{"id":13567228,"url":"https://github.com/anthonynsimon/timeflake","last_synced_at":"2025-05-15T09:07:25.366Z","repository":{"id":44702374,"uuid":"233312247","full_name":"anthonynsimon/timeflake","owner":"anthonynsimon","description":"Timeflake is a 128-bit, roughly-ordered, URL-safe UUID.","archived":false,"fork":false,"pushed_at":"2023-09-01T13:24:07.000Z","size":113,"stargazers_count":813,"open_issues_count":5,"forks_count":17,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-14T03:02:19.547Z","etag":null,"topics":["python","uuid"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/timeflake/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anthonynsimon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-01-11T23:36:52.000Z","updated_at":"2025-03-31T08:47:07.000Z","dependencies_parsed_at":"2024-01-10T19:10:21.140Z","dependency_job_id":null,"html_url":"https://github.com/anthonynsimon/timeflake","commit_stats":{"total_commits":90,"total_committers":7,"mean_commits":"12.857142857142858","dds":0.06666666666666665,"last_synced_commit":"94c801f9ad08c0af5c77e7b4d48a8e15a66c2c1b"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonynsimon%2Ftimeflake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonynsimon%2Ftimeflake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonynsimon%2Ftimeflake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonynsimon%2Ftimeflake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anthonynsimon","download_url":"https://codeload.github.com/anthonynsimon/timeflake/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254289594,"owners_count":22046128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","uuid"],"created_at":"2024-08-01T13:02:26.340Z","updated_at":"2025-05-15T09:07:20.355Z","avatar_url":"https://github.com/anthonynsimon.png","language":"Python","readme":"\n# Timeflake\n[![PyPi Latest Version](https://img.shields.io/pypi/v/timeflake)](https://pypi.org/project/timeflake/)\n[![PyPi Downloads](https://img.shields.io/pypi/dm/timeflake)](https://pypi.org/project/timeflake/)\n[![License](https://img.shields.io/github/license/anthonynsimon/timeflake)](https://github.com/anthonynsimon/timeflake/blob/master/LICENSE)\n\nTimeflake is a 128-bit, roughly-ordered, URL-safe UUID. Inspired by Twitter's Snowflake, Instagram's ID and Firebase's PushID.\n\n\n## Features\n\n- **Fast.** Roughly ordered (K-sortable), incremental timestamp in most significant bits enables faster indexing and less fragmentation on database indices (vs UUID v1/v4).\n- **Unique enough.** With 1.2e+24 unique timeflakes per millisecond, even if you're creating 50 million of them *per millisecond* the chance of a collision is still 1 in a billion. You're likely to see a collision when creating 1.3e+12 (one trillion three hundred billion) timeflakes per millisecond.*\n- **Efficient.** 128 bits are used to encode a timestamp in milliseconds (48 bits) and a cryptographically generated random number (80 bits).\n- **Flexible.** Out of the box encodings in 128-bit unsigned int, hex, URL-safe base62 and raw bytes. Fully compatible with uuid.UUID.\n\n\\* Please consider how the [Birthday Paradox](https://betterexplained.com/articles/understanding-the-birthday-paradox/) might affect your use case. Also read the security note on this readme.\n\n## Why?\nThis could be useful to you, if you're looking for a UUID with the following properties:\n- You want to have UUIDs in URLs that are not predictable (vs auto-increment integers).\n- They should be random, but roughly-ordered over time so that your MySQL/Postgres indices stay fast and efficient as the dataset grows.\n- And simple to use across multiple machines (no coordination or centralized system required).\n- It would be nice if they were compatible with standard 128-bit UUID representations (many libraries in Python handle uuid.UUID, but no third-party types).\n\nSome existing alternatives which I considered:\n- **UUIDv1** but the timestamp bytes are not sequential and gives away network information.\n- **UUIDv4** but they're mostly random, and can mess up the performance on clustered indexes.\n- **ULID** but the approach to incrementing the sequence during the same millisecond makes it more predictable.\n- **KSUID** but it's 160-bit, so unfortunately not compatible with standard 128-bit UUIDs.\n\n\n## Usage\n\n```python\nimport timeflake\n\n# Create a random Timeflake\nflake = timeflake.random()\n\u003e\u003e\u003e Timeflake(base62='00mx79Rjxvfgr8qat2CeQDs')\n\n# Get the base62, int, hex or bytes representation\nflake.base62\n\u003e\u003e\u003e '00mx79Rjxvfgr8qat2CeQDs'\n\nflake.hex\n\u003e\u003e\u003e '016fa936bff0997a0a3c428548fee8c9'\n\nflake.int\n\u003e\u003e\u003e 1909005012028578488143182045514754249\n\nflake.bytes\n\u003e\u003e\u003e b'\\x01o\\xa96\\xbf\\xf0\\x99z\\n\u003cB\\x85H\\xfe\\xe8\\xc9'\n\n# Convert to the standard library's UUID type\nflake.uuid\n\u003e\u003e\u003e UUID('016fa936-bff0-997a-0a3c-428548fee8c9')\n\n# Get the timestamp component\nflake.timestamp\n\u003e\u003e\u003e 1579091935216\n\n# Get the random component\nflake.random\n\u003e\u003e\u003e 724773312193627487660233\n\n# Parse an existing flake (you can also pass bytes, hex or int representations)\ntimeflake.parse(from_base62='0002HCZffkHWhKPVdXxs0YH')\n\u003e\u003e\u003e Timeflake('0004fbc6872f70fc9e27355a499e8b6d')\n\n# Create from a user defined timestamp or random value:\ntimeflake.from_values(1579091935216, 724773312193627487660233)\n\u003e\u003e\u003e Timeflake('016fa936bff0997a0a3c428548fee8c9')\n```\n\n\n## Spec\n\n128 bits are used to encode:\n\n1) UNIX-time in milliseconds (48 bits)\n2) Cryptographically generated random number (80 bits)\n\nFor example, the timeflake `016fb4209023b444fd07590f81b7b0eb` (hex) encodes the following:\n\n```\n016fb4209023  +  b444fd07590f81b7b0eb\n      |                   |\n      |                   |\n  timestamp            random\n  [48 bits]           [80 bits]\n```\n\nIn Python:\n\n```python\nflake = timeflake.parse(from_hex='016fb4209023b444fd07590f81b7b0eb')\nflake.timestamp = 1579275030563  # 2020-01-17T15:30:30.563 UTC\nflake.random = 851298578153087956398315\n```\n\n## Alphabets\n\nA custom base62 alphabet representation is included, modified to preserve lexicographical order when sorting strings using this encoding. The `hex` representation has a max length of 32 characters, while the `base62` will be 22 characters. Padding is required to be able to derive the encoding from the string length.\n\nThe following are all valid representations of the same Timeflake:\n\n```\nint    = 1909226360721144613344160656901255403\nhex    = 016fb4209023b444fd07590f81b7b0eb\nbase62 = 02i2XhN7hAuaFh3MwztcMd\n```\n\nYou can convert a timeflake to any alphabet using the `itoa` (integer to ASCII) function:\n\n```python\nfrom timeflake.utils import itoa\n\nflake = timeflake.random()\nitoa(flake.int, alphabet=timeflake.flake.HEX, padding=32)\n```\n\n## Provided extensions\n### Django model fields\nYou can use timeflakes as primary keys for your models. These fields currently support MySQL, Postgres and Sqlite3.\n\nExample usage:\n```python\nfrom timeflake.extensions.django import TimeflakePrimaryKeyBinary\n\nclass Item(models.Model):\n   item_id = TimeflakePrimaryKeyBinary()\n   # ...\n```\n\n### Peewee ORM\nSee [this gist](https://gist.github.com/bibby/3c7a162fb83a833850af8ff668d5441b) for an example.\n\n## Note on security\nSince the timestamp part is predictable, the search space within any given millisecond is 2^80 random numbers, which is meant to avoid collisions, not to secure or hide information. You should not be using timeflakes for password-reset tokens, API keys or for anything which is security sensitive. There are better libraries which are meant for this use case (for example, the standard library's [secrets module](https://docs.python.org/3/library/secrets.html)).\n\n## Note on privacy\nPlease be aware of the privacy implications that time based IDs can have. As Timeflake encodes the precise time in which the ID was created, this could potentially reveal:\n- User timezone.\n- Geographic location: If the client software creates multiple associated IDs at the same time (like an article and embedded media), then the differences in timestamps of the IDs can reveal the latency of the client's network connection to the server. This reveals user geographic location. This can also happen if the client creates a single ID and the server adds an additional timestamp to the object.\n- User identity (de-anonymizing)\n   1. Most Android apps include Google's libraries for working with push notifications. And some iOS apps that use Google Cloud services also load the libraries. These Google libraries automatically load Google Analytics which records the names of every screen the users view in the app, and sends them to Google. So Google knows that userN switched from screen \"New Post\" to screen \"Published Post\" at time K.\n   2. Some ISPs record and sell user behavior data. For example, SAP knows that userN made a request to appM's API at time K.\n   3. Even if the posting app does not share its user behavior data with third-parties, the user could post and then immediately switch to an app that does share user behavior data. This provides data points like \"userN stopped using an app that does not record analytics at time K\".\n   4. Operating Systems (Android, Windows, macOS) send user behavior data to their respective companies.\n   5. Browsers and Browser Extensions send user behavior data to many companies. Data points like \"userN visited a URL at example.com at time K\" can end up in many databases and sold.\n   6. Posting times combined with traffic analysis can perfectly de-anonymize users.\n- How long the user took to write the post. This can happen if the app creates the ID when the user starts editing the post and also shares a timestamp of the publication or save time.\n- Whether or not the user edited the post after posting it. This can happen if the posts's displayed time doesn't match the timestamp in the ID.\n- Whether or not the user prepared the post in advance and set it to post automatically. If the timestamp is very close to a round numbered time like 21:00:00, it was likely posted automatically. If the posting platform does not provide such functionality, then the user must be using some third-party software or custom software to do it. This information can help de-anonymize the user.\n\n## Supported versions\nRight now the codebase is only tested with Python 3.7+.\n\n## Dependencies\nNo dependencies other than the standard library.\n\n## Contribute\nWant to hack on the project? Any kind of contribution is welcome!\nSimply follow the next steps:\n\n- Fork the project.\n- Create a new branch.\n- Make your changes and write tests when practical.\n- Commit your changes to the new branch.\n- Send a pull request, it will be reviewed shortly.\n- In case you want to add a feature, please create a new issue and briefly explain what the feature would consist of. For bugs or requests, before creating an issue please check if one has already been created for it.\n\n## Contributors\nThank you for making this project better!\n\n- [@mleonhard](https://github.com/mleonhard) - documented privacy implications of time based IDs.\n- [@making](https://github.com/making) - Implemented Java version of Timeflake.\n- [@Gioni06](https://github.com/Gioni06) - Implemented Go version of Timeflake.\n- [@zzzz465](https://github.com/zzzz465) - Implementation of TS/JS version of Timeflake.\n- [@bibby](https://github.com/bibby) - Added extension for peewee ORM.\n- [@sebst](https://github.com/sebst) - Improved compatibility with standard UUID class. \n- [@yedpodtrzitko](https://github.com/yedpodtrzitko) - Codebase improvements. \n\n## Changelog\nPlease see the [CHANGELOG](CHANGELOG.md) for more details.\n\n## Implementations in other languages\n* [Java](https://github.com/making/timeflake4j)\n* [Go](https://github.com/Gioni06/go-timeflake)\n* [Javascript/Typescript](https://github.com/zzzz465/timeflake4js)\n\n## License\nThis project is licensed under the MIT license. Please read the [LICENSE](LICENSE) file for more details.\n\n## Prior art\n\n- [Sharding \u0026 IDs at Instagram](https://instagram-engineering.com/sharding-ids-at-instagram-1cf5a71e5a5c)\n- [Announcing Snowflake: Twitter](https://blog.twitter.com/engineering/en_us/a/2010/announcing-snowflake.html)\n- [The 2^120 Ways to Ensure Unique Identifiers](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html)\n\n\n\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonynsimon%2Ftimeflake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthonynsimon%2Ftimeflake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonynsimon%2Ftimeflake/lists"}