ZID

https://github.com/zaczero/zid
Admin
ZID is a unique, numerically sortable identifier that behaves like a 64-bit signed integer,...
Tokens:1,560
Snippets:4
Trust Score:9.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install ZID via Pip

Source: https://github.com/zaczero/zid/blob/main/README.md

Installs the ZID package using the Python Package Index (PyPI). This is the recommended installation method for accessing the full features and optimizations of the ZID library.

```sh
pip install zid
```

--------------------------------

### Basic ZID Usage Examples

Source: https://github.com/zaczero/zid/blob/main/README.md

Demonstrates how to generate single ZIDs, multiple ZIDs using `zids(count)`, and parse the timestamp from a ZID using `parse_zid_timestamp`. These examples showcase the core functionality of the ZID library.

```python
from zid import zid
zid()  # -> 112723768038396241
zid()  # -> 112723768130153517
zid()  # -> 112723768205368402

from zid import zids
zids(3)
# -> [113103096068704205, 113103096068704206, 113103096068704207]

from zid import parse_zid_timestamp
parse_zid_timestamp(112723768038396241)
# -> 1720028198828 (UNIX timestamp in milliseconds)
```

--------------------------------

### ZID Generator (Copy & Paste Python)

Source: https://github.com/zaczero/zid/blob/main/README.md

A self-contained Python function for generating ZIDs without external installation. It uses `os.urandom` for sequence numbers and `time.time_ns` for timestamps, ensuring collision resistance and numerical sortability.

```python
from os import urandom
from time import time_ns

_last_time: int = -1
_last_sequence: int = -1

def zid() -> int:
    global _last_time, _last_sequence

    # UNIX timestamp in milliseconds
    time: int = time_ns() // 1_000_000
    if time > 0x7FFF_FFFF_FFFF:
        raise OverflowError('Time value is too large')

    # CSPRNG-initialized sequence numbers
    sequence: int
    if _last_time == time:
        _last_sequence = sequence = (_last_sequence + 1) & 0xFFFF
    else:
        _last_sequence = sequence = int.from_bytes(urandom(2))
        _last_time = time

    return (time << 16) | sequence
```

--------------------------------

### ZID Format Specification

Source: https://github.com/zaczero/zid/blob/main/README.md

Details the binary structure of a ZID, illustrating how the 64 bits are allocated. It shows that 47 bits are used for the UNIX timestamp in milliseconds and the remaining 16 bits for sequence numbers, with the most significant bit reserved.

```text
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0|1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|0|1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0|                     timestamp (31 bits)                     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|      timestamp (16 bits)      |   random+sequence (16 bits)   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
Tokens:
Raw