Skip to content

ID Module

The id module provides utilities for generating and validating entity IDs. It primarily uses ULID (Universally Unique Lexicographically Sortable Identifier) as the format for IDs, with fallback to UUID4 if the ULID library is not available.

Key Features

  • ULID Generation: Creates sortable, unique identifiers
  • Type Safety: Provides the EntityId type for improved type checking
  • Validation: Tools to validate ID format

API Reference

ID generation and validation utilities.

This module provides functions for generating and validating unique entity IDs. It uses ULID (Universally Unique Lexicographically Sortable Identifier) as the primary ID format, with fallback to UUID4 if the ULID library is not available.

Functions

cast_entity_id(value)

Cast a string to an EntityId type.

Parameters:

Name Type Description Default
value str

The string to cast

 required

Returns:

Name Type Description
EntityId EntityId

The string as an EntityId
Source code in spryx_core/id.py 
55
56
57
58
59
60
61
62
63
64
65
def cast_entity_id(value: str) -> EntityId:
    """
    Cast a string to an EntityId type.

    Args:
        value: The string to cast

    Returns:
        EntityId: The string as an EntityId
    """
    return EntityId(value)

generate_entity_id()

Generate a new unique entity ID.

Returns:

Name Type Description
EntityId EntityId

A new ULID as a string (falls back to UUID4 if ULID is not available)
Source code in spryx_core/id.py 
29
30
31
32
33
34
35
36
37
38
39
def generate_entity_id() -> EntityId:
    """
    Generate a new unique entity ID.

    Returns:
        EntityId: A new ULID as a string (falls back to UUID4 if ULID is not available)
    """
    if _has_ulid:
        # Use ulid package to generate a new ULID
        return EntityId(str(ulid_lib.ULID()))
    return EntityId(str(uuid.uuid4()))

is_valid_ulid(value)

Check if a string is a valid ULID.

Parameters:

Name Type Description Default
value str

The string to validate

 required

Returns:

Name Type Description
bool bool

True if the string is a valid ULID, False otherwise
Source code in spryx_core/id.py 
42
43
44
45
46
47
48
49
50
51
52
def is_valid_ulid(value: str) -> bool:
    """
    Check if a string is a valid ULID.

    Args:
        value: The string to validate

    Returns:
        bool: True if the string is a valid ULID, False otherwise
    """
    return bool(_ULID_RE.fullmatch(value))

Usage Examples

Basic ID Generation

from spryx_core import generate_entity_id

# Generate a new unique ID
entity_id = generate_entity_id()
print(entity_id)  # Example: 01HNJG7VWTZA0CGTJ9T7WG9CPB

Validation

from spryx_core import is_valid_ulid

# Check if an ID is in valid ULID format
valid_id = "01HNJG7VWTZA0CGTJ9T7WG9CPB"
invalid_id = "not-a-valid-id"

print(is_valid_ulid(valid_id))    # True
print(is_valid_ulid(invalid_id))  # False

Type Safety

from spryx_core import EntityId, cast_entity_id
from typing import Dict

# Use EntityId as a type hint
def get_user(user_id: EntityId) -> Dict:
    # Function implementation...
    return {"id": user_id, "name": "Test User"}

# Cast a string to EntityId type
user_id = cast_entity_id("01HNJG7VWTZA0CGTJ9T7WG9CPB")
user = get_user(user_id)

ULID vs UUID

ULIDs offer several advantages over UUIDs:

  1. Sortability: ULIDs are lexicographically sortable, meaning they can be sorted as strings
  2. Time-based: The first part of a ULID encodes the creation timestamp
  3. Human readability: ULIDs use Crockford's base32 encoding for improved readability
  4. Compact representation: 26 characters vs 36 for UUID

If the ulid package is not installed, the library will automatically fall back to generating UUID4 strings instead.