sonyflake
=========
Sonyflake is a distributed unique ID generator inspired by `Twitter's Snoflake <https://blog.twitter.com/2010/announcing-snowflake>`_.
This project is a Python implementation inspired by the original `sony/sonyflake <https://github.com/sony/sonyflake>`_ project, written in Go.
Sonyflake focuses on lifetime and performance on many host/core environment. So it has a different bit assignment from Snowflake. By default, a Sonyflake ID is composed of:
- 39 bits for time in units of 10 msec
- 8 bits for a sequence number
- 16 bits for a machine id
As a result, Sonyflake has the following advantages and disadvantages:
- The lifetime (174 years) is longer than that of Snowflake (69 years)
- It can work in more distributed machines (2^16) than Snowflake (2^10)
- It can generate 2^8 IDs per 10 msec at most in a single instance (fewer than Snowflake)
However, if you want more generation rate in a single host,
you can easily run multiple Sonyflake instances using threads or asyncio tasks.
In addition, you can adjust the lifetime and generation rate of Sonyflake
by customizing the bit assignment and the time unit.
Installation
============
**Python 3.11 or higher is required**
Stable
------
.. code-block:: shell
# Linux/macOS
python -m pip install -U sonyflake
# Windows
py -3 -m pip install -U sonyflake
Development
-----------
.. code-block:: shell
# Linux/macOS
python -m pip install -U "sonyflake @ git+https://github.com/iyad-f/sonyflake"
# Windows
py -3 -m pip install -U "sonyflake @ git+https://github.com/iyad-f/sonyflake"
Usage
=====
You can configure Sonyflake with the following options:
- ``bits_sequence`` is the bit length of a sequence number.
If bits_sequence is not provided, the default bit length is used, which is 8.
If bits_sequence is 31 or more, an error is raised.
- ``bits_machine_id`` is the bit length of a machine ID.
If bits_machine_id is not provided, the default bit length is used, which is 16.
If bits_machine_id is 31 or more, an error is raised.
- ``time_unit`` is the time unit of Sonyflake.
If time_unit is not provided, the default time unit is used, which is 10 msec.
If time_unit is less than a millisecond, an error is raised.
- ``start_time`` is the time since which the Sonyflake time is defined as the elapsed time.
If start_time is not before the current time, an error is raised.
- ``machine_id`` is the unique ID of a Sonyflake instance.
If machine_id is not provided, the default machine_id is used, which is the lower 16 bits of the private IP address.
- ``check_machine_id`` validates the uniqueness of a machine ID.
If check_machine_id returns false, an error is raised.
If check_machine_id is not provided, no validation is done.
The bit length of time is calculated by ``63 - bits_sequence - bits_machine_id``.
If it is less than 32, an error is raised.
To obtain a new unique ID, use the ``next_id`` or ``next_id_async`` methods depending on whether you
are in a synchronous or asynchronous environment.
Sync
----
.. code-block:: python
import datetime
from sonyflake import Sonyflake
start_time = datetime.datetime(2025, 1, 1, 0, 0, 0, 0, datetime.UTC)
sf = Sonyflake(start_time=start_time)
next_id = sf.next_id()
print(next_id)
Async
-----
.. code-block:: python
import asyncio
import datetime
from sonyflake import Sonyflake
async def main() -> None:
start_time = datetime.datetime(2025, 1, 1, 0, 0, 0, 0, datetime.UTC)
sf = Sonyflake(start_time=start_time)
next_id = await sf.next_id_async()
print(next_id)
asyncio.run(main())
``next_id`` or ``next_id_async`` can continue to generate IDs for about 174 years from ``start_time`` by default.
But after the Sonyflake time is over the limit, ``next_id`` raises an error.
Examples
========
Examples can be found in the `examples directory <https://github.com/iyad-f/sonyflake/tree/main/examples>`_
Links
=====
- `Documentation <https://sonyflake.readthedocs.io/en/latest/>`_
- `Source code <https://github.com/iyad-f/sonyflake>`_
Contact
=======
Send a DM on discord at `iyad8888`.
Raw data
{
"_id": null,
"home_page": null,
"name": "sonyflake",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "snowflake, snowflake py, snowflake.py, sonyflake, sonyflake py",
"author": "Iyad",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c0/2e/b87929cf8efa61e7a7996ead93a81cbf55ef63b25c8ed9c452228261d3ce/sonyflake-2.0.0.tar.gz",
"platform": null,
"description": "sonyflake\n=========\n\nSonyflake is a distributed unique ID generator inspired by `Twitter's Snoflake <https://blog.twitter.com/2010/announcing-snowflake>`_.\n\nThis project is a Python implementation inspired by the original `sony/sonyflake <https://github.com/sony/sonyflake>`_ project, written in Go.\n\nSonyflake focuses on lifetime and performance on many host/core environment. So it has a different bit assignment from Snowflake. By default, a Sonyflake ID is composed of:\n\n - 39 bits for time in units of 10 msec\n - 8 bits for a sequence number\n - 16 bits for a machine id\n\nAs a result, Sonyflake has the following advantages and disadvantages:\n\n- The lifetime (174 years) is longer than that of Snowflake (69 years)\n- It can work in more distributed machines (2^16) than Snowflake (2^10)\n- It can generate 2^8 IDs per 10 msec at most in a single instance (fewer than Snowflake)\n\nHowever, if you want more generation rate in a single host,\nyou can easily run multiple Sonyflake instances using threads or asyncio tasks.\n\nIn addition, you can adjust the lifetime and generation rate of Sonyflake\nby customizing the bit assignment and the time unit.\n\nInstallation\n============\n\n**Python 3.11 or higher is required**\n\nStable\n------\n\n.. code-block:: shell\n\n # Linux/macOS\n python -m pip install -U sonyflake\n\n # Windows\n py -3 -m pip install -U sonyflake\n\nDevelopment\n-----------\n\n.. code-block:: shell\n\n # Linux/macOS\n python -m pip install -U \"sonyflake @ git+https://github.com/iyad-f/sonyflake\"\n\n # Windows\n py -3 -m pip install -U \"sonyflake @ git+https://github.com/iyad-f/sonyflake\"\n\nUsage\n=====\n\nYou can configure Sonyflake with the following options:\n\n- ``bits_sequence`` is the bit length of a sequence number.\n If bits_sequence is not provided, the default bit length is used, which is 8.\n If bits_sequence is 31 or more, an error is raised.\n\n- ``bits_machine_id`` is the bit length of a machine ID.\n If bits_machine_id is not provided, the default bit length is used, which is 16.\n If bits_machine_id is 31 or more, an error is raised.\n\n- ``time_unit`` is the time unit of Sonyflake.\n If time_unit is not provided, the default time unit is used, which is 10 msec.\n If time_unit is less than a millisecond, an error is raised.\n\n- ``start_time`` is the time since which the Sonyflake time is defined as the elapsed time.\n If start_time is not before the current time, an error is raised.\n\n- ``machine_id`` is the unique ID of a Sonyflake instance.\n If machine_id is not provided, the default machine_id is used, which is the lower 16 bits of the private IP address.\n\n- ``check_machine_id`` validates the uniqueness of a machine ID.\n If check_machine_id returns false, an error is raised.\n If check_machine_id is not provided, no validation is done.\n\nThe bit length of time is calculated by ``63 - bits_sequence - bits_machine_id``.\nIf it is less than 32, an error is raised.\n\nTo obtain a new unique ID, use the ``next_id`` or ``next_id_async`` methods depending on whether you\nare in a synchronous or asynchronous environment.\n\nSync\n----\n\n.. code-block:: python\n\n import datetime\n\n from sonyflake import Sonyflake\n\n start_time = datetime.datetime(2025, 1, 1, 0, 0, 0, 0, datetime.UTC)\n sf = Sonyflake(start_time=start_time)\n next_id = sf.next_id()\n print(next_id)\n\nAsync\n-----\n\n.. code-block:: python\n\n import asyncio\n import datetime\n\n from sonyflake import Sonyflake\n\n\n async def main() -> None:\n start_time = datetime.datetime(2025, 1, 1, 0, 0, 0, 0, datetime.UTC)\n sf = Sonyflake(start_time=start_time)\n next_id = await sf.next_id_async()\n print(next_id)\n\n asyncio.run(main())\n\n``next_id`` or ``next_id_async`` can continue to generate IDs for about 174 years from ``start_time`` by default.\nBut after the Sonyflake time is over the limit, ``next_id`` raises an error.\n\nExamples\n========\nExamples can be found in the `examples directory <https://github.com/iyad-f/sonyflake/tree/main/examples>`_\n\nLinks\n=====\n- `Documentation <https://sonyflake.readthedocs.io/en/latest/>`_\n- `Source code <https://github.com/iyad-f/sonyflake>`_\n\nContact\n=======\nSend a DM on discord at `iyad8888`.",
"bugtrack_url": null,
"license": null,
"summary": "A distributed unique ID generator inspired by Twitter's Snowflake",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/iyad-f/sonyflake",
"Issues": "https://github.com/iyad-f/sonyflake/issues",
"Repository": "https://github.com/iyad-f/sonyflake"
},
"split_keywords": [
"snowflake",
" snowflake py",
" snowflake.py",
" sonyflake",
" sonyflake py"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "966da113272940ebaa800b1e70d1ea24d7bd7a2eef51d9e5c3ed68848fa5f0ae",
"md5": "91a2f92c07aca9b657a5761cf0618969",
"sha256": "9d6ccf3da2bd55d81af3f0ffad0a740ec745dd153cb0614d962c7658153ccd8c"
},
"downloads": -1,
"filename": "sonyflake-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "91a2f92c07aca9b657a5761cf0618969",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8000,
"upload_time": "2025-07-22T12:49:51",
"upload_time_iso_8601": "2025-07-22T12:49:51.161589Z",
"url": "https://files.pythonhosted.org/packages/96/6d/a113272940ebaa800b1e70d1ea24d7bd7a2eef51d9e5c3ed68848fa5f0ae/sonyflake-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c02eb87929cf8efa61e7a7996ead93a81cbf55ef63b25c8ed9c452228261d3ce",
"md5": "709281eadf2066e86e96fe5bfcce55df",
"sha256": "be281dfaecd35f7095de7418e87fc4eefaa6e9883fb257b4053e30a39fe53374"
},
"downloads": -1,
"filename": "sonyflake-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "709281eadf2066e86e96fe5bfcce55df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 14647,
"upload_time": "2025-07-22T12:49:52",
"upload_time_iso_8601": "2025-07-22T12:49:52.276887Z",
"url": "https://files.pythonhosted.org/packages/c0/2e/b87929cf8efa61e7a7996ead93a81cbf55ef63b25c8ed9c452228261d3ce/sonyflake-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 12:49:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iyad-f",
"github_project": "sonyflake",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sonyflake"
}
JSON
