Temporale

A comprehensive Python datetime library with nanosecond precision, timezone support, and flexible date/time operations.

Features

• Core Types: Date, Time, DateTime, Duration, Period, Interval
• Nanosecond Precision: Sub-microsecond accuracy for all temporal operations
• Timezone Support: UTC offset model with simple timezone handling
• Rich Arithmetic: Add durations to dates, compute differences, chain operations
• Multiple Formats: ISO 8601, RFC 3339, and custom strftime patterns
• JSON Serialization: Round-trip serialization with type preservation
• Format Inference: Automatically detect and parse various date/time formats
• Relative Parsing: Parse natural language like "yesterday", "next Monday", "3 days ago"

Installation

pip install temporale

Quick Start

from temporale import Date, Time, DateTime, Duration

# Create dates
today = Date.today()
birthday = Date(1990, 5, 15)

# Create times
now = Time.now()
meeting = Time(14, 30)

# Create datetimes
appointment = DateTime(2024, 3, 15, 14, 30)

# Duration arithmetic
future = today + Duration(days=30)
age = today - birthday  # Returns Duration

# Formatting
print(appointment.to_iso_format())  # "2024-03-15T14:30:00"

Requirements

• Python 3.10 or later

Development

# Clone the repository
git clone https://github.com/tugtool/temporale
cd temporale

# Create virtual environment and install
uv venv .tug-test-venv
uv pip install --python .tug-test-venv/bin/python pytest
uv pip install --python .tug-test-venv/bin/python -e .

# Run tests
.tug-test-venv/bin/python -m pytest tests/ -v

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.