python-ulid 2.1.0__tar.gz → 2.3.0__tar.gz

{python_ulid-2.1.0 → python_ulid-2.3.0}/.github/workflows/lint-and-test.yml

@@ -9,12 +9,13 @@ on:
 jobs:
   lint-code:
     runs-on: ubuntu-latest
+    name: Lint code
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
       - name: Install dependencies
         run: |
           pip install hatch
@@ -25,12 +26,13 @@ jobs:
 
   lint-typing:
     runs-on: ubuntu-latest
+    name: Lint type annotations
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
       - name: Install dependencies
         run: |
           pip install hatch
@@ -41,13 +43,14 @@ jobs:
 
   test:
     runs-on: ubuntu-latest
+    name: Run tests
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -57,3 +60,13 @@ jobs:
           pip install hatch-fancy-pypi-readme
       - name: Test
         run: hatch run cov-test
+      - uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  package:
+    name: Build & verify package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hynek/build-and-inspect-python-package@v2

{python_ulid-2.1.0 → python_ulid-2.3.0}/.github/workflows/publish.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.x"
       - name: Install dependencies

{python_ulid-2.1.0 → python_ulid-2.3.0}/.gitignore

@@ -12,4 +12,4 @@ __pycache__
 /ChangeLog
 /dist/
 /build/
-/docs/_build
+/docs/build

python_ulid-2.3.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.3
+    hooks:
+      - id: ruff
+      - id: ruff-format
+  - repo: https://github.com/pycqa/doc8
+    rev: v1.1.1
+    hooks:
+      - id: doc8

{python_ulid-2.1.0 → python_ulid-2.3.0}/.readthedocs.yml

@@ -1,12 +1,12 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
 
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/source/conf.py
 
 python:
   install:

{python_ulid-2.1.0 → python_ulid-2.3.0}/CHANGELOG.rst

@@ -5,6 +5,36 @@ Changelog
 
 Versions follow `Semantic Versioning <http://www.semver.org>`_
 
+`2.3.0`_ - 2023-09-21
+---------------------
+
+Added
+~~~~~
+* :class:`.ULID` objects can now be converted to bytes with ``bytes(ulid)``.
+* The Pydantic v2 protocol is now supported, so that the :class:`.ULID` class can be directly used
+  as type annotations in `Pydantic models <https://docs.pydantic.dev/latest/concepts/models/#basic-model-usage>`_
+
+Changed
+~~~~~~~
+* The type annotations have been adapted, so that the classmethod constructors properly reflect the
+  type for :class:`.ULID` subclasses. Thanks to `@johnpaulett <https://github.com/johnpaulett>`_
+
+
+`2.2.0`_ - 2023-09-21
+---------------------
+
+Added
+~~~~~
+* Added a new flag ``--uuid4`` to the CLI ``show`` command, that converts the provided ``ULID``
+  into an RFC 4122 compliant ``UUID``.
+* The `ulid build` command allows the use of the special value ``-`` for all options to read its
+  inputs from ``stdin``. E.g.
+
+  .. code-block:: bash
+
+    $ date --iso-8601 | python -m ulid build --from-datetime -
+    01HAT9PVR02T3S13XB48S7GEHE
+
 `2.1.0`_ - 2023-09-21
 ---------------------
 
@@ -113,6 +143,8 @@ Changed
 * The package now has no external dependencies.
 * The test-coverage has been raised to 100%.
 
+.. _2.3.0: https://github.com/mdomke/python-ulid/compare/2.2.0...2.3.0
+.. _2.2.0: https://github.com/mdomke/python-ulid/compare/2.1.0...2.2.0
 .. _2.1.0: https://github.com/mdomke/python-ulid/compare/2.0.0...2.1.0
 .. _2.0.0: https://github.com/mdomke/python-ulid/compare/1.1.0...2.0.0
 .. _1.1.0: https://github.com/mdomke/python-ulid/compare/1.0.3...1.1.0

{python_ulid-2.1.0 → python_ulid-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: python-ulid
-Version: 2.1.0
+Version: 2.3.0
 Summary: Universally unique lexicographically sortable identifier
 Author-email: Martin Domke <mail@martindomke.net>
 License-Expression: MIT
@@ -15,8 +15,11 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.9
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == 'pydantic'
 Description-Content-Type: text/x-rst
 
 
@@ -57,6 +60,12 @@ Use ``pip`` to install the library
 
   $ 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
@@ -82,8 +91,8 @@ or use one of the named constructors
    >>> ULID.from_datetime(datetime.datetime.now())
    ULID(01E75J2XBK390V2XRH44EHC10X)
 
-There are several options for encoding the ``ULID`` object (e.g. string, hex, int),
-as well as to access the timestamp attribute in different formats:
+There are several options for encoding the ``ULID`` object
+(e.g. string, hex, int, bytes, UUID):
 
 .. code-block:: pycon
 
@@ -91,22 +100,54 @@ as well as to access the timestamp attribute in different formats:
    '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)
-   >>> ulid.to_uuid()
-   UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')
 
 .. 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
+``ulid`` or as python module ``python -m ulid``. The CLI allows you to generate, inspect
 and convert ULIDs, e.g.
 
 .. code-block:: bash
@@ -124,8 +165,26 @@ and convert ULIDs, e.g.
    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-ccff-acef-7900e6555299
+   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
 
@@ -135,3 +194,7 @@ 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>`_

{python_ulid-2.1.0 → python_ulid-2.3.0}/README.rst

@@ -69,6 +69,12 @@ Use ``pip`` to install the library
 
   $ 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
@@ -94,8 +100,8 @@ or use one of the named constructors
    >>> ULID.from_datetime(datetime.datetime.now())
    ULID(01E75J2XBK390V2XRH44EHC10X)
 
-There are several options for encoding the ``ULID`` object (e.g. string, hex, int),
-as well as to access the timestamp attribute in different formats:
+There are several options for encoding the ``ULID`` object
+(e.g. string, hex, int, bytes, UUID):
 
 .. code-block:: pycon
 
@@ -103,22 +109,54 @@ as well as to access the timestamp attribute in different formats:
    '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)
-   >>> ulid.to_uuid()
-   UUID('015ea15f-6cd1-c566-89a3-73fab3f63ece')
 
 .. 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
+``ulid`` or as python module ``python -m ulid``. The CLI allows you to generate, inspect
 and convert ULIDs, e.g.
 
 .. code-block:: bash
@@ -136,8 +174,26 @@ and convert ULIDs, e.g.
    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-ccff-acef-7900e6555299
+   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
 
@@ -147,3 +203,7 @@ 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>`_

{python_ulid-2.1.0 → python_ulid-2.3.0}/docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+SOURCEDIR     = source
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

python_ulid-2.3.0/docs/requirements.txt

@@ -0,0 +1,2 @@
+furo
+sphinx-copybutton

python_ulid-2.3.0/docs/source/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst

{python_ulid-2.1.0/docs → python_ulid-2.3.0/docs/source}/conf.py

@@ -3,9 +3,9 @@ import sys
 from datetime import datetime
 
 
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../.."))
 
-import ulid  # noqa
+import ulid
 
 
 copyright = f"{datetime.now().year}, Martin Domke"
@@ -24,6 +24,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -32,7 +33,7 @@ templates_path = ["_templates"]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = []
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -40,15 +41,8 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_logo = "../logo.png"
+html_logo = "../../logo.png"
 html_theme = "furo"
-html_theme_options = {
-    "github_user": "mdomke",
-    "github_repo": "python-ulid",
-    "description": "A library for working with ULIDs",
-    "sidebar_collapse": False,
-    "logo_text_align": "center",
-}
 
 html_title = "Python ULID docs"
 

{python_ulid-2.1.0/docs → python_ulid-2.3.0/docs/source}/index.rst

@@ -4,19 +4,23 @@ Python ULID
 Release v\ |release| (:ref:`What's new <changelog>`)
 
 
-.. include:: ../README.rst
+.. include:: ../../README.rst
    :start-after: teaser-begin
    :end-before: teaser-end
 
-.. include:: ../README.rst
+.. include:: ../../README.rst
    :start-after: installation-begin
    :end-before: installation-end
 
-.. include:: ../README.rst
+.. include:: ../../README.rst
    :start-after: usage-begin
    :end-before: usage-end
 
-.. include:: ../README.rst
+.. include:: ../../README.rst
+   :start-after: pydantic-begin
+   :end-before: pydantic-end
+
+.. include:: ../../README.rst
    :start-after: cli-begin
    :end-before: cli-end
 

{python_ulid-2.1.0 → python_ulid-2.3.0}/hatch.toml

@@ -1,8 +1,11 @@
 [envs.default]
 dependencies = [
-  "freezegun==1.2.*",
+  "freezegun==1.4.*",
   "pytest-cov==4.1.*",
-  "pytest==7.3.*",
+  "pytest==8.1.*",
+]
+features = [
+  "pydantic"
 ]
 
 [envs.default.scripts]
@@ -11,18 +14,19 @@ cov-test = "pytest --cov {args:ulid} --cov-report=term-missing --cov-report=xml"
 
 [envs.lint]
 dependencies = [
-  "ruff==0.0.290",
-  "black==23.9.*",
-  "mypy==1.5.*",
+  "ruff==0.3.*",
+  "mypy==1.9.*",
+  "doc8==1.1.*",
 ]
 
 [envs.lint.scripts]
 typing = "mypy --install-types --non-interactive {args:ulid}"
 style = [
-  "black --check --diff {args:.}",
-  "ruff {args:.}",
+  "ruff format --check --diff {args:.}",
+  "ruff check {args:.}",
 ]
 fmt = [
-  "black {args:.}",
-  "ruff --fix {args:.}",
+  "ruff format {args:.}",
+  "ruff check --fix {args:.}",
 ]
+docs = "doc8 docs"

{python_ulid-2.1.0 → python_ulid-2.3.0}/pyproject.toml

@@ -22,9 +22,15 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Topic :: Software Development :: Libraries",
 ]
 
+[project.optional-dependencies]
+pydantic = [
+    "pydantic>=2.0"
+]
+
 [project.scripts]
 ulid = "ulid.__main__:entrypoint"
 
@@ -42,6 +48,8 @@ line-length = 100
 [tool.ruff]
 target-version = "py39"
 line-length = 100
+
+[tool.ruff.lint]
 select = ["A", "B", "C", "C4", "E", "F", "I", "N", "PT", "Q", "RUF", "S", "SIM", "T10", "UP", "W", "YTT"]
 fixable = ["RUF100", "I001"]
 ignore = [
@@ -50,21 +58,14 @@ ignore = [
     "A003",   # Allow shadowing bultins on classes
 ]
 
-[tool.ruff.mccabe]
+[tool.ruff.lint.mccabe]
 max-complexity = 15
 
-[tool.ruff.isort]
+[tool.ruff.lint.isort]
 force-single-line = true
 lines-after-imports = 2
 order-by-type = false
 
-[tool.isort]
-profile = "black"
-force_alphabetical_sort_within_sections = true
-force_single_line = true
-lines_after_imports = 2
-line_length = 100
-
 [tool.coverage.run]
 branch = true
 parallel = true
@@ -78,4 +79,4 @@ content-type = "text/x-rst"
 
 [[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
 path = "README.rst"
-start-after = ".. teaser-begin"
+start-after = ".. teaser-begin"

python_ulid-2.3.0/tests/test_cli.py

@@ -0,0 +1,77 @@
+import pytest
+
+import ulid.__main__ as cli
+from ulid import ULID
+
+
+@pytest.mark.parametrize("option", ["", "uuid", "uuid4", "hex", "int", "timestamp", "datetime"])
+def test_parse_show(option: str):
+    ulid = ULID()
+    argv = ["show", f"--{option}", str(ulid)]
+    output = cli.main(argv)
+    if option == "uuid":
+        assert output == str(ulid.to_uuid())
+    elif option == "uuid4":
+        assert output == str(ulid.to_uuid4())
+    elif option == "hex":
+        assert output == ulid.hex
+    elif option == "int":
+        assert output == str(int(ulid))
+    elif option == "timestamp":
+        assert output == str(ulid.timestamp)
+    elif option == "datetime":
+        assert output == ulid.datetime.isoformat()
+    else:
+        assert str(ulid) in output
+        assert ulid.hex in output
+        assert str(int(ulid)) in output
+        assert str(ulid.timestamp) in output
+        assert str(ulid.datetime.isoformat()) in output
+
+
+@pytest.mark.parametrize(
+    "option",
+    [
+        "",
+        "from-uuid",
+        "from-str",
+        "from-hex",
+        "from-int",
+        "from-timestamp",
+        "from-datetime",
+    ],
+)
+def test_build(option: str):
+    ulid = ULID()
+    value: str
+    includes_randomness = True
+    includes_timestamp = True
+    if option.endswith("uuid"):
+        value = str(ulid.to_uuid())
+    elif option.endswith("str"):
+        value = str(ulid)
+    elif option.endswith("hex"):
+        value = ulid.hex
+    elif option.endswith("int"):
+        value = str(int(ulid))
+    elif option.endswith("timestamp"):
+        value = str(ulid.timestamp)
+        includes_randomness = False
+    elif option.endswith("datetime"):
+        value = ulid.datetime.isoformat()
+        includes_randomness = False
+    else:
+        includes_timestamp = False
+        includes_randomness = False
+
+    argv = ["build"]
+    if option:
+        argv += [f"--{option}", value]
+    output = cli.main(argv)
+
+    if includes_randomness and includes_timestamp:
+        assert output == str(ulid)
+
+    ulid_out = ULID.from_str(output)
+    if includes_timestamp:
+        assert ulid_out.datetime == ulid.datetime

{python_ulid-2.1.0 → python_ulid-2.3.0}/tests/test_ulid.py

@@ -8,6 +8,8 @@ from typing import Union
 
 import pytest
 from freezegun import freeze_time
+from pydantic import BaseModel
+from pydantic import ValidationError
 
 from ulid import base32
 from ulid import constants
@@ -115,7 +117,8 @@ def test_hash() -> None:
 @freeze_time()
 def test_ulid_from_time() -> None:
     ulid1 = ULID.from_timestamp(time.time())
-    ulid2 = ULID.from_datetime(utcnow())
+    ulid2 = ULID.from_timestamp(time.time_ns() // 1000000)
+    ulid3 = ULID.from_datetime(utcnow())
 
     now = utcnow()
     t = time.time()
@@ -126,6 +129,9 @@ def test_ulid_from_time() -> None:
     assert ulid2.timestamp == pytest.approx(t)
     datetimes_almost_equal(ulid2.datetime, now)
 
+    assert ulid2.timestamp == pytest.approx(t)
+    datetimes_almost_equal(ulid3.datetime, now)
+
 
 @freeze_time()
 def test_ulid_from_timestamp() -> None:
@@ -155,3 +161,19 @@ Params = Union[bytes, str, int, float]
 def test_ulid_invalid_input(constructor: Callable[[Params], ULID], value: Params) -> None:
     with pytest.raises(ValueError):  # noqa: PT011
         constructor(value)
+
+
+def test_pydantic_protocol() -> None:
+    ulid = ULID()
+
+    class Model(BaseModel):
+        ulid: ULID
+
+    for value in [ulid, str(ulid), int(ulid), bytes(ulid)]:
+        model = Model(ulid=value)
+        assert isinstance(model.ulid, ULID)
+        assert model.ulid == ulid
+
+    for value in [b"not-enough", "not-enough"]:
+        with pytest.raises(ValidationError):
+            Model(ulid=value)

{python_ulid-2.1.0 → python_ulid-2.3.0}/ulid/__init__.py

@@ -9,15 +9,21 @@ from datetime import datetime
 from datetime import timezone
 from typing import Any
 from typing import Generic
+from typing import TYPE_CHECKING
 from typing import TypeVar
 
 from ulid import base32
 from ulid import constants
 
 
+if TYPE_CHECKING:  # pragma: no cover
+    from pydantic import GetCoreSchemaHandler
+    from pydantic import ValidatorFunctionWrapHandler
+    from pydantic_core import CoreSchema
+
 try:
     from importlib.metadata import version
-except ImportError:
+except ImportError:  # pragma: no cover
     from importlib_metadata import version  # type: ignore
 
 
@@ -44,6 +50,9 @@ class validate_type(Generic[T]):  # noqa: N801
         return wrapped
 
 
+U = TypeVar("U", bound="ULID")
+
+
 @functools.total_ordering
 class ULID:
     """The :class:`ULID` object consists of a timestamp part of 48 bits and of 80 random bits.
@@ -67,11 +76,13 @@ class ULID:
     def __init__(self, value: bytes | None = None) -> None:
         if value is not None and len(value) != constants.BYTES_LEN:
             raise ValueError("ULID has to be exactly 16 bytes long.")
-        self.bytes: bytes = value or ULID.from_timestamp(time.time()).bytes
+        self.bytes: bytes = (
+            value or ULID.from_timestamp(time.time_ns() // constants.NANOSECS_IN_MILLISECS).bytes
+        )
 
     @classmethod
     @validate_type(datetime)
-    def from_datetime(cls, value: datetime) -> ULID:
+    def from_datetime(cls: type[U], value: datetime) -> U:
         """Create a new :class:`ULID`-object from a :class:`datetime`. The timestamp part of the
         `ULID` will be set to the corresponding timestamp of the datetime.
 
@@ -85,7 +96,7 @@ class ULID:
 
     @classmethod
     @validate_type(int, float)
-    def from_timestamp(cls, value: int | float) -> ULID:
+    def from_timestamp(cls: type[U], value: int | float) -> U:
         """Create a new :class:`ULID`-object from a timestamp. The timestamp can be either a
         `float` representing the time in seconds (as it would be returned by :func:`time.time()`)
         or an `int` in milliseconds.
@@ -104,7 +115,7 @@ class ULID:
 
     @classmethod
     @validate_type(uuid.UUID)
-    def from_uuid(cls, value: uuid.UUID) -> ULID:
+    def from_uuid(cls: type[U], value: uuid.UUID) -> U:
         """Create a new :class:`ULID`-object from a :class:`uuid.UUID`. The timestamp part will be
         random in that case.
 
@@ -118,25 +129,25 @@ class ULID:
 
     @classmethod
     @validate_type(bytes)
-    def from_bytes(cls, bytes_: bytes) -> ULID:
+    def from_bytes(cls: type[U], bytes_: bytes) -> U:
         """Create a new :class:`ULID`-object from sequence of 16 bytes."""
         return cls(bytes_)
 
     @classmethod
     @validate_type(str)
-    def from_hex(cls, value: str) -> ULID:
+    def from_hex(cls: type[U], value: str) -> U:
         """Create a new :class:`ULID`-object from 32 character string of hex values."""
         return cls.from_bytes(bytes.fromhex(value))
 
     @classmethod
     @validate_type(str)
-    def from_str(cls, string: str) -> ULID:
+    def from_str(cls: type[U], string: str) -> U:
         """Create a new :class:`ULID`-object from a 26 char long string representation."""
         return cls(base32.decode(string))
 
     @classmethod
     @validate_type(int)
-    def from_int(cls, value: int) -> ULID:
+    def from_int(cls: type[U], value: int) -> U:
         """Create a new :class:`ULID`-object from an `int`."""
         return cls(int.to_bytes(value, constants.BYTES_LEN, "big"))
 
@@ -209,6 +220,10 @@ class ULID:
         """Encode this object as an integer."""
         return int.from_bytes(self.bytes, byteorder="big")
 
+    def __bytes__(self) -> bytes:
+        """Encode this object as byte sequence."""
+        return self.bytes
+
     def __lt__(self, other: Any) -> bool:
         if isinstance(other, ULID):
             return self.bytes < other.bytes
@@ -233,3 +248,34 @@ class ULID:
 
     def __hash__(self) -> int:
         return hash(self.bytes)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: GetCoreSchemaHandler) -> CoreSchema:
+        from pydantic_core import core_schema
+
+        return core_schema.no_info_wrap_validator_function(
+            cls._pydantic_validate,
+            core_schema.union_schema(
+                [
+                    core_schema.is_instance_schema(ULID),
+                    core_schema.no_info_plain_validator_function(ULID),
+                ]
+            ),
+        )
+
+    @classmethod
+    def _pydantic_validate(cls, value: Any, handler: ValidatorFunctionWrapHandler) -> Any:
+        from pydantic_core import PydanticCustomError
+
+        try:
+            if isinstance(value, int):
+                ulid = cls.from_int(value)
+            elif isinstance(value, str):
+                ulid = cls.from_str(value)
+            elif isinstance(value, ULID):
+                ulid = value
+            else:
+                ulid = cls.from_bytes(value)
+        except ValueError as err:
+            raise PydanticCustomError("ulid_format", "Unrecognized format") from err
+        return handler(ulid)

{python_ulid-2.1.0 → python_ulid-2.3.0}/ulid/__main__.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
 import argparse
 import shutil
 import sys
 import textwrap
+from collections.abc import Callable
 from collections.abc import Sequence
 from datetime import datetime
 from functools import partial
+from typing import Any
 from uuid import UUID
 
 import ulid
@@ -47,37 +51,31 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
     )
     b.add_argument(
         "--from-int",
-        type=int,
         metavar="<int>",
         help="create from integer",
     )
     b.add_argument(
         "--from-hex",
-        type=str,
         metavar="<str>",
         help="create from 32 character hex value",
     )
     b.add_argument(
         "--from-str",
-        type=str,
         metavar="<str>",
         help="create from base32 encoded string of length 26",
     )
     b.add_argument(
         "--from-timestamp",
-        type=parse_numeric,
         metavar="<int|float>",
         help="create from timestamp either as float in secs or int as millis",
     )
     b.add_argument(
         "--from-datetime",
-        type=datetime.fromisoformat,
         metavar="<iso8601>",
         help="create from datetime. The timestamp part of the ULID will be taken from the datetime",
     )
     b.add_argument(
         "--from-uuid",
-        type=UUID,
         metavar="<uuid>",
         help="create from given UUID. The timestamp part will be random.",
     )
@@ -85,7 +83,8 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
 
     s = subparsers.add_parser("show", help="show properties of a ULID")
     s.add_argument("ulid", help="the ULID to inspect. The special value - reads from stdin")
-    s.add_argument("--uuid", action="store_true", help="convert to UUID")
+    s.add_argument("--uuid", action="store_true", help="convert to fully random UUID")
+    s.add_argument("--uuid4", action="store_true", help="convert to RFC 4122 compliant UUIDv4")
     s.add_argument("--hex", action="store_true", help="convert to hex")
     s.add_argument("--int", action="store_true", help="convert to int")
     s.add_argument("--timestamp", "--ts", action="store_true", help="show timestamp")
@@ -94,6 +93,18 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
     return parser
 
 
+def main(argv: Sequence[str], prog: str | None = None) -> str:
+    args = make_parser(prog).parse_args(argv)
+    return args.func(args)
+
+
+def from_value_or_stdin(value: str, convert: Callable[[str], Any] | None = None) -> Any:
+    value = sys.stdin.readline().strip() if value == "-" else value
+    if convert is not None:
+        return convert(value)
+    return value
+
+
 def parse_numeric(s: str) -> int | float:
     try:
         return int(s)
@@ -101,60 +112,54 @@ def parse_numeric(s: str) -> int | float:
         return float(s)
 
 
-def main(argv: Sequence[str], prog: str | None = None) -> None:
-    args = make_parser(prog).parse_args(argv)
-    args.func(args)
-
-
-def build(args: argparse.Namespace) -> None:
+def build(args: argparse.Namespace) -> str:
     ulid: ULID
     if args.from_int is not None:
-        ulid = ULID.from_int(args.from_int)
+        ulid = ULID.from_int(from_value_or_stdin(args.from_int, int))
     elif args.from_hex is not None:
-        ulid = ULID.from_hex(args.from_hex)
+        ulid = ULID.from_hex(from_value_or_stdin(args.from_hex))
     elif args.from_str is not None:
-        ulid = ULID.from_str(args.from_str)
+        ulid = ULID.from_str(from_value_or_stdin(args.from_str))
     elif args.from_timestamp is not None:
-        ulid = ULID.from_timestamp(args.from_timestamp)
+        ulid = ULID.from_timestamp(from_value_or_stdin(args.from_timestamp, parse_numeric))
     elif args.from_datetime is not None:
-        ulid = ULID.from_datetime(args.from_datetime)
+        ulid = ULID.from_datetime(from_value_or_stdin(args.from_datetime, datetime.fromisoformat))
     elif args.from_uuid is not None:
-        ulid = ULID.from_uuid(args.from_uuid)
+        ulid = ULID.from_uuid(from_value_or_stdin(args.from_uuid, UUID))
     else:
         ulid = ULID()
-    print(ulid)
+    return str(ulid)
 
 
-def show(args: argparse.Namespace) -> None:
-    value = sys.stdin.readline().strip() if args.ulid == "-" else args.ulid
-    ulid: ULID = ULID.from_str(value)
+def show(args: argparse.Namespace) -> str:
+    ulid: ULID = ULID.from_str(from_value_or_stdin(args.ulid))
     if args.uuid:
-        print(ulid.to_uuid())
+        return str(ulid.to_uuid())
+    elif args.uuid4:
+        return str(ulid.to_uuid4())
     elif args.hex:
-        print(ulid.hex)
+        return ulid.hex
     elif args.int:
-        print(int(ulid))
+        return str(int(ulid))
     elif args.timestamp:
-        print(ulid.timestamp)
+        return str(ulid.timestamp)
     elif args.datetime:
-        print(ulid.datetime)
+        return ulid.datetime.isoformat()
     else:
-        print(
-            textwrap.dedent(
-                f"""
-                ULID:      {ulid!s}
-                Hex:       {ulid.hex}
-                Int:       {int(ulid)}
-                Timestamp: {ulid.timestamp}
-                Datetime:  {ulid.datetime}
-                """
-            ).strip()
-        )
+        return textwrap.dedent(
+            f"""
+            ULID:      {ulid!s}
+            Hex:       {ulid.hex}
+            Int:       {int(ulid)}
+            Timestamp: {ulid.timestamp}
+            Datetime:  {ulid.datetime.isoformat()}
+            """
+        ).strip()
 
 
-def entrypoint() -> None:
-    main(sys.argv[1:])
+def entrypoint() -> None:  # pragma: no cover
+    print(main(sys.argv[1:]))
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     main(sys.argv[1:], "python -m ulid")

{python_ulid-2.1.0 → python_ulid-2.3.0}/ulid/constants.py

@@ -1,4 +1,5 @@
 MILLISECS_IN_SECS = 1000
+NANOSECS_IN_MILLISECS = 1000000
 
 TIMESTAMP_LEN = 6
 RANDOMNESS_LEN = 10

python_ulid-2.1.0/.pre-commit-config.yaml

@@ -1,18 +0,0 @@
-repos:
-  - repo: https://github.com/psf/black
-    rev: 23.9.1
-    hooks:
-      - id: black
-  - repo: https://github.com/timothycrosley/isort
-    rev: 5.12.0
-    hooks:
-      - id: isort
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
-    rev: v0.0.290
-    hooks:
-      - id: ruff
-  - repo: https://github.com/pycqa/doc8
-    rev: v1.1.1
-    hooks:
-      - id: doc8

python_ulid-2.1.0/docs/changelog.rst

@@ -1 +0,0 @@
-.. include:: ../CHANGELOG.rst

python_ulid-2.1.0/docs/requirements.txt

@@ -1 +0,0 @@
-furo