Repository navigation
This release adds a SQLAlchemy column type, support for Python 3.15, and a batch of fixes that make invalid input fail with clear errors instead of OverflowErrors, broken objects or tracebacks.
Added
-
SQLAlchemy and SQLModel support. The new
ulid.sqlalchemy.ULIDTypecolumn type storesULIDvalues and always loads them back asULID. Install it with the new extra:pip install python-ulid[sqlalchemy]
from sqlalchemy import select from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column from ulid import ULID from ulid.sqlalchemy import ULIDType class Base(DeclarativeBase): pass class Order(Base): __tablename__ = "orders" id: Mapped[ULID] = mapped_column(ULIDType(), primary_key=True, default=ULID) customer: Mapped[str] # ULIDs sort by creation time, so the newest order is simply the largest ID newest = session.scalars(select(Order).order_by(Order.id.desc())).first() # Filters accept a ULID, a UUID, bytes, an int or any string representation session.scalars(select(Order).where(Order.id == "01KA6Q4C1D8M2Z3N4P5Q6R7S8T"))
By default values are stored as a UUID: a native
UUIDcolumn on PostgreSQL andCHAR(32)elsewhere. UseULIDType(storage="binary")for a compactBINARY(16)column, orULIDType(storage="string")to see the familiar 26-character ULID in your database. All storage options keep the database sort order identical to the ULID order (except for SQL Server's nativeUNIQUEIDENTIFIER).With SQLModel,
ULIDworks as a field type directly; only the column type needs to be passed:from sqlmodel import Field, SQLModel class Hero(SQLModel, table=True): id: ULID = Field(default_factory=ULID, primary_key=True, sa_type=ULIDType) name: str
-
Python 3.15 is now officially supported and tested.
Fixed
-
import ulidworks in frozen applications. Applications built with cx_Freeze or PyInstaller often leave out package metadata, which madeimport ulidfail withPackageNotFoundError. The version is now written into the package at build time. -
ULID.parse(int(ulid))now round-trips for every ULID. Previously only integers with exactly 37 digits were recognised as a full ULID, which covers ULIDs created between roughly 1996 and 2232 @KuljeetSinghXDA. -
Clear
ValueErrors for out-of-range values instead of a bareOverflowError:>>> ULID.from_timestamp(-1.0) ValueError: Value is below minimum possible timestamp >>> ULID.from_int(2**128) ValueError: Value is outside the 128-bit range of a ULID
-
Pydantic validation always raises
ValidationErrorfor unsupported values such as adict, afloator an out-of-rangeint, instead of leakingTypeErrororOverflowError@KuljeetSinghXDA. -
The
ULIDconstructor validates its input.bytearrayandmemoryview(as returned by many database drivers) are accepted and stored as immutablebytes. Other types, such as a 16-characterstr, now raiseTypeErrorinstead of creating a broken object @KuljeetSinghXDA. -
The
ulidCLI reports invalid input without a traceback:$ ulid show not-a-ulid ulid: error: Encoded ULID has to be exactly 26 characters long.
Invalid input exits with status
2, like other command-line argument errors. -
ULID.from_datetimeandULID.from_timestampno longer land one millisecond early when a value on an exact millisecond multiplies to just below that integer as a float @arieleven.
Contributors
Thanks to @KuljeetSinghXDA and @arieleven for their contributions to this release!
Full changelog: 4.1.0...4.2.0