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 to 0. 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:

1. Date chunk: First 3 characters, for the number of days since the epoch.
2. Time chunk: Remaining characters, for the time of day:
   • Minute precision (default): 3 characters, for the minutes past midnight.
   • Second precision (with -s option): 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.