v0.3.7

[akhundMurad]

Release v0.3.7 -- Rust-powered performance

This release is a big step toward “production-grade” TypeID usage in Python: the core implementation is now tuned for real-world throughput, packaging is aligned with native builds, and the project ships with reproducible benchmarks and clearer docs. ⚡

The headline change is a Rust-accelerated base32 codec (via a new typeid._base32 extension) and a move to uuid-utils for UUIDv7 generation. Together with a set of internal optimizations (lazy UUID materialization, single-pass suffix validation, and cached string rendering), this brings substantial speedups in the hot paths. 🚀 Benchmarks included in-repo show mean times improving from ~3.47 µs → ~0.70 µs for generation, ~2.08 µs → ~1.30 µs for parsing, and ~5.52 µs → ~2.25 µs for an end-to-end workflow (generate → stringify → parse).

Operationally, CI/CD has been reorganized around PR-focused tests and a tag-driven publish workflow. Publishing now builds wheels for multiple OSes and Python versions, sanity-checks native imports, uploads artifacts, publishes to PyPI, and then deploys docs. Documentation has been refreshed across the board (Quickstart tweaks, expanded explain docs, and a new Performance section that pulls directly from the benchmark README), and contributor guidance now explicitly covers the optional Rust acceleration workflow, benchmark discipline, and expectations around Python fallback.

Breaking changes (read before upgrading) ⚠️

This version changes a few foundational pieces that may affect downstream builds and integrations:

• Build backend is now maturin (native extension) instead of hatchling. If you build from source (sdist, editable installs, constrained build environments), you may now need Rust tooling available, depending on how you consume the package.
• UUID dependency switched from uuid6 to uuid-utils, and the project’s UUID types in tests/CLI have been updated accordingly.
• typeid.base32 API now operates on bytes (and is implemented by the Rust extension). Code that passed list[int] or expected decode() to return a list will need adjustment.

Migration guide

If you only install from PyPI wheels, the main work is adapting code that touches UUID helpers and base32 directly. If you build from source, also review the packaging notes below.

1) Replace uuid6 usage with uuid-utils

# before
from uuid6 import uuid7, UUID

# after
from uuid_utils import uuid7, UUID

If you pass UUID objects into TypeID.from_uuid(), ensure they’re uuid_utils.UUID instances (or compatible) in your codebase.

2) Update base32 encode/decode call sites (if you used them directly)

# before
encoded = base32.encode(list(u.bytes))
raw = bytes(base32.decode(encoded))

# after
encoded = base32.encode(u.bytes)      # takes bytes
raw = base32.decode(encoded)          # returns bytes

3) Packaging / builds (important for CI, Linux distros, and source installs)

• If you build from source, make sure your environment supports PEP 517 builds with maturin and has a Rust toolchain available when required.
• CI publishing is now tag-driven (v*) and builds wheels across Linux/macOS/Windows with a native import sanity check.

Notable additions and improvements

A few highlights worth calling out without turning this into a changelog dump:

• New TypeID.created_at (best-effort UTC datetime for UUIDv7; safely None for nil/non-v7 values), plus uuid_bytes and internal caching/slots for lower overhead.
• Reproducible benchmark suite under bench/, committed raw JSON results, and a docs page that includes the benchmark narrative and numbers.
• CI workflows simplified: PR tests now build/install the native extension during checks, and publishing handles wheels, sdist, PyPI, and docs deploy in one pipeline.

If you maintain downstream packages or internal tooling that relies on the old build backend, UUID library, or base32 types, treat this as a “review-required” upgrade. Once migrated, you should see noticeably faster ID generation and parsing with no change to the core TypeID string format or everyday usage.

---

This discussion was created from the release v0.3.7.