<h1 align="center">
<a href="https://www.svix.com">
<img width="120" src="https://avatars.githubusercontent.com/u/80175132?s=200&v=4" />
<p align="center">Svix - Webhooks as a service</p>
</a>
</h1>
# Svix-KSUID (Python)
[](https://pypi.python.org/pypi/svix-ksuid/)
[](https://www.svix.com/slack/)
This library is inspired by [Segment's KSUID](https://segment.com/blog/a-brief-history-of-the-uuid/) implementation:
https://github.com/segmentio/ksuid
For the Rust version, please check out https://github.com/svix/rust-ksuid
## What is a ksuid?
A ksuid is a K sorted UID. In other words, a KSUID also stores a date component, so that ksuids can be approximately
sorted based on the time they were created.
Read more [here](https://segment.com/blog/a-brief-history-of-the-uuid/).
## Usage
```
pip install svix-ksuid
```
```python
from ksuid import Ksuid
ksuid = Ksuid()
```
### Higher timestamp accuracy mode
Ksuids have a 1 second accuracy which is not sufficient for all use-cases. That's why this library exposes a higher accuracy mode which supports accuracy of up to 4ms.
It's fully compatible with normal ksuids, in fact, it outputs valid ksuids. The difference is that it sacrifices one byte of the random payload in favor of this accuracy.
The code too is fully compatible:
```
pip install svix-ksuid
```
```python
from ksuid import KsuidMs
ksuid = KsuidMs()
```
## Examples
### Default ksuid
Generate a ksuid without passing a specific datetime
```python
In [1]: from ksuid import Ksuid
In [2]: ksuid = Ksuid()
In [3]: f"Base62: {ksuid}"
Out[3]: 'Base62: 1srOrx2ZWZBpBUvZwXKQmoEYga2'
In [4]: f"Bytes: {bytes(ksuid)}"
Out[4]: "Bytes: b'\\r5\\xc43\\xe1\\x93>7\\xf2up\\x87c\\xad\\xc7tZ\\xf5\\xe7\\xf2'"
In [5]: f"Datetime: {ksuid.datetime}"
Out[5]: 'Datetime: 2021-05-21 14:04:03'
In [6]: f"Timestamp: {ksuid.timestamp}"
Out[6]: 'Timestamp: 1621627443'
In [7]: f"Payload: {ksuid.payload}"
Out[7]: "Payload: b'\\xe1\\x93>7\\xf2up\\x87c\\xad\\xc7tZ\\xf5\\xe7\\xf2'"
```
### ksuid from datetime
```python
In [1]: datetime = datetime(year=2021, month=5, day=19, hour=1, minute=1, second=1, microsecond=1)
In [2]: datetime
Out[2]: datetime.datetime(2021, 5, 19, 1, 1, 1, 1)
In [3]: ksuid = Ksuid(datetime)
In [4]: ksuid.datetime
Out[4]: datetime.datetime(2021, 5, 19, 1, 1, 1)
In [5]: ksuid.timestamp
Out[5]: 1621407661
```
### ksuid from base62
```python
In [1]: ksuid = Ksuid()
In [2]: ksuid.timestamp
Out[2]: 1621634852
In [3]: f"Base62: {ksuid}"
Out[3]: 'Base62: 1srdszO8Xy2cR6CnARnvxCfRmK4'
In [4]: ksuid_from_base62 = Ksuid.from_base62("1srdszO8Xy2cR6CnARnvxCfRmK4")
In [5]: ksuid_from_base62.timestamp
Out[5]: 1621634852
```
### ksuid from bytes
```python
In [1]: ksuid = Ksuid()
In [2]: ksuid_from_bytes = ksuid.from_bytes(bytes(ksuid))
In [3]: f"ksuid: {ksuid}, ksuid_from_bytes: {ksuid_from_bytes}"
Out[3]: 'ksuid: 1sreAHoz6myPhXghsOdVBoec3Vr, ksuid_from_bytes: 1sreAHoz6myPhXghsOdVBoec3Vr'
In [4]: ksuid == ksuid_from_bytes
Out[4]: True
```
### Compare ksuid(s)
```python
In [1]: ksuid_1 = Ksuid()
In [2]: ksuid_2 = Ksuid.from_bytes(bytes(ksuid_1))
In [3]: f"ksuid_1: {ksuid_1}, ksuid_2: {ksuid_2}"
Out[3]: 'ksuid_1: 1sreAHoz6myPhXghsOdVBoec3Vr, ksuid_2: 1sreAHoz6myPhXghsOdVBoec3Vr'
In [4]: ksuid_1 == ksuid_2
Out[4]: True
In [5]: ksuid_1
Out[5]: 1tM9eRSTrHIrrH5SMEW24rtvIOF
In [6]: ksuid_2
Out[6]: 1tM9eRSTrHIrrH5SMEW24rtvIOF
```
### Order of ksuid(s)
```python
In [1]: ksuid_1 = Ksuid()
In [2]: ksuid_1.timestamp
Out[2]: 1621963256
In [3]: ksuid_2 = Ksuid()
In [4]: ksuid_2.timestamp
Out[4]: 1621963266
In [5]: ksuid_1 < ksuid_2
Out[5]: True
In [6]: ksuid_1 <= ksuid_2
Out[6]: True
In [7]: ksuid_1 >= ksuid_2
Out[7]: False
In [8]: ksuid_1 > ksuid_2
Out[8]: False
```
### License
ksuid source code is available under an MIT [License](./LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/svixhq/python-ksuid/",
"name": "svix-ksuid",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "svix,ksuid",
"author": "Svix",
"author_email": "development@svix.com",
"download_url": "https://files.pythonhosted.org/packages/a1/7a/0c98b77ca01d64f13143607b88273a13110d659780b93cb1333abebf8039/svix-ksuid-0.6.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\n <a href=\"https://www.svix.com\">\n <img width=\"120\" src=\"https://avatars.githubusercontent.com/u/80175132?s=200&v=4\" />\n <p align=\"center\">Svix - Webhooks as a service</p>\n </a>\n</h1>\n\n# Svix-KSUID (Python)\n\n\n\n\n[](https://pypi.python.org/pypi/svix-ksuid/)\n[](https://www.svix.com/slack/)\n\nThis library is inspired by [Segment's KSUID](https://segment.com/blog/a-brief-history-of-the-uuid/) implementation:\nhttps://github.com/segmentio/ksuid\n\nFor the Rust version, please check out https://github.com/svix/rust-ksuid\n\n## What is a ksuid?\n\nA ksuid is a K sorted UID. In other words, a KSUID also stores a date component, so that ksuids can be approximately \nsorted based on the time they were created. \n\nRead more [here](https://segment.com/blog/a-brief-history-of-the-uuid/).\n\n## Usage\n\n```\npip install svix-ksuid\n```\n\n```python\nfrom ksuid import Ksuid\n\nksuid = Ksuid()\n```\n\n### Higher timestamp accuracy mode\n\nKsuids have a 1 second accuracy which is not sufficient for all use-cases. That's why this library exposes a higher accuracy mode which supports accuracy of up to 4ms.\n\nIt's fully compatible with normal ksuids, in fact, it outputs valid ksuids. The difference is that it sacrifices one byte of the random payload in favor of this accuracy.\n\nThe code too is fully compatible:\n\n```\npip install svix-ksuid\n```\n\n```python\nfrom ksuid import KsuidMs\n\nksuid = KsuidMs()\n```\n\n## Examples\n\n### Default ksuid\n\nGenerate a ksuid without passing a specific datetime\n\n```python\nIn [1]: from ksuid import Ksuid\n\nIn [2]: ksuid = Ksuid()\n\nIn [3]: f\"Base62: {ksuid}\"\nOut[3]: 'Base62: 1srOrx2ZWZBpBUvZwXKQmoEYga2'\n\nIn [4]: f\"Bytes: {bytes(ksuid)}\"\nOut[4]: \"Bytes: b'\\\\r5\\\\xc43\\\\xe1\\\\x93>7\\\\xf2up\\\\x87c\\\\xad\\\\xc7tZ\\\\xf5\\\\xe7\\\\xf2'\"\n\nIn [5]: f\"Datetime: {ksuid.datetime}\"\nOut[5]: 'Datetime: 2021-05-21 14:04:03'\n\nIn [6]: f\"Timestamp: {ksuid.timestamp}\"\nOut[6]: 'Timestamp: 1621627443'\n\nIn [7]: f\"Payload: {ksuid.payload}\"\nOut[7]: \"Payload: b'\\\\xe1\\\\x93>7\\\\xf2up\\\\x87c\\\\xad\\\\xc7tZ\\\\xf5\\\\xe7\\\\xf2'\"\n```\n\n### ksuid from datetime\n\n```python\nIn [1]: datetime = datetime(year=2021, month=5, day=19, hour=1, minute=1, second=1, microsecond=1)\n\nIn [2]: datetime\nOut[2]: datetime.datetime(2021, 5, 19, 1, 1, 1, 1)\n\nIn [3]: ksuid = Ksuid(datetime)\n\nIn [4]: ksuid.datetime\nOut[4]: datetime.datetime(2021, 5, 19, 1, 1, 1)\n\nIn [5]: ksuid.timestamp\nOut[5]: 1621407661\n```\n\n### ksuid from base62\n\n```python\nIn [1]: ksuid = Ksuid()\n\nIn [2]: ksuid.timestamp\nOut[2]: 1621634852\n\nIn [3]: f\"Base62: {ksuid}\"\nOut[3]: 'Base62: 1srdszO8Xy2cR6CnARnvxCfRmK4'\n\nIn [4]: ksuid_from_base62 = Ksuid.from_base62(\"1srdszO8Xy2cR6CnARnvxCfRmK4\")\n\nIn [5]: ksuid_from_base62.timestamp\nOut[5]: 1621634852\n```\n\n### ksuid from bytes\n\n```python\nIn [1]: ksuid = Ksuid()\n\nIn [2]: ksuid_from_bytes = ksuid.from_bytes(bytes(ksuid))\n\nIn [3]: f\"ksuid: {ksuid}, ksuid_from_bytes: {ksuid_from_bytes}\"\nOut[3]: 'ksuid: 1sreAHoz6myPhXghsOdVBoec3Vr, ksuid_from_bytes: 1sreAHoz6myPhXghsOdVBoec3Vr'\n\nIn [4]: ksuid == ksuid_from_bytes\nOut[4]: True\n```\n\n### Compare ksuid(s)\n\n```python\nIn [1]: ksuid_1 = Ksuid()\n\nIn [2]: ksuid_2 = Ksuid.from_bytes(bytes(ksuid_1))\n\nIn [3]: f\"ksuid_1: {ksuid_1}, ksuid_2: {ksuid_2}\"\nOut[3]: 'ksuid_1: 1sreAHoz6myPhXghsOdVBoec3Vr, ksuid_2: 1sreAHoz6myPhXghsOdVBoec3Vr'\n\nIn [4]: ksuid_1 == ksuid_2\nOut[4]: True\n\nIn [5]: ksuid_1\nOut[5]: 1tM9eRSTrHIrrH5SMEW24rtvIOF\n\nIn [6]: ksuid_2\nOut[6]: 1tM9eRSTrHIrrH5SMEW24rtvIOF\n```\n\n\n### Order of ksuid(s)\n\n```python\nIn [1]: ksuid_1 = Ksuid()\n\nIn [2]: ksuid_1.timestamp\nOut[2]: 1621963256\n\nIn [3]: ksuid_2 = Ksuid()\n\nIn [4]: ksuid_2.timestamp\nOut[4]: 1621963266\n\nIn [5]: ksuid_1 < ksuid_2\nOut[5]: True\n\nIn [6]: ksuid_1 <= ksuid_2\nOut[6]: True\n\nIn [7]: ksuid_1 >= ksuid_2\nOut[7]: False\n\nIn [8]: ksuid_1 > ksuid_2\nOut[8]: False\n```\n\n### License\n\nksuid source code is available under an MIT [License](./LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pure-Python KSUID implementation",
"version": "0.6.2",
"project_urls": {
"Homepage": "https://github.com/svixhq/python-ksuid/"
},
"split_keywords": [
"svix",
"ksuid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a17a0c98b77ca01d64f13143607b88273a13110d659780b93cb1333abebf8039",
"md5": "85f99063917d1f9ffa2c730198d98b31",
"sha256": "beb95bd6284bdbd526834e233846653d2bd26eb162b3233513d8f2c853c78964"
},
"downloads": -1,
"filename": "svix-ksuid-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "85f99063917d1f9ffa2c730198d98b31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6957,
"upload_time": "2023-07-07T09:18:24",
"upload_time_iso_8601": "2023-07-07T09:18:24.717240Z",
"url": "https://files.pythonhosted.org/packages/a1/7a/0c98b77ca01d64f13143607b88273a13110d659780b93cb1333abebf8039/svix-ksuid-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-07 09:18:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "svixhq",
"github_project": "python-ksuid",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "svix-ksuid"
}
JSON
