v0.3.7

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.

v0.3.5 (YANKED)

Release v0.3.5 — Performance, Reliability, and CI Improvements

This release is a major step forward in performance, robustness, and release automation for typeid-python. It introduces optional Rust acceleration, reproducible benchmarks, and a significantly improved CI/CD pipeline—while maintaining full backward compatibility and a pure-Python fallback.

---

Highlights

Optional Rust Acceleration

• New opt-in Rust backend for Base32 encode/decode and UUIDv7 generation.

• Automatically used when available; pure Python fallback remains the default guarantee.

• Enabled via:

  pip install typeid-python[rust]

Measurable Performance Gains

• ~5× faster TypeID generation
• ~1.6× faster parsing
• ~2.5× faster end-to-end workflows
• Benchmarks are reproducible, committed as raw JSON, and documented in detail.

Reproducible Benchmark Suite

• New bench/ directory with:

  • pytest-benchmark-based tests
  • versioned benchmark snapshots
  • clear comparison methodology

• Performance claims are now fully auditable.

Smarter Internals

• Lazy UUID materialization (decode only when needed)
• Single-pass suffix validation and decode
• Cached string representations
• Cleaner UUID backend abstraction with explicit override support

Improved Semantics

• New created_at property for UUIDv7-backed TypeIDs

• Correct handling of:

  • nil UUIDs
  • non-v7 UUIDs
  • unexpected UUID backends

• typeid explain now accurately reflects sortability and timestamps

CI / Release Pipeline Overhaul

• Docs and PyPI publishing now run only on version tags

• New multi-platform wheel builds (Linux, macOS, Windows)

• Rust wheels built automatically when applicable

• Tests and docs are required gates before publishing

• Clear separation between:

  • PR checks
  • tests
  • docs
  • release publishing

Documentation Improvements

• New Performance documentation section
• Expanded Rust acceleration guidance
• Clear benchmark philosophy and methodology
• Updated Quickstart and Explain docs
• Improved CONTRIBUTING guide with explicit Rust-optional guarantees

Compatibility & Safety

• No breaking API changes
• Existing users are unaffected unless opting into extras
• Python-only environments remain fully supported
• Lockfile discipline and validation tightened

---

As always, feedback, benchmarks, and PRs are welcome.
This release focuses on making performance improvements transparent, measurable, and optional—without compromising safety or clarity.

Full Changelog: v0.3.4...v0.3.5

v0.3.4

🚀 v0.3.4 — Explainable ID, Documentation, DX Improvements & New Features

This release focuses on improving developer experience, documentation, and extensibility, while adding powerful new features to typeid-python.

✨ What’s New

• Full documentation site
  A complete docs site is now available, with improved CLI docs and richer docstrings for easier onboarding and discovery.
  → PR: #50

• typeid explain — Human-readable schema explanations
  A new command that turns TypeID schemas into clear, human-friendly explanations.
  → PR: #46

• Reusable TypeID factories with caching
  Improve performance and reuse with built-in factory support and caching.
  → PR: #48

• UV support
  Native support for uv package management 🎉
  → PR: #47

🧹 Maintenance & Cleanup

• Replaced flake8 with ruff
• Updated CONTRIBUTING.md
• Added twine as a dependency
  → PR: #44

---

🔎 Full Changelog

Compare all changes here:
v0.3.3...v0.3.4

v0.3.3

🚀 What's New

⚠️ Important Changes

• TypeID now supports Python 3.14.
• Support for Python 3.9 has been dropped.

🔧 Enhancements & Updates

• Added a new typeid CLI by @iloveitaly (PR #22)
• Improved TypeID’s repr to be executable by introducing .from_string() by @iloveitaly (PR #23)
• Added support for passing uuid.UUID directly to TypeID.from_uuid by @rbuffat (PR #21)
• Updated dependencies and improved project configuration by @akhundMurad (PR #26)

🙌 New Contributors

• @iloveitaly made their first contribution in PR #22
• @rbuffat made their first contribution in PR #21

Full Changelog:
v0.3.2...v0.3.3

v0.3.2

What's Changed

• Removed Python 3.8 Testing. The GitHub Actions workflow has been updated to remove tests for Python 3.8. Supported Python versions now include: 3.9, 3.10, 3.11, 3.12.
• Add py.typed marker by @leonsmith in #19
• chore: enable catching all TypeID exceptions by @saltmade in #17

Depndency updates

poetry.lock updated with several dependencies changes:

certifi downgraded to 2024.6.2.
charset-normalizer downgraded to 3.3.2.
click downgraded to 8.1.7.
exceptiongroup downgraded to 1.2.1.
idna downgraded to 3.7.
mypy downgraded to 1.10.0.
packaging downgraded to 24.1.
platformdirs downgraded to 4.2.2.
pyyaml downgraded to 6.0.1.

New Contributors

• @leonsmith made their first contribution in #19
• @saltmade made their first contribution in #17

Full Changelog: v0.3.1...v0.3.2

v0.3.1

What's Changed

• fix: Improve type prefix and suffix extraction by @iron3oxide in #13
• fix: Remove the strict version definition for uuid6 lib

New Contributors

• @iron3oxide made their first contribution in #13

Full Changelog: v0.3.0...v0.3.1

v0.3.0

What's Changed

• Updated prefix validation to match type-id regex by @v99101 in #11
• Improvements and fixes by @attevaltojarvi in #10

New Contributors

• @v99101 made their first contribution in #11
• @attevaltojarvi made their first contribution in #10

Full Changelog: v0.2.3...v0.3.0

v0.2.3

What's Changed

• Small refactoring by @akhundMurad in #7
• Add comparatives __gt__ and __ge__ by @oselz in #8

New Contributors

• @oselz made their first contribution in #8

Full Changelog: v0.2.2...v0.2.3

v0.2.2

What's Changed

• add classmethod constructors by @beheh in #6
• make compatible with sqlalchemy by @beheh in #5

New Contributors

• @beheh made their first contribution in #6

Full Changelog: v0.2.1...v0.2.2

v0.2.1

What's Changed

• Implement a CLI tool by @akhundMurad in #4

Full Changelog: v0.2.0...v0.2.1