cuid

library0.4pypypi✓ verified 24d ago

cuid.py is a Python implementation of the original CUID (Collision-resistant Unique IDentifier) standard, designed for horizontally scalable and fast unique ID generation. It aims to provide portable and sequentially-ordered unique identifiers. The current version is 0.4. The upstream CUID standard (v1), which this library implements, has been deprecated in favor of CUID2 due to security considerations, so this library is not actively developed beyond maintenance for the deprecated standard.

serialization

pip install cuid

github ↗package ↗

INSTALL

IMPORT

SIG · CUID

cuid

serializationpythonv0.4

Install

2.4s avg

Import

20ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.020s · 19.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.020s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cuid

✓ import cuid

✗ from cuid import cuid

While 'from cuid import cuid' works, it can lead to confusion if you also use 'cuid.slug()'. Importing the module directly and accessing functions via 'cuid.cuid()' or 'cuid.slug()' is clearer.

Demonstrates how to generate a standard CUID and a shorter CUID slug using the library. Note the warning about slugs for primary keys.

import cuid # Generate a standard CUID my_cuid = cuid.cuid() print(f"Generated CUID: {my_cuid}") # Generate a 'slug' (shorter, less collision-resistant, not for primary keys) my_slug = cuid.slug() print(f"Generated CUID slug: {my_slug}")

Debug

Known issues

breakingThe original CUID standard (v1), implemented by this library, has been officially deprecated upstream due to security concerns. It leaks timestamps and other potentially predictable information, making it unsuitable for security-sensitive applications where IDs should not be guessable or reveal creation order. The successor is CUID2.

fix

For new projects or security-sensitive applications, consider migrating to `cuid2` (a separate Python package implementing CUID2) or another ID generation scheme that offers stronger security guarantees. The `cuid2` library offers similar benefits (collision resistance, scalability) with enhanced security.

affects: All versions of `cuid` (0.x)

deprecatedThis Python library implements the deprecated CUID v1 standard. While functional, it is no longer recommended for new development, especially where security or information leakage are concerns. The project appears to be in maintenance mode for this deprecated standard.

fix

Evaluate whether your use case truly requires CUID v1 characteristics. If not, switch to `cuid2` for improved security. If bound to CUID v1, be aware of its limitations and deprecation status.

affects: All versions of `cuid` (0.x)

gotchaThe `cuid.slug()` function generates shorter, URL-friendly identifiers. However, slugs have less random data, less room for the counter and fingerprint, which increases the probability of collisions. They are explicitly NOT recommended for use as database unique IDs or primary keys where strong collision resistance is critical.

fix

Only use `cuid.slug()` for non-critical, human-readable identifiers such as URL slugs. Always use the full `cuid.cuid()` for database primary keys or other scenarios requiring high collision resistance.

affects: All versions of `cuid` (0.x)

gotchaCUIDs, including those generated by `cuid.py`, are string-based identifiers. When used as database primary keys, ensure that database columns are appropriately indexed for optimal performance. They are not intrinsically integers and may not perform as well with auto-incrementing integer primary key optimizations in some databases.

fix

Ensure database columns storing CUIDs are properly indexed as strings/text. If strict sequential (gap-less) numbers or extremely small storage footprints are critical, consider auto-incrementing integers or other ID types, respectively.

affects: All versions of `cuid` (0.x)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cuid'

The 'cuid' library is not installed in the current Python environment.

fix

Install the 'cuid' library using pip: 'pip install cuid'.

ImportError: cannot import name 'cuid' from 'cuid'

Incorrect import statement; 'cuid' is a module, not a class or function.

fix

Use the correct import statement: 'import cuid'.

AttributeError: module 'cuid' has no attribute 'generate'

The 'cuid' module does not have a 'generate' function; the correct function is 'cuid.cuid()'.

fix

Generate a CUID using: 'import cuid; id = cuid.cuid()'.

AttributeError: module 'cuid' has no callable object

The user attempted to call the 'cuid' module directly as a function (e.g., `cuid()`) instead of calling the `cuid()` or `slug()` functions within the module.

fix

Access the ID generation function via `cuid.cuid()` for a full CUID or `cuid.slug()` for a shorter slug: `import cuid; new_id = cuid.cuid()`

TypeError: 'module' object is not callable

After 'import cuid', the module itself is not a callable function; the CUID generation function is nested within it.

fix

import cuid
print(cuid.cuid())

Upgrade

Version history

0.4latest on PyPI · released Mar 6, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttp://github.com/necaris/cuid.py ↗

packagehttps://pypi.org/project/cuid/ ↗