# ZID
[](https://pypi.org/project/zid)
[](https://liberapay.com/Zaczero/)
[](https://github.com/sponsors/Zaczero)
**ZID** is a unique identifier with nice properties:
- It behaves like a 64-bit signed integer, so it can be safely used with external software, e.g., in a database. ZIDs will never overflow into negative values.
- ZIDs are numerically sortable since the timestamp is stored in the most significant bits. Additional randomness is stored only in the least significant bits.
- The specification is very simple, reducing the potential for bugs and making ZIDs highly efficient to generate and parse. Scroll down for the installation-free copy-and-paste code - it's that short!
- CSPRNG-initialized sequence numbers enhance the privacy of the generated identifiers while remaining collision-resistant. You can generate up to 65,536 ZIDs within the same millisecond timestamp on a single machine.
## Installation
```sh
pip install zid
```
## Installation (copy & paste)
Alternatively, you can copy and paste the following code for an installation-free ZID generator. This code excludes some performance optimizations and utility methods for the sake of simplicity:
```py
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 > 0x7FFFFFFFFFFF:
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
```
## Basic Usage
```py
from zid import zid
zid() # -> 112723768038396241
zid() # -> 112723768130153517
zid() # -> 112723768205368402
from zid import parse_zid_timestamp
parse_zid_timestamp(112723768038396241)
# -> 1720028198828 (UNIX timestamp in milliseconds)
```
## Format specification
ZID is 64 bits long in binary. Only 63 bits are used to fit in a signed integer. The first 47 bits are a UNIX timestamp in milliseconds. The remaining 16 bits are CSPRNG-initialized sequence numbers.
```txt
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|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) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
## Limitations
- Timestamps support years from 1970 to approx. 6429. To verify this, you can follow the formula *1970 + (2^47 − 1) / 1000 / (3600 * 24) / 365.25*
- If several ZIDs are generated with the same millisecond timestamp, knowing one of them will allow you to discover the others due to linearly increasing sequence numbers. Otherwise, guessing ZID values is difficult (but not impossible) due to the millisecond precision of the timestamp and the additional 16 bits of entropy. Do not rely on ZIDs alone for your security!
- You can generate up to 65,536 ZIDs within the same millisecond timestamp on a single machine. With two separate machines, you will generate on average 16,384 ZIDs each before a collision occurs within the same millisecond timestamp. With three separate machines, the average number is 10,240 ZIDs each.
- ZIDs are not strictly increasing within the same millisecond timestamp due to the possible sequence number overflow.
Raw data
{
"_id": null,
"home_page": "https://github.com/Zaczero/zid",
"name": "zid",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "uuid, unique identifier, identifier, primary key",
"author": "Kamil Monicz",
"author_email": "kamil@monicz.dev",
"download_url": "https://files.pythonhosted.org/packages/1f/71/20d31d1b26e48b6cb39d4dd6e26477993eeaccb74c54c749d942cc32180b/zid-1.0.0.tar.gz",
"platform": null,
"description": "# ZID\n\n[](https://pypi.org/project/zid)\n[](https://liberapay.com/Zaczero/)\n[](https://github.com/sponsors/Zaczero)\n\n**ZID** is a unique identifier with nice properties:\n\n- It behaves like a 64-bit signed integer, so it can be safely used with external software, e.g., in a database. ZIDs will never overflow into negative values.\n\n- ZIDs are numerically sortable since the timestamp is stored in the most significant bits. Additional randomness is stored only in the least significant bits.\n\n- The specification is very simple, reducing the potential for bugs and making ZIDs highly efficient to generate and parse. Scroll down for the installation-free copy-and-paste code - it's that short!\n\n- CSPRNG-initialized sequence numbers enhance the privacy of the generated identifiers while remaining collision-resistant. You can generate up to 65,536 ZIDs within the same millisecond timestamp on a single machine.\n\n## Installation\n\n```sh\npip install zid\n```\n\n## Installation (copy & paste)\n\nAlternatively, you can copy and paste the following code for an installation-free ZID generator. This code excludes some performance optimizations and utility methods for the sake of simplicity:\n\n```py\nfrom os import urandom\nfrom time import time_ns\n\n_last_time: int = -1\n_last_sequence: int = -1\n\ndef zid() -> int:\n global _last_time, _last_sequence\n\n # UNIX timestamp in milliseconds\n time: int = time_ns() // 1_000_000\n if time > 0x7FFFFFFFFFFF:\n raise OverflowError('Time value is too large')\n\n # CSPRNG-initialized sequence numbers\n sequence: int\n if _last_time == time:\n _last_sequence = sequence = (_last_sequence + 1) & 0xFFFF\n else:\n _last_sequence = sequence = int.from_bytes(urandom(2))\n _last_time = time\n\n return (time << 16) | sequence\n```\n\n## Basic Usage\n\n```py\nfrom zid import zid\nzid() # -> 112723768038396241\nzid() # -> 112723768130153517\nzid() # -> 112723768205368402\n\nfrom zid import parse_zid_timestamp\nparse_zid_timestamp(112723768038396241)\n# -> 1720028198828 (UNIX timestamp in milliseconds)\n```\n\n## Format specification\n\nZID is 64 bits long in binary. Only 63 bits are used to fit in a signed integer. The first 47 bits are a UNIX timestamp in milliseconds. The remaining 16 bits are CSPRNG-initialized sequence numbers.\n\n```txt\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|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|\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|0| timestamp (31 bits) |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| timestamp (16 bits) | random+sequence (16 bits) |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n```\n\n## Limitations\n\n- Timestamps support years from 1970 to approx. 6429. To verify this, you can follow the formula *1970 + (2^47 \u2212 1) / 1000 / (3600 * 24) / 365.25*\n\n- If several ZIDs are generated with the same millisecond timestamp, knowing one of them will allow you to discover the others due to linearly increasing sequence numbers. Otherwise, guessing ZID values is difficult (but not impossible) due to the millisecond precision of the timestamp and the additional 16 bits of entropy. Do not rely on ZIDs alone for your security!\n\n- You can generate up to 65,536 ZIDs within the same millisecond timestamp on a single machine. With two separate machines, you will generate on average 16,384 ZIDs each before a collision occurs within the same millisecond timestamp. With three separate machines, the average number is 10,240 ZIDs each.\n\n- ZIDs are not strictly increasing within the same millisecond timestamp due to the possible sequence number overflow.\n\n",
"bugtrack_url": null,
"license": "Unlicense",
"summary": "ZID is a unique identifier with nice properties",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Zaczero/zid",
"Repository": "https://github.com/Zaczero/zid"
},
"split_keywords": [
"uuid",
" unique identifier",
" identifier",
" primary key"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96bc190f87039471448980d8388db0237b05bd4cc34d8596e253268d70bad11f",
"md5": "6ce287b011c8e2d4c8eec5c873a41d62",
"sha256": "c87b45b32e936e50b701da9c2359b9af6c4826fdefb93b6a6096d42f0999ed20"
},
"downloads": -1,
"filename": "zid-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6ce287b011c8e2d4c8eec5c873a41d62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 4296,
"upload_time": "2024-07-03T19:39:17",
"upload_time_iso_8601": "2024-07-03T19:39:17.735872Z",
"url": "https://files.pythonhosted.org/packages/96/bc/190f87039471448980d8388db0237b05bd4cc34d8596e253268d70bad11f/zid-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1f7120d31d1b26e48b6cb39d4dd6e26477993eeaccb74c54c749d942cc32180b",
"md5": "3208b18221a89d106363db728b153242",
"sha256": "dfde14cf1268460824da490d12b647c0495b9f722a45d03e724907cfdc3d6cac"
},
"downloads": -1,
"filename": "zid-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "3208b18221a89d106363db728b153242",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 4920,
"upload_time": "2024-07-03T19:39:23",
"upload_time_iso_8601": "2024-07-03T19:39:23.007612Z",
"url": "https://files.pythonhosted.org/packages/1f/71/20d31d1b26e48b6cb39d4dd6e26477993eeaccb74c54c749d942cc32180b/zid-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-03 19:39:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Zaczero",
"github_project": "zid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zid"
}
JSON
