Skip to content

4.2.0

Latest

Choose a tag to compare

@mdomke mdomke released this 17 Nov 12:13
· 3 commits to main since this release
4afe4bb

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.ULIDType column type stores ULID values and always loads them back as ULID. 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 UUID column on PostgreSQL and CHAR(32) elsewhere. Use ULIDType(storage="binary") for a compact BINARY(16) column, or ULIDType(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 native UNIQUEIDENTIFIER).

    With SQLModel, ULID works 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 ulid works in frozen applications. Applications built with cx_Freeze or PyInstaller often leave out package metadata, which made import ulid fail with PackageNotFoundError. 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 bare OverflowError:

    >>> 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 ValidationError for unsupported values such as a dict, a float or an out-of-range int, instead of leaking TypeError or OverflowError @KuljeetSinghXDA.

  • The ULID constructor validates its input. bytearray and memoryview (as returned by many database drivers) are accepted and stored as immutable bytes. Other types, such as a 16-character str, now raise TypeError instead of creating a broken object @KuljeetSinghXDA.

  • The ulid CLI 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_datetime and ULID.from_timestamp no 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