Nano ID (Python)

py-nanoid is the Python port of the popular JavaScript Nano ID library: a small, dependency-free ID generator that produces URL-safe unique strings using a larger alphabet (A-Za-z0-9_-) than UUID, shrinking typical ID length from 36 characters to 21 while keeping a comparable collision probability to UUID v4.

The library exposes both a cryptographically secure generate() (backed by Python’s secrets/os.urandom-based random APIs) and a faster non_secure_generate() for cases where cryptographic strength isn’t required, plus support for custom alphabets and custom ID lengths.

What You Get

• A generate() function producing cryptographically secure, URL-friendly 21-character IDs by default.
• A non_secure_generate() variant using a faster, non-cryptographic random source for cases where security isn’t required.
• Support for custom ID length via a size argument, trading collision resistance for shorter IDs.
• Support for a custom alphabet (e.g. digits-only, hex) instead of the default URL-safe character set.
• A minimal, dependency-free implementation (~70 lines across the whole package) that’s easy to audit.

Common Use Cases

• Generating short, URL-safe unique identifiers for use in URLs, slugs, or short links.
• Creating primary keys or public-facing record IDs that are more compact than UUIDs.
• Generating session tokens or one-off identifiers where a smaller, still-collision-resistant ID is preferred over a full UUID.
• Producing test fixtures or mock data that need quick, unique string identifiers.

Under The Hood

Architecture: The package is deliberately minimal — generate.py implements the secure path using Python’s cryptographically strong random byte source, non_secure_generate.py implements the faster non-cryptographic variant, algorithm.py holds the shared bit-masking algorithm that maps random bytes onto the target alphabet without modulo bias, and method.py/resources.py provide the default alphabet and size constants. There is no class hierarchy or plugin system; each generation mode is a small, standalone function.

Tech Stack: Pure Python with no third-party runtime dependencies, relying only on the standard library’s secure random primitives; requirements.txt lists only development/test tooling.

Code Quality: test/ mirrors the package 1:1 with a test module per source file (algorithm_test.py, generate_test.py, method_test.py, non_secure_test.py, url_test.py, plus an integration nanoid_test.py), and CI runs via CircleCI. The codebase’s small size (roughly 70 lines of implementation) makes the whole library easy to read end-to-end in a few minutes, though the project has seen very little maintenance activity in recent years despite continued heavy download volume.

API Design: The library exposes exactly two top-level functions (generate, non_secure_generate) with optional positional/keyword arguments for alphabet and size, directly mirroring the original JavaScript Nano ID’s nanoid()/customAlphabet() API shape, which keeps the mental model identical for anyone already familiar with Nano ID from the JS ecosystem.