Timeflake

0.4.3 · active · verified Fri Apr 17

Timeflake is a Python library for generating 128-bit, roughly-ordered, URL-safe UUIDs, inspired by Twitter's Snowflake, Instagram's ID, and Firebase's PushID. It combines a timestamp with a random component. The current version is 0.4.3, with releases typically occurring a few times a year to introduce new features or address issues.

Common errors

```
AttributeError: module 'timeflake' has no attribute 'Timeflake'
```
cause Attempting to access the `Timeflake` class (with an uppercase 'T') directly from the `timeflake` module after version 0.4.0.

fix The class was renamed to `timeflake` (lowercase). Use `import timeflake; tf_obj = timeflake.timeflake()` to instantiate a new object.
```
TypeError: 'module' object is not callable
```
cause Attempting to call the `timeflake` module directly as a function (e.g., `tf = timeflake()`) without referring to the constructor function.

fix To generate a new timeflake, call the `timeflake()` function *within* the module: `import timeflake; tf_obj = timeflake.timeflake()`.
```
NameError: name 'Timeflake' is not defined
```
cause This usually happens when you remove `from timeflake import Timeflake` (due to the v0.4.0 breaking change) but your code still tries to call `Timeflake()` directly.

fix Update your code to `import timeflake` and then use `timeflake.timeflake()` to create instances.

Warnings

breaking The main class name changed from `Timeflake` to `timeflake` (lowercase). This affects how you import and instantiate the object.
Fix: Instead of `from timeflake import Timeflake; tf = Timeflake()`, use `import timeflake; tf = timeflake.timeflake()`.
breaking The primary way to instantiate a Timeflake object changed. The top-level `timeflake()` function now returns an instance of the `timeflake` class.
Fix: Previous versions might have used `Timeflake.random()` or similar. The new recommended way is `timeflake.timeflake()` for a new random ID, or `timeflake.parse()` to decode.
gotcha Timeflake IDs are 'roughly-ordered', not strictly monotonic. While the timestamp component ensures general ordering, the random component means two IDs generated in the exact same millisecond might not be strictly ordered relative to each other. This is typically acceptable for most distributed systems where perfect ordering is not a strict requirement.
Fix: Understand the ordering guarantees for your use case. If strict monotonicity within the same millisecond is critical, Timeflake may not be the ideal solution without additional sequencing.

Install

pip install timeflake Install Timeflake

Imports

timeflake
wrong:
```
from timeflake import Timeflake
```
correct:
```
import timeflake
```
The main class was renamed from `Timeflake` to `timeflake` (lowercase) in v0.4.0. The top-level `timeflake()` function is now the primary way to instantiate a Timeflake object. Importing `Timeflake` directly is no longer possible after v0.4.0.

Quickstart

This quickstart demonstrates how to generate a new Timeflake, access its various representations (integer, hex, base62, UUID, datetime), and parse an existing Timeflake string back into an object.

import timeflake

# Generate a new timeflake
tf = timeflake.timeflake()

print(f"Generated Timeflake: {tf}")
print(f"As integer: {tf.int}")
print(f"As hex: {tf.hex}")
print(f"As base62: {tf.base62}")
print(f"As UUID: {tf.uuid}")
print(f"As datetime: {tf.datetime}")

# Encode and decode a timeflake
encoded_tf = tf.base62
decoded_tf = timeflake.parse(encoded_tf)
print(f"\nOriginal: {tf}, Decoded: {decoding_tf}")

view raw JSON →