or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-nanoid

A tiny, secure, URL-friendly, unique string ID generator for Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/nanoid@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-nanoid@2.0.0

index.mddocs/

Nanoid

A tiny, secure, URL-friendly, unique string ID generator for Python. Nanoid uses cryptographically strong random APIs and generates compact IDs with a larger alphabet than UUID, reducing ID size from 36 to 21 characters while maintaining collision probability similar to UUID v4.

Package Information

  • Package Name: nanoid
  • Package Type: pypi
  • Language: Python
  • Installation: pip install nanoid

Core Imports

from nanoid import generate, non_secure_generate

Basic Usage

from nanoid import generate

# Generate a secure 21-character ID with default alphabet
id = generate()  # => "NDzkGoTCdRcaRyt7GOepg"

# Generate shorter ID (higher collision probability)
id = generate(size=10)  # => "IRFa-VaY2b"

# Generate ID with custom alphabet (positional arguments)
id = generate('1234567890abcdef', 10)  # => "4f9zd13a42"

# Generate ID with custom alphabet (keyword arguments)
id = generate(alphabet='1234567890abcdef', size=10)  # => "4f9zd13a42"

For non-secure, fast generation:

from nanoid import non_secure_generate

# Fast, non-cryptographic generation
id = non_secure_generate()
id = non_secure_generate('1234567890abcdef', 10)  # positional
id = non_secure_generate(alphabet='1234567890abcdef', size=10)  # keyword

Capabilities

Secure ID Generation

Generate cryptographically secure, URL-friendly unique string IDs using strong random APIs with customizable alphabet and length.

def generate(alphabet=alphabet, size=size):
    """
    Generate a cryptographically secure unique string ID.
    
    Parameters:
    - alphabet (str, optional): Custom alphabet for ID generation.
      Defaults to URL-friendly 64-character alphabet from nanoid.resources.
    - size (int, optional): Length of generated ID. Defaults to 21.
    
    Returns:
    str: Generated unique ID string
    
    Usage:
    # Using defaults
    generate()
    
    # Positional arguments
    generate('0123456789abcdef', 10)
    
    # Keyword arguments  
    generate(alphabet='0123456789abcdef', size=10)
    generate(size=10)
    
    Notes:
    - Uses os.urandom() for cryptographically strong randomness
    - Default settings provide collision probability similar to UUID v4
    - Default alphabet excludes problematic URL characters like .(),-
    """

Fast Non-Secure ID Generation

Generate IDs quickly using pseudo-random generation for non-security-critical applications where performance is prioritized over cryptographic strength.

def non_secure_generate(alphabet=alphabet, size=size):
    """
    Generate a fast, non-secure unique string ID.
    
    Parameters:
    - alphabet (str, optional): Custom alphabet for ID generation.
      Defaults to URL-friendly 64-character alphabet from nanoid.resources.
    - size (int, optional): Length of generated ID. Defaults to 21.
    
    Returns:
    str: Generated unique ID string
    
    Usage:
    # Using defaults
    non_secure_generate()
    
    # Positional arguments
    non_secure_generate('0123456789abcdef', 10)
    
    # Keyword arguments  
    non_secure_generate(alphabet='0123456789abcdef', size=10)
    non_secure_generate(size=10)
    
    Notes:
    - Uses random.random() for fast pseudo-random generation
    - Not cryptographically secure - use only when security is not required
    - Significantly faster than secure generation for high-volume use cases
    """

Constants

The package provides access to default configuration constants:

# Default URL-friendly alphabet (64 characters)
alphabet = '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'

# Default ID length for UUID v4-like collision probability
size = 21

Access constants:

from nanoid.resources import alphabet, size

print(f"Default alphabet: {alphabet}")
print(f"Default size: {size}")

Usage Examples

Web Application IDs

from nanoid import generate

# Generate user session IDs
session_id = generate()

# Generate short resource identifiers
post_id = generate(size=12)

# Generate database-safe IDs with custom alphabet
db_id = generate('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', 16)

Custom Alphabets for Specific Use Cases

from nanoid import generate

# Numeric-only IDs
numeric_id = generate('0123456789', 10)

# Lowercase alphanumeric
lower_id = generate('0123456789abcdefghijklmnopqrstuvwxyz', 15)

# Base64-like alphabet
base64_id = generate('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/', 22)

Performance Considerations

from nanoid import generate, non_secure_generate

# For security-critical applications (recommended)
secure_token = generate()

# For high-volume, non-security-critical use (faster)
temp_id = non_secure_generate()

# Batch generation example
secure_ids = [generate(size=10) for _ in range(1000)]
fast_ids = [non_secure_generate(size=10) for _ in range(10000)]

Security Features

  • Cryptographically Secure: Uses os.urandom() for strong randomness in generate()
  • URL-Safe: Default alphabet excludes characters that require URL encoding
  • Collision Resistant: Default 21-character length provides ~2^126 possible combinations
  • Distribution Testing: Library includes tests to verify symbol distribution uniformity

Collision Probability

The default configuration (21 characters, 64-symbol alphabet) provides collision probability similar to UUID v4:

  • ~1% probability after generating ~7×10^15 IDs
  • Use size calculator at https://zelark.github.io/nano-id-cc/ to determine appropriate ID length for your use case

Error Handling

Both functions are designed to be robust:

  • Invalid alphabet: Empty string or None will cause errors
  • Invalid size: Negative or zero size will cause errors
  • Large sizes: Memory usage scales linearly with size parameter