o192 — Python

Python reference implementation of ORION-192 — Ordered, Resilient, Independent, Opaque-ish, Non-coordinated 192-bit identifiers for distributed systems.

ORION-192 produces fixed-width, URL-safe, lexicographically sortable IDs without a central coordinator, worker ID, or machine identity in the wire format. This package is byte-compatible with the JavaScript and Rust reference implementations.

Highlights

• Zero runtime dependencies. The CSPRNG comes from the standard library (os.urandom / secrets).
• Fully typed, ships a py.typed marker, and is mypy --strict clean.
• Supports CPython 3.9+ and PyPy; pure-Python source, no native build step.
• Strictly monotonic within a generator instance, including across clock rollback.
• Wire-compatible with the JavaScript and Rust packages — same 24-byte layout, same 32-character canonical form.

Install

python -m pip install o192

Quick start

from o192 import orionid, OrionIdGenerator, parse, is_valid

# 1. One-shot helper
print(orionid())  # → "0Pu_iDKVO9012BwIEM28oFojPMWLWeLU"

# 2. Long-lived generator (recommended for sustained throughput)
gen = OrionIdGenerator(epoch_ms=1_735_689_600_000)  # 2025-01-01 UTC
a, b = gen.next(), gen.next()
assert a < b  # strictly monotonic per generator

# 3. Parse and inspect
if is_valid(a):
    view = parse(a, epoch_ms=1_735_689_600_000)
    print(view.unix_datetime, view.fraction4096, view.counter)

Command-line

The package installs an o192 console entry point:

o192            # prints a single ORION-192 id
python -m o192  # equivalent

API

Top-level helpers

def orionid() -> str: ...
def parse(identifier: str, *, epoch_ms: int = 0) -> ParsedOrionId: ...
def is_valid(identifier: str) -> bool: ...
def encode_sortable64(data: bytes | bytearray | memoryview) -> str: ...
def decode_sortable64(identifier: str) -> bytes: ...

OrionIdGenerator

OrionIdGenerator(
    *,
    epoch_ms: int = 0,                                   # private epoch in ms
    random_pool_bytes: int = 65_536,                     # 14 .. 16 MiB
    clock: Callable[[], int] | None = None,              # test-only
    random_bytes: Callable[[int], bytes] | None = None,  # test-only
)

generator.next() -> str                       # 32-char canonical string
generator.next_bytes() -> bytes               # 24-byte binary form
generator.parse(identifier: str) -> ParsedOrionId

# Read-only telemetry
generator.epoch_ms: int
generator.last_time_key: int                  # -1 before the first call
generator.counter: int                        # 20-bit counter
generator.clock_rollbacks: int                # observed backward jumps
generator.synthetic_ticks: int                # counter-overflow advances

ParsedOrionId

@dataclass(frozen=True, slots=True)
class ParsedOrionId:
    id: str                       # original canonical string
    binary: bytes                 # 24-byte binary form
    unix_ms: int                  # relative_ms + epoch_ms
    unix_datetime: datetime | None
    relative_ms: int              # 48-bit ms field
    fraction4096: int             # 12-bit sub-ms fraction
    approx_sub_ms: float          # fraction4096 / 4096, in ms
    counter: int                  # 20-bit counter
    random_hex: str               # 14-byte tail as lower-case hex

Errors

class OrionIdError(ValueError):
    code: str
    # One of: INVALID_LENGTH, INVALID_CHARACTER, INVALID_OPTION,
    #         TIMESTAMP_OVERFLOW, COUNTER_OVERFLOW, RANDOM_FAILURE

OrionIdError subclasses ValueError, so existing except ValueError handlers continue to work. Inspect error.code for programmatic handling.

Performance

A single OrionIdGenerator produces roughly 400 k – 1 M IDs/second on a modern laptop under CPython, and noticeably more under PyPy. Numbers are indicative — run the bundled benchmark on your target hardware:

python ../../benchmarks/python_bench.py

Status

ORION-192 is at spec v0 — implementation-complete, cross-language conformant, and wire-frozen. See the project status for the full stability statement.

Specification & related

• Specification (SPEC.md) — normative wire format and algorithm.
• Design rationale (docs/RATIONALE.md) — why 192 bits, why this layout.
• Storage guide (docs/DATABASE.md) — column types, collation, indexing.
• Security policy (SECURITY.md) — threat model and disclosure process.
• Sibling implementations: JavaScript · Rust.

License

Licensed under the MIT License — Copyright © 2026 Lam Hieu and contributors.