# 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
The recommended installation method is through the PyPI package manager. The project is implemented in Rust, offering excellent performance characteristics. Several pre-built binary wheels are available for Linux, macOS, and Windows, with support for both x64 and ARM architectures.
```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 performance optimizations and utility methods for the sake of simplicity and portability:
```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 > 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
```
## Basic usage
```py
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)
```
## 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": null,
"name": "zid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "identifier, primary key, unique identifier, uuid",
"author": null,
"author_email": "Kamil Monicz <kamil@monicz.dev>",
"download_url": "https://files.pythonhosted.org/packages/36/9f/59b447652aa62bab4076430cfabb8d35ed14cf0f4fe4ab4cdf9c870d7d78/zid-1.3.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\nThe recommended installation method is through the PyPI package manager. The project is implemented in Rust, offering excellent performance characteristics. Several pre-built binary wheels are available for Linux, macOS, and Windows, with support for both x64 and ARM architectures.\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 performance optimizations and utility methods for the sake of simplicity and portability:\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 > 0x7FFF_FFFF_FFFF:\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 zids\nzids(3)\n# -> [113103096068704205, 113103096068704206, 113103096068704207]\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": null,
"summary": "ZID is a unique identifier with nice properties",
"version": "1.3.0",
"project_urls": {
"Issues": "https://github.com/Zaczero/zid/issues",
"Repository": "https://github.com/Zaczero/zid"
},
"split_keywords": [
"identifier",
" primary key",
" unique identifier",
" uuid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78a2f830bb9d9d29f1e1dd532fc93efc01d43f3d0a2912e20a244bbf73885f9c",
"md5": "8c5ad32d5dfb5a1cc0e1ef7c9eee64ab",
"sha256": "9d43a8394a8cdfbcd39490294373cf6aaa3a655a894e09c90970f2027b7f66ab"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "8c5ad32d5dfb5a1cc0e1ef7c9eee64ab",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 207469,
"upload_time": "2024-10-26T02:07:04",
"upload_time_iso_8601": "2024-10-26T02:07:04.075862Z",
"url": "https://files.pythonhosted.org/packages/78/a2/f830bb9d9d29f1e1dd532fc93efc01d43f3d0a2912e20a244bbf73885f9c/zid-1.3.0-cp39-abi3-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4f2866e37d0c2797b39c0d6eb2bd2ed3fd6b3fe1c6ac99a9daf8adb6a0f5c2fc",
"md5": "c8b9913429af2f3f5e804d0a37b55b7a",
"sha256": "effeacd9d543accd0b785a5fc107207e0e74afc28e97dece871dea85533f2e30"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "c8b9913429af2f3f5e804d0a37b55b7a",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 202915,
"upload_time": "2024-10-26T02:07:05",
"upload_time_iso_8601": "2024-10-26T02:07:05.905195Z",
"url": "https://files.pythonhosted.org/packages/4f/28/66e37d0c2797b39c0d6eb2bd2ed3fd6b3fe1c6ac99a9daf8adb6a0f5c2fc/zid-1.3.0-cp39-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0db4ded92205a3a4185be6f0e5aff7a01a88431a53b9566f71e9e22ff9377d35",
"md5": "1d2857c45a652bc9b517cd657c07c991",
"sha256": "b1a9b93b4ac9635591e5e6e61ce98f10685d903b20eaf756697e71187e500b2a"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "1d2857c45a652bc9b517cd657c07c991",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 210705,
"upload_time": "2024-10-26T02:07:07",
"upload_time_iso_8601": "2024-10-26T02:07:07.622525Z",
"url": "https://files.pythonhosted.org/packages/0d/b4/ded92205a3a4185be6f0e5aff7a01a88431a53b9566f71e9e22ff9377d35/zid-1.3.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f909638cb46064c7de1feb9b701ed480956ba73961dea218983624e38cc3b143",
"md5": "de2c4bb5743a4311cb3d260e9eb2f7c5",
"sha256": "20dcf553c7eaf430e70203339b7477631ae7d5baabda530dc3587ea78a7cc608"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "de2c4bb5743a4311cb3d260e9eb2f7c5",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 220656,
"upload_time": "2024-10-26T02:07:08",
"upload_time_iso_8601": "2024-10-26T02:07:08.701143Z",
"url": "https://files.pythonhosted.org/packages/f9/09/638cb46064c7de1feb9b701ed480956ba73961dea218983624e38cc3b143/zid-1.3.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c724ed61c4ab7e7f42cb35082a3407c8fc0014c8021686411f620868b6b6281b",
"md5": "22d3df76e7475a06c624c4e10ffa7116",
"sha256": "9e9369b2cb54a0ba09106eb4f6ebf337f3cc61fcabdfbec13688ae6ff042676d"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-musllinux_1_2_aarch64.whl",
"has_sig": false,
"md5_digest": "22d3df76e7475a06c624c4e10ffa7116",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 418697,
"upload_time": "2024-10-26T02:07:10",
"upload_time_iso_8601": "2024-10-26T02:07:10.223002Z",
"url": "https://files.pythonhosted.org/packages/c7/24/ed61c4ab7e7f42cb35082a3407c8fc0014c8021686411f620868b6b6281b/zid-1.3.0-cp39-abi3-musllinux_1_2_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9440fa976b60cff6b387d3c528c43c16da441bf77fd94c6965a90403cb2ae3af",
"md5": "d7be948b2bb7ac16143e14528e479e90",
"sha256": "69d6baa740ff71bb19caa4a24031f5889a8a24734a300e11be3b113c5ab71959"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-musllinux_1_2_x86_64.whl",
"has_sig": false,
"md5_digest": "d7be948b2bb7ac16143e14528e479e90",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 401447,
"upload_time": "2024-10-26T02:07:11",
"upload_time_iso_8601": "2024-10-26T02:07:11.607969Z",
"url": "https://files.pythonhosted.org/packages/94/40/fa976b60cff6b387d3c528c43c16da441bf77fd94c6965a90403cb2ae3af/zid-1.3.0-cp39-abi3-musllinux_1_2_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9750d07236016b8d6767ca70cd42697a2a6877b45413817c1b6d836157cd58f",
"md5": "5c621391018b4560c28a7e860be25181",
"sha256": "85d82e16ba90f44fe8b55434cf2cca286b4c1847d4235fdc72e067b2bbaa5cda"
},
"downloads": -1,
"filename": "zid-1.3.0-cp39-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "5c621391018b4560c28a7e860be25181",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 106204,
"upload_time": "2024-10-26T02:07:13",
"upload_time_iso_8601": "2024-10-26T02:07:13.137168Z",
"url": "https://files.pythonhosted.org/packages/a9/75/0d07236016b8d6767ca70cd42697a2a6877b45413817c1b6d836157cd58f/zid-1.3.0-cp39-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "369f59b447652aa62bab4076430cfabb8d35ed14cf0f4fe4ab4cdf9c870d7d78",
"md5": "97037ee7e94fe78475fd88a541384e6f",
"sha256": "a0656fec82da66f9c0f07d09c19470ddef887c878ba8c3d5f7d210b7766de786"
},
"downloads": -1,
"filename": "zid-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "97037ee7e94fe78475fd88a541384e6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22985,
"upload_time": "2024-10-26T02:07:14",
"upload_time_iso_8601": "2024-10-26T02:07:14.053801Z",
"url": "https://files.pythonhosted.org/packages/36/9f/59b447652aa62bab4076430cfabb8d35ed14cf0f4fe4ab4cdf9c870d7d78/zid-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 02:07:14",
"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
