{"author":null,"author_email":"Martin Domke ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Environment :: Console","Intended Audience :: Developers","License :: OSI Approved :: MIT License","Operating System :: MacOS :: MacOS X","Operating System :: POSIX :: Linux","Programming Language :: Python","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.9","Topic :: Software Development :: Libraries"],"description":"\n\nA ``ULID`` is a *universally unique lexicographically sortable identifier*. It is\n\n* 128-bit compatible with ``UUID``\n* 1.21e+24 unique ULIDs per millisecond\n* Lexicographically sortable!\n* Canonically encoded as a 26 character string, as opposed to the 36 character UUID\n* Uses Crockford's base32 for better efficiency and readability (5 bits per character)\n* Case insensitive\n* No special characters (URL safe)\n\nIn general the structure of a ULID is as follows:\n\n.. code-block:: text\n\n 01AN4Z07BY 79KA1307SR9X4MV3\n |----------| |----------------|\n Timestamp Randomness\n 48bits 80bits\n\n\nFor more information have a look at the original\n`specification `_.\n\n.. teaser-end\n\n.. installation-begin\n\nInstallation\n------------\n\nUse ``pip`` to install the library\n\n.. code-block:: bash\n\n $ pip install python-ulid\n\nto include Pydantic support install the optional dependency like so\n\n.. code-block:: bash\n\n $ pip install python-ulid[pydantic]\n\n.. installation-end\n\n.. usage-begin\n\nBasic Usage\n-----------\n\nCreate a new ``ULID`` object from the current timestamp\n\n.. code-block:: pycon\n\n >>> from ulid import ULID\n >>> ULID()\n ULID(01E75HZVW36EAZKMF1W7XNMSB4)\n\nor use one of the named constructors\n\n.. code-block:: pycon\n\n >>> import time, datetime\n >>> ULID.from_timestamp(time.time())\n ULID(01E75J1MKKWMGG0N5MBHFMRC84)\n >>> ULID.from_datetime(datetime.datetime.now())\n ULID(01E75J2XBK390V2XRH44EHC10X)\n\nThere are several options for encoding the ``ULID`` object\n(e.g. string, hex, int, bytes, UUID):\n\n.. code-block:: pycon\n\n >>> str(ulid)\n '01BTGNYV6HRNK8K8VKZASZCFPE'\n >>> ulid.hex\n '015ea15f6cd1c56689a373fab3f63ece'\n >>> int(ulid)\n 1820576928786795198723644692628913870\n >>> bytes(ulid)\n b'\\x01^\\xa1_l\\xd1\\xc5f\\x89\\xa3s\\xfa\\xb3\\xf6>\\xce'\n >>> ulid.to_uuid()\n UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')\n\nIt is also possible to directly access the timestamp component of a ``ULID``,\neither in UNIX epoch or as ``datetime.datetime``\n\n.. code-block:: pycon\n\n >>> ulid.timestamp\n 1505945939.153\n >>> ulid.datetime\n datetime.datetime(2017, 9, 20, 22, 18, 59, 153000, tzinfo=datetime.timezone.utc)\n\n.. usage-end\n\n.. pydantic-begin\n\nPydantic integration\n---------------------\n\nThe ``ULID`` class can be directly used for the popular data validation library\n`Pydantic `_ like so\n\n.. code-block:: python\n\n from pydantic import BaseModel\n from ulid import ULID\n\n\n class Model(BaseModel):\n ulid: ULID\n\n model = Model(ulid=\"DX89370400440532013000\") # OK\n model = Model(ulid=\"not-a-ulid\") # Raises ValidationError\n\n.. pydantic-end\n\n.. cli-begin\n\nCommand line interface\n-----------------------\n\nThe package comes with a CLI interface that can be invoked either by the script name\n``ulid`` or as python module ``python -m ulid``. The CLI allows you to generate, inspect\nand convert ULIDs, e.g.\n\n.. code-block:: bash\n\n $ ulid build\n 01HASFKBN8SKZTSVVS03K5AMMS\n\n $ ulid build --from-datetime=2023-09-23T10:20:30\n 01HB0J0F5GCKEXNSWVAD5PEAC1\n\n $ ulid show 01HASFKBN8SKZTSVVS03K5AMMS\n ULID: 01HASFKBN8SKZTSVVS03K5AMMS\n Hex: 018ab2f9aea8ccffacef7900e6555299\n Int: 2049395013039097460549394558635823769\n Timestamp: 1695219822.248\n Datetime: 2023-09-20 14:23:42.248000+00:00\n\nThere are several flags to select specific output formats for the ``show`` command, e.g.\n\n\n.. code-block:: bash\n\n $ ulid show --datetime 01HASFKBN8SKZTSVVS03K5AMMS\n 2023-09-20 14:23:42.248000+00:00\n\nThe special character ``-`` allows to read values from ``stdin`` so that they can be piped. E.g.\n\n.. code-block:: bash\n\n $ echo 01HASFKBN8SKZTSVVS03K5AMMS | ulid show --uuid -\n 018ab2f9-aea8-4cff-acef-7900e6555299\n\n $ date --iso-8601 | python -m ulid build --from-datetime -\n 01HAT9PVR02T3S13XB48S7GEHE\n\nFor a full overview of flags for the ``build`` and ``show`` commands use the ``--help`` option\n(e.g. ``ulid show --help``).\n\n.. cli-end\n\nOther implementations\n---------------------\n\n* `ahawker/ulid `_\n* `valohai/ulid2 `_\n* `mdipierro/ulid `_\n* `oklog/ulid `_\n* `ulid/javascript `_\n* `RobThree/NUlid `_\n* `imdario/go-ulid `_\n","description_content_type":"text/x-rst","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":null,"license":null,"license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"python-ulid","package_url":"https://pypi.org/project/python-ulid/","platform":null,"project_url":"https://pypi.org/project/python-ulid/","project_urls":{"CI":"https://github.com/mdomke/python-ulid/actions","Changelog":"https://python-ulid.readthedocs.io/en/latest/changelog.html","Documentation":"https://python-ulid.readthedocs.io","Homepage":"https://github.com/mdomke/python-ulid","Issues":"https://github.com/mdomke/python-ulid/issues","Repository":"https://github.com/mdomke/python-ulid"},"provides_extra":["pydantic"],"release_url":"https://pypi.org/project/python-ulid/3.0.0/","requires_dist":["pydantic>=2.0; extra == \"pydantic\""],"requires_python":">=3.9","summary":"Universally unique lexicographically sortable identifier","version":"3.0.0","yanked":false,"yanked_reason":null}

Package search

python-ulid

project_urls

Dependencies

All package metadata

Releases