Metadata-Version: 2.4
Name: timeslug
Version: 1.0.2
Summary: Generate a base36 timestamp from an ISO 8601 datetime string
Author-email: 0jar <git@jarema.me>
License-Expression: MIT
Project-URL: Homepage, https://codeberg.org/0jar/timeslug
Project-URL: Repository, https://codeberg.org/0jar/timeslug.git
Project-URL: Issues, https://codeberg.org/0jar/timeslug/issues
Keywords: time,timestamp,base36,slug,datetime,date
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Classifier: Development Status :: 5 - Production/Stable
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# 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`:

```bash
pip install timeslug
```

## CLI usage

Generate a base36 code from any ISO 8601 datetime string:

```bash
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:

```bash
timeslug "2026-05-26T15:30:00" -o 10957
# Output: 7fu0pu
```

Or you can use the same epoch shift and use the current time:

```bash
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:

```python
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](LICENSE).
