| Name | python-ulid JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | None |
| Summary | Universally unique lexicographically sortable identifier |
| upload_time | 2024-10-11 15:31:55 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
A ``ULID`` is a *universally unique lexicographically sortable identifier*. It is
* 128-bit compatible with ``UUID``
* 1.21e+24 unique ULIDs per millisecond
* Lexicographically sortable!
* Canonically encoded as a 26 character string, as opposed to the 36 character UUID
* Uses Crockford's base32 for better efficiency and readability (5 bits per character)
* Case insensitive
* No special characters (URL safe)
In general the structure of a ULID is as follows:
.. code-block:: text
01AN4Z07BY 79KA1307SR9X4MV3
|----------| |----------------|
Timestamp Randomness
48bits 80bits
For more information have a look at the original
`specification <https://github.com/alizain/ulid#specification>`_.
.. teaser-end
.. installation-begin
Installation
------------
Use ``pip`` to install the library
.. code-block:: bash
$ pip install python-ulid
to include Pydantic support install the optional dependency like so
.. code-block:: bash
$ pip install python-ulid[pydantic]
.. installation-end
.. usage-begin
Basic Usage
-----------
Create a new ``ULID`` object from the current timestamp
.. code-block:: pycon
>>> from ulid import ULID
>>> ULID()
ULID(01E75HZVW36EAZKMF1W7XNMSB4)
or use one of the named constructors
.. code-block:: pycon
>>> import time, datetime
>>> ULID.from_timestamp(time.time())
ULID(01E75J1MKKWMGG0N5MBHFMRC84)
>>> ULID.from_datetime(datetime.datetime.now())
ULID(01E75J2XBK390V2XRH44EHC10X)
There are several options for encoding the ``ULID`` object
(e.g. string, hex, int, bytes, UUID):
.. code-block:: pycon
>>> str(ulid)
'01BTGNYV6HRNK8K8VKZASZCFPE'
>>> ulid.hex
'015ea15f6cd1c56689a373fab3f63ece'
>>> int(ulid)
1820576928786795198723644692628913870
>>> bytes(ulid)
b'\x01^\xa1_l\xd1\xc5f\x89\xa3s\xfa\xb3\xf6>\xce'
>>> ulid.to_uuid()
UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')
It is also possible to directly access the timestamp component of a ``ULID``,
either in UNIX epoch or as ``datetime.datetime``
.. code-block:: pycon
>>> ulid.timestamp
1505945939.153
>>> ulid.datetime
datetime.datetime(2017, 9, 20, 22, 18, 59, 153000, tzinfo=datetime.timezone.utc)
.. usage-end
.. pydantic-begin
Pydantic integration
---------------------
The ``ULID`` class can be directly used for the popular data validation library
`Pydantic <https://docs.pydantic.dev/latest/>`_ like so
.. code-block:: python
from pydantic import BaseModel
from ulid import ULID
class Model(BaseModel):
ulid: ULID
model = Model(ulid="DX89370400440532013000") # OK
model = Model(ulid="not-a-ulid") # Raises ValidationError
.. pydantic-end
.. cli-begin
Command line interface
-----------------------
The package comes with a CLI interface that can be invoked either by the script name
``ulid`` or as python module ``python -m ulid``. The CLI allows you to generate, inspect
and convert ULIDs, e.g.
.. code-block:: bash
$ ulid build
01HASFKBN8SKZTSVVS03K5AMMS
$ ulid build --from-datetime=2023-09-23T10:20:30
01HB0J0F5GCKEXNSWVAD5PEAC1
$ ulid show 01HASFKBN8SKZTSVVS03K5AMMS
ULID: 01HASFKBN8SKZTSVVS03K5AMMS
Hex: 018ab2f9aea8ccffacef7900e6555299
Int: 2049395013039097460549394558635823769
Timestamp: 1695219822.248
Datetime: 2023-09-20 14:23:42.248000+00:00
There are several flags to select specific output formats for the ``show`` command, e.g.
.. code-block:: bash
$ ulid show --datetime 01HASFKBN8SKZTSVVS03K5AMMS
2023-09-20 14:23:42.248000+00:00
The special character ``-`` allows to read values from ``stdin`` so that they can be piped. E.g.
.. code-block:: bash
$ echo 01HASFKBN8SKZTSVVS03K5AMMS | ulid show --uuid -
018ab2f9-aea8-4cff-acef-7900e6555299
$ date --iso-8601 | python -m ulid build --from-datetime -
01HAT9PVR02T3S13XB48S7GEHE
For a full overview of flags for the ``build`` and ``show`` commands use the ``--help`` option
(e.g. ``ulid show --help``).
.. cli-end
Other implementations
---------------------
* `ahawker/ulid <https://github.com/ahawker/ulid>`_
* `valohai/ulid2 <https://github.com/valohai/ulid2>`_
* `mdipierro/ulid <https://github.com/mdipierro/ulid>`_
* `oklog/ulid <https://github.com/oklog/ulid>`_
* `ulid/javascript <https://github.com/ulid/javascript>`_
* `RobThree/NUlid <https://github.com/RobThree/NUlid>`_
* `imdario/go-ulid <https://github.com/imdario/go-ulid>`_
Raw data
{
"_id": null,
"home_page": null,
"name": "python-ulid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Martin Domke <mail@martindomke.net>",
"download_url": "https://files.pythonhosted.org/packages/9a/db/e5e67aeca9c2420cb91f94007f30693cc3628ae9783a565fd33ffb3fbfdd/python_ulid-3.0.0.tar.gz",
"platform": null,
"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 <https://github.com/alizain/ulid#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 <https://docs.pydantic.dev/latest/>`_ 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 <https://github.com/ahawker/ulid>`_\n* `valohai/ulid2 <https://github.com/valohai/ulid2>`_\n* `mdipierro/ulid <https://github.com/mdipierro/ulid>`_\n* `oklog/ulid <https://github.com/oklog/ulid>`_\n* `ulid/javascript <https://github.com/ulid/javascript>`_\n* `RobThree/NUlid <https://github.com/RobThree/NUlid>`_\n* `imdario/go-ulid <https://github.com/imdario/go-ulid>`_\n",
"bugtrack_url": null,
"license": null,
"summary": "Universally unique lexicographically sortable identifier",
"version": "3.0.0",
"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"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "634ecc2ba2c0df2589f35a4db8473b8c2ba9bbfc4acdec4a94f1c78934d2350f",
"md5": "4aa03ee917b8d92ce2ce9b8c540b48c9",
"sha256": "e4c4942ff50dbd79167ad01ac725ec58f924b4018025ce22c858bfcff99a5e31"
},
"downloads": -1,
"filename": "python_ulid-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4aa03ee917b8d92ce2ce9b8c540b48c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11194,
"upload_time": "2024-10-11T15:31:54",
"upload_time_iso_8601": "2024-10-11T15:31:54.368685Z",
"url": "https://files.pythonhosted.org/packages/63/4e/cc2ba2c0df2589f35a4db8473b8c2ba9bbfc4acdec4a94f1c78934d2350f/python_ulid-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9adbe5e67aeca9c2420cb91f94007f30693cc3628ae9783a565fd33ffb3fbfdd",
"md5": "30c0bb0d6bbed34ff0a852e806de04cb",
"sha256": "e50296a47dc8209d28629a22fc81ca26c00982c78934bd7766377ba37ea49a9f"
},
"downloads": -1,
"filename": "python_ulid-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "30c0bb0d6bbed34ff0a852e806de04cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 28822,
"upload_time": "2024-10-11T15:31:55",
"upload_time_iso_8601": "2024-10-11T15:31:55.475458Z",
"url": "https://files.pythonhosted.org/packages/9a/db/e5e67aeca9c2420cb91f94007f30693cc3628ae9783a565fd33ffb3fbfdd/python_ulid-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-11 15:31:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mdomke",
"github_project": "python-ulid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-ulid"
}
