ulidx 0.0.1__py3-none-any.whl

ulidx/__init__.py

@@ -0,0 +1,341 @@
+"""
+Author: lqxnjk <lqxnjk@qq.com>
+Created: 2026-10-23 10:06
+Modified: 2026-10-23 10:06
+Python Version: 3.10
+ULID generation and conversion: sortable, monotonic, thread-safe.
+
+Standalone package: stdlib only, no internal dependencies.
+"""
+
+import calendar
+import datetime
+import os
+import struct
+import sys
+import threading
+import time
+import typing
+import uuid
+from collections.abc import Sequence
+
+__all__ = ["Ulid"]
+
+class Ulid:
+    """生成并转换按时间排序的 128 位 ULID 标识符。"""
+
+    _symbols = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+    _py3 = (sys.version_info[0] >= 3)
+    _text_type = str
+
+    # 单调性状态按线程隔离：每个线程各自持有「上一次熵 / 上一次毫秒时间戳」，
+    # 避免把进程级可变状态暴露给所有调用方而互相干扰。
+    _state: threading.local = threading.local()
+    # 保护「读旧值 -> 比较 -> 写回」临界区，保证同一线程内的单调性承诺不被并发交错破坏
+    _lock: threading.Lock = threading.Lock()
+
+    if _py3:
+        _to_binary = bytes
+
+    _decode_table: typing.ClassVar[list[int]] = [
+        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x01,
+        0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0xFF, 0xFF,
+        0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E,
+        0x0F, 0x10, 0x11, 0xFF, 0x12, 0x13, 0xFF, 0x14, 0x15, 0xFF,
+        0x16, 0x17, 0x18, 0x19, 0x1A, 0xFF, 0x1B, 0x1C, 0x1D, 0x1E,
+        0x1F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x0A, 0x0B, 0x0C,
+        0x0D, 0x0E, 0x0F, 0x10, 0x11, 0xFF, 0x12, 0x13, 0xFF, 0x14,
+        0x15, 0xFF, 0x16, 0x17, 0x18, 0x19, 0x1A, 0xFF, 0x1B, 0x1C,
+        0x1D, 0x1E, 0x1F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+    ]
+
+    @classmethod
+    def generate(cls, n_timestamp: float | datetime.datetime | None = None, n_monotonic: bool = False) -> str:
+        """生成按时间排序的 26 字符 ULID 字符串。
+
+        参数:
+            n_timestamp: n_=时间戳。None 使用当前时间；为 datetime 时按 UTC 取秒；
+                为 float 时按 Unix 秒解释。默认 None。
+            n_monotonic: n_=是否单调递增。为 True 时若同一毫秒内生成的熵小于上一次，
+                则重新生成以保证严格递增，避免碰撞。
+
+        返回:
+            str: 26 字符的 Crockford base32 大写 ULID 字符串。
+
+        注意:
+            ``n_monotonic`` 只在**单个线程内**保证严格递增；各线程各自持有单调状态，
+            不保证跨线程的全局单调。若需要跨线程全局有序，请由调用方自行串行化。
+        """
+        return cls.by_bytes(cls._generate_bytes(n_timestamp, n_monotonic))
+
+    @classmethod
+    def generate_batch(
+        cls,
+        n_count: int = 1,
+        n_timestamp: float | datetime.datetime | None = None,
+        n_monotonic: bool = False,
+    ) -> list[str]:
+        """批量生成多个 ULID 字符串（共享同一时间戳）。
+
+        与 :meth:`generate` 不同，本方法在一次调用内固定时间戳，仅随机部分不同，
+        因此适用于需要同刻批量生成且不依赖逐次递增的场景；内部复用
+        :meth:`_generate_bytes`，熵源与单调逻辑和 :meth:`generate` 完全一致。
+
+        参数:
+            n_count: m_=生成数量，默认 1。
+            n_timestamp: n_=时间戳（语义同 :meth:`generate`），默认 None（当前时间）。
+            n_monotonic: n_=是否单调递增，默认 False；同样只在单线程内保证严格递增。
+
+        返回:
+            list[str]: 长度为 n_count 的 ULID 字符串列表。
+        """
+        if n_timestamp is None:
+            _ts_val = time.time()
+        elif isinstance(n_timestamp, datetime.datetime):
+            _ts_val = float(calendar.timegm(n_timestamp.utctimetuple()))
+        else:
+            _ts_val = float(n_timestamp)
+
+        # 复用 _generate_bytes：统一熵源（os.urandom）、统一加锁的单调逻辑，
+        # 避免本方法再维护一份平行实现；传同一 _ts_val 保证整批共享同一毫秒时间戳。
+        return [cls.by_bytes(cls._generate_bytes(_ts_val, n_monotonic)) for _ in range(n_count)]
+
+    @classmethod
+    def generate_uuid(cls, n_timestamp: float | datetime.datetime | None = None, n_monotonic: bool = False) -> uuid.UUID:
+        """生成与 ULID 等价的 :class:`uuid.UUID` 对象。
+
+        参数:
+            n_timestamp: n_=时间戳（语义同 :meth:`generate`），默认 None。
+            n_monotonic: n_=是否单调递增，默认 False。
+
+        返回:
+            uuid.UUID: 由 ULID 16 字节直接构造的 UUID。
+        """
+        return uuid.UUID(bytes=cls._generate_bytes(n_timestamp, n_monotonic))
+
+    @classmethod
+    def _next_entropy(cls, m_timestamp: int, n_monotonic: bool) -> bytes:
+        """在锁内生成当前 ULID 的 10 字节熵，并维护线程级单调状态。
+
+        参数:
+            m_timestamp: m_=当前 ULID 的毫秒时间戳，用于判断是否与上一次同毫秒。
+            n_monotonic: m_=是否单调递增；为 True 且与上一次同毫秒时，
+                重新取样直到熵不小于上一次，保证同线程内严格递增。
+
+        返回:
+            bytes: 10 字节随机熵（统一取 :func:`os.urandom` 密码学随机源）。
+
+        注意:
+            状态存放在 :data:`_state`（``threading.local``），因此单调性仅限单线程；
+            读旧值、比较与写回都在 :data:`_lock` 内完成，保证临界区原子。
+        """
+        _state = cls._state
+        with cls._lock:
+            _prev = getattr(_state, "entropy", None)
+            _prev_timestamp = getattr(_state, "timestamp", None)
+            _entropy = os.urandom(10)
+            if n_monotonic and _prev is not None and _prev_timestamp == m_timestamp:
+                while _entropy < _prev:
+                    _entropy = os.urandom(10)
+            _state.entropy = _entropy
+            _state.timestamp = m_timestamp
+        return _entropy
+
+    @classmethod
+    def _generate_bytes(cls, n_timestamp: float | datetime.datetime | None = None, n_monotonic: bool = False) -> bytes:
+        """生成 ULID 字节（内部方法）。
+
+        参数:
+            n_timestamp: n_=时间戳，语义同 :meth:`generate`，默认 None（当前时间）。
+            n_monotonic: n_=是否单调递增，默认 False（仅单线程内保证严格递增）。
+
+        返回:
+            bytes: 16 字节 ULID（6 字节毫秒时间戳 + 10 字节随机熵）。
+        """
+        if n_timestamp is None:
+            _ts_val = time.time()
+        elif isinstance(n_timestamp, datetime.datetime):
+            _ts_val = float(calendar.timegm(n_timestamp.utctimetuple()))
+        else:
+            _ts_val = float(n_timestamp)
+
+        _ts = int(_ts_val * 1000.0)
+        _ts_bytes: bytes = struct.pack(b"!Q", _ts)[2:]
+        _entropy = cls._next_entropy(_ts, n_monotonic)
+        return _ts_bytes + _entropy
+
+    @classmethod
+    def by_bytes(cls, m_binary: bytes | Sequence[int]) -> str:
+        """
+        将 16 字节二进制数据编码为 26 字符的 base32 字符串
+        :param m_binary: 字节串或字节列表
+        :return: 26 字符的 ASCII 字符串
+        :rtype: str
+        """
+        assert len(m_binary) == 16
+
+        _symbols = cls._symbols
+        return "".join(
+            [
+                _symbols[(m_binary[0] & 224) >> 5],
+                _symbols[m_binary[0] & 31],
+                _symbols[(m_binary[1] & 248) >> 3],
+                _symbols[((m_binary[1] & 7) << 2) | ((m_binary[2] & 192) >> 6)],
+                _symbols[(m_binary[2] & 62) >> 1],
+                _symbols[((m_binary[2] & 1) << 4) | ((m_binary[3] & 240) >> 4)],
+                _symbols[((m_binary[3] & 15) << 1) | ((m_binary[4] & 128) >> 7)],
+                _symbols[(m_binary[4] & 124) >> 2],
+                _symbols[((m_binary[4] & 3) << 3) | ((m_binary[5] & 224) >> 5)],
+                _symbols[m_binary[5] & 31],
+                _symbols[(m_binary[6] & 248) >> 3],
+                _symbols[((m_binary[6] & 7) << 2) | ((m_binary[7] & 192) >> 6)],
+                _symbols[(m_binary[7] & 62) >> 1],
+                _symbols[((m_binary[7] & 1) << 4) | ((m_binary[8] & 240) >> 4)],
+                _symbols[((m_binary[8] & 15) << 1) | ((m_binary[9] & 128) >> 7)],
+                _symbols[(m_binary[9] & 124) >> 2],
+                _symbols[((m_binary[9] & 3) << 3) | ((m_binary[10] & 224) >> 5)],
+                _symbols[m_binary[10] & 31],
+                _symbols[(m_binary[11] & 248) >> 3],
+                _symbols[((m_binary[11] & 7) << 2) | ((m_binary[12] & 192) >> 6)],
+                _symbols[(m_binary[12] & 62) >> 1],
+                _symbols[((m_binary[12] & 1) << 4) | ((m_binary[13] & 240) >> 4)],
+                _symbols[((m_binary[13] & 15) << 1) | ((m_binary[14] & 128) >> 7)],
+                _symbols[(m_binary[14] & 124) >> 2],
+                _symbols[((m_binary[14] & 3) << 3) | ((m_binary[15] & 224) >> 5)],
+                _symbols[m_binary[15] & 31],
+            ]
+        )
+
+    @classmethod
+    def to_bytes(cls, m_ulid: str) -> bytes:
+        """将 26 字符 ULID 字符串解码为 16 字节。
+
+        参数:
+            m_ulid: m_=待解码的 ULID 字符串。
+
+        返回:
+            bytes: 16 字节的二进制表示。
+
+        异常:
+            ValueError: 长度非 26、首字符超出 '0'-'7' 范围或包含非法 base32 字符时抛出。
+        """
+        if len(m_ulid) != 26:
+            raise ValueError(f"base32 ulid is {len(m_ulid)} characters long, expected 26")
+        if not all(c in cls._symbols for c in m_ulid):
+            raise ValueError("invalid characters in base32 ulid")
+
+        _b = [ord(c) for c in m_ulid]
+        if _b[0] < 48 or _b[0] > 55:
+            raise ValueError(f"base32 ulid is out of range (starts with {m_ulid[0]}; accepted are 01234567)")
+
+        _tab = cls._decode_table
+        _binary = [(c & 0xFF) for c in [
+            ((_tab[_b[0]] << 5) | _tab[_b[1]]),
+            ((_tab[_b[2]] << 3) | (_tab[_b[3]] >> 2)),
+            ((_tab[_b[3]] << 6) | (_tab[_b[4]] << 1) | (_tab[_b[5]] >> 4)),
+            ((_tab[_b[5]] << 4) | (_tab[_b[6]] >> 1)),
+            ((_tab[_b[6]] << 7) | (_tab[_b[7]] << 2) | (_tab[_b[8]] >> 3)),
+            ((_tab[_b[8]] << 5) | _tab[_b[9]]),
+            ((_tab[_b[10]] << 3) | (_tab[_b[11]] >> 2)),
+            ((_tab[_b[11]] << 6) | (_tab[_b[12]] << 1) | (_tab[_b[13]] >> 4)),
+            ((_tab[_b[13]] << 4) | (_tab[_b[14]] >> 1)),
+            ((_tab[_b[14]] << 7) | (_tab[_b[15]] << 2) | (_tab[_b[16]] >> 3)),
+            ((_tab[_b[16]] << 5) | _tab[_b[17]]),
+            ((_tab[_b[18]] << 3) | _tab[_b[19]] >> 2),
+            ((_tab[_b[19]] << 6) | (_tab[_b[20]] << 1) | (_tab[_b[21]] >> 4)),
+            ((_tab[_b[21]] << 4) | (_tab[_b[22]] >> 1)),
+            ((_tab[_b[22]] << 7) | (_tab[_b[23]] << 2) | (_tab[_b[24]] >> 3)),
+            ((_tab[_b[24]] << 5) | _tab[_b[25]]),
+        ]]
+        return bytes(_binary)
+
+    @classmethod
+    def to_binary(cls, m_ulid: str | bytes | bytearray | uuid.UUID) -> bytes | bytearray:
+        """将多种表示形式统一转换为 16 字节二进制。
+
+        参数:
+            m_ulid: m_=ULID 字符串（26 字符）、bytes/bytearray（16 字节）或
+                :class:`uuid.UUID` 对象。
+
+        返回:
+            bytes | bytearray: 对应的 16 字节二进制（输入为 bytearray 时原样返回）。
+
+        异常:
+            ValueError: 输入无法识别为有效 ULID（长度/类型不符）时抛出。
+        """
+        if isinstance(m_ulid, uuid.UUID):
+            return m_ulid.bytes
+        if isinstance(m_ulid, (cls._text_type, bytes)) and len(m_ulid) == 26:
+            _str_val = m_ulid.decode("ascii") if isinstance(m_ulid, bytes) else m_ulid
+            return cls.to_bytes(_str_val)
+        if isinstance(m_ulid, (bytes, bytearray)) and len(m_ulid) == 16:
+            return m_ulid
+        raise ValueError(f"can not convert ulid {m_ulid!r} to binary")
+
+    @classmethod
+    def to_timestamp(cls, m_ulid: str | bytes | bytearray | uuid.UUID) -> float:
+        """从 ULID 提取其时间分量（UTC 毫秒时间戳的秒值）。
+
+        参数:
+            m_ulid: m_=任意合法的 ULID 表示（字符串/字节/UUID）。
+
+        返回:
+            float: Unix 秒（含毫秒小数）时间戳。
+
+        异常:
+            ValueError: 输入非有效 ULID 时由 :meth:`to_binary` 抛出。
+        """
+        _ts_bytes = bytes(cls.to_binary(m_ulid)[:6])
+        _ts_bytes = b"\0\0" + _ts_bytes
+        assert len(_ts_bytes) == 8
+        _res: tuple[int, ...] = struct.unpack(b"!Q", _ts_bytes)
+        return float(_res[0] / 1000.)
+
+    @classmethod
+    def to_time(cls, m_ulid: str | bytes | bytearray | uuid.UUID, n_hour_offset: int = 8) -> datetime.datetime:
+        """从 ULID 提取时间并转换为带时区的 :class:`datetime.datetime`。
+
+        参数:
+            m_ulid: m_=任意合法的 ULID 表示（字符串/字节/UUID）。
+            n_hour_offset: n_=目标时区相对 UTC 的小时偏移，默认 +8（中国标准时间）。
+
+        返回:
+            datetime.datetime: 已附时区信息的本地化时间。
+
+        注意:
+            内部先按 UTC 解释时间戳再换算到目标时区，不依赖运行机器的本地时区。
+        """
+        # to_timestamp 返回的是 UTC 秒：先按 UTC 解释，再换算到目标时区，
+        # 避免依赖运行机器的本地时区（旧实现在非 UTC+8 环境会整体偏移）
+        _timestamp = cls.to_timestamp(m_ulid)
+        _tz = datetime.timezone(datetime.timedelta(hours=n_hour_offset))
+        return datetime.datetime.fromtimestamp(_timestamp, datetime.timezone.utc).astimezone(_tz)
+
+    @classmethod
+    def to_uuid(cls, m_ulid: str | bytes | bytearray | uuid.UUID) -> uuid.UUID:
+        """将任意 ULID 表示转换为 :class:`uuid.UUID` 对象。
+
+        参数:
+            m_ulid: m_=ULID 字符串（26 字符）、16 字节或 UUID。
+
+        返回:
+            uuid.UUID: 由 ULID 二进制构造的 UUID。
+        """
+        return uuid.UUID(bytes=bytes(cls.to_binary(m_ulid)))
+
+    @classmethod
+    def from_uuid(cls, m_uuid: uuid.UUID) -> str:
+        """将 :class:`uuid.UUID` 转换为对应的 ULID 字符串。
+
+        参数:
+            m_uuid: m_=源 UUID 对象。
+
+        返回:
+            str: 由其 16 字节编码得到的 26 字符 ULID 字符串。
+        """
+        return cls.by_bytes(m_uuid.bytes)
+

ulidx-0.0.1.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: ulidx
+Version: 0.0.1
+Summary: ULID generation and conversion: sortable, monotonic, thread-safe.
+Project-URL: Homepage, https://github.com/lqxnjk/ulidx
+Project-URL: Source, https://github.com/lqxnjk/ulidx
+Author: lqxnjk
+License: MIT
+License-File: LICENSE
+Keywords: id,identifier,monotonic,sortable,ulid,uuid
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ulidx
+
+ULID generation and conversion. A ULID is a 128-bit identifier that is both
+**lexicographically sortable by creation time** and **random enough to be used
+as a primary key** — 26 characters in Crockford base32, no hyphens.
+
+## Install
+
+```console
+pip install ulidx
+```
+
+## Usage
+
+```python
+from ulidx import Ulid
+
+# plain generation
+Ulid.generate()                       # '01J8Z9K2M3N4P5Q6R7S8T9V0WX'
+
+# guaranteed strictly increasing within a process, even in the same millisecond
+Ulid.generate(n_monotonic=True)
+
+# pin the timestamp (aware or naive datetime, or epoch seconds)
+Ulid.generate(n_timestamp=1700000000)
+
+# bulk
+Ulid.generate_batch(1000)
+
+# back and forth
+value = Ulid.generate()
+Ulid.to_timestamp(value)              # float, epoch seconds
+Ulid.to_time(value)                   # datetime in UTC+8
+Ulid.to_bytes(value)                  # 16 raw bytes
+Ulid.by_bytes(Ulid.to_bytes(value))   # round trip
+Ulid.to_uuid(value)                   # uuid.UUID
+Ulid.from_uuid(some_uuid)             # 26-char str
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `generate(ts=None, monotonic=False)` | New 26-character ULID |
+| `generate_batch(count, ...)` | List of ULIDs |
+| `generate_uuid(ts=None, ...)` | New ULID as `uuid.UUID` |
+| `by_bytes(data)` | 16 bytes to ULID string |
+| `to_bytes(ulid)` | ULID (str / bytes / UUID) to 16 bytes |
+| `to_timestamp(ulid)` | Epoch seconds encoded in the ULID |
+| `to_time(ulid, hour_offset=8)` | `datetime` in the given UTC offset |
+| `to_uuid(ulid)` / `from_uuid(uuid)` | Convert between ULID and `uuid.UUID` |
+
+## Monotonicity
+
+`n_monotonic=True` keeps the generator state per thread, so concurrent threads
+never share a counter. Within a thread, ULIDs produced in the same millisecond
+strictly increase, which keeps sorting stable when several IDs are created in
+one tick.
+
+## License
+
+MIT

ulidx-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+ulidx/__init__.py,sha256=9cLR9qBo3VU76-yDIxiDTyynv_R2QpQ-rcjf7Ba5hhA,15241
+ulidx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ulidx-0.0.1.dist-info/METADATA,sha256=rCA15a7C_qCKSWn7wsL_FecX27Y96yh0Ip3p6SG112k,2648
+ulidx-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ulidx-0.0.1.dist-info/licenses/LICENSE,sha256=Q2c07NeDARb1XSKFLKAaKA8pCiR_C4baR6PRyCYj-t8,1063
+ulidx-0.0.1.dist-info/RECORD,,

ulidx-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

ulidx-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lqxnjk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.