timeslug
A lightweight Python CLI tool that generates base36 timestamps from ISO 8601 datetime strings. Has no dependencies.
Installation
You can install the package via pip:
pip install timeslug
CLI usage
Generate a base36 code from any ISO 8601 datetime string:
timeslug "2026-05-26T15:30:00Z"
# Output: fw70pu
If no timezone is specified in the input string, timeslug falls back to UTC.
Options
--now: Use the current UTC time.-o,--offset: Number of days to increment from the epoch (1970-01-01) before generating the code. Defaults to0. Use this to shrink the output for recent dates if needed.--offset-from: ISO date string to use as the base for the epoch offset (e.g.2000-01-01). This computes the days from 1970-01-01 and adds it to-o.-s,--seconds: Include second precision. Uses 4 characters for the time instead of 3.
The following example increments the epoch by 10,957 days (to 2000-01-01) and generates a code from 2026-05-26 15:30:00 UTC:
timeslug "2026-05-26T15:30:00" -o 10957
# Output: 7fu0pu
Or you can use the same epoch shift and use the current time:
timeslug --now --offset-from 2000-01-01
Output format
The generated base36 code consists of two parts:
- Date chunk: First 3 characters, for the number of days since the epoch.
- Time chunk: Remaining characters, for the time of day:
- Minute precision (default): 3 characters, for the minutes past midnight.
- Second precision (with
-soption): 4 characters, for the seconds past midnight.
Python API
You can import the functions in your Python projects:
from timeslug import generate_code, encode_base36, decode_base36
# Generate a base36 code from an ISO 8601 string
slug = generate_code("2026-05-26T15:30:00Z")
print(slug) # Output: fw70pu
# Generate a base36 code with second precision
slug_sec = generate_code("2026-05-26T15:30:00Z", seconds=True)
print(slug_sec) # Output: fw71720
# Encode any integer to base36
encoded = encode_base36(12345)
print(encoded) # Output: 9ix
# Decode a base36 string back to an integer
decoded = decode_base36("9ix")
print(decoded) # Output: 12345
License
This project is licensed under the MIT License.
Metadata
Release files for timeslug 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| timeslug-1.0.2.tar.gz | 4.7 kB | Without provenance | Details for timeslug-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| timeslug-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for timeslug-1.0.2-py3-none-any.whl |
Total release size: 9.7 kB
Release files / timeslug-1.0.2.tar.gz
| Download URL | timeslug-1.0.2.tar.gz |
|---|---|
| Size | 4.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec42cd6ef95a2a2881714e7043897faa0a21c8a4158ebe5e89f507c4ef37e1b8
|
|
BLAKE2b-256 checksum How to use checksums |
dd51c9aff2221a81d5fe349c34e259499ed70eb411ee014ad62e30c75d4519da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / timeslug-1.0.2-py3-none-any.whl
| Download URL | timeslug-1.0.2-py3-none-any.whl |
|---|---|
| Size | 5.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
293e413eabaf484d9f8fdd18abdcc5f48032737c6c2a318bb62eb34d9f2283bb
|
|
BLAKE2b-256 checksum How to use checksums |
b1173955ef26d54e12c031321e9491aa4fbcabcc4e7dc4d024f9a88bdaa7c861
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for timeslug 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.