time-unifier 0.1.0

Strict timezone-safe datetime handling for Python

TimeUnifier

Eliminate naive datetime bugs in Python with strict, explicit timezone handling.

Python's built-in datetime is flexible but that flexibility allows subtle bugs that often go unnoticed until production.

from datetime import datetime

a = datetime.now()
b = datetime.utcnow()

print(a > b)  # unclear, depends on context

from time_unifier import now_utc

a = now_utc()
b = now_utc()

print(a > b)  # always valid

TimeUnifier removes ambiguity by enforcing correctness at the API level.

Quick Start

from time_unifier import now_utc

ut = now_utc()
zt = ut.to_zone("Europe/Stockholm")
ut2 = zt.to_utc()

Core Idea

• All time must have a timezone
• UTC is the internal standard
• No mixing between UTC and zoned time
• All conversions are explicit

If something is incorrect, it fails immediately.

Basic Usage

Create Time

from time_unifier import now_utc, now_zone

ut = now_utc()
zt = now_zone("Europe/Stockholm")

Convert Time

zt = ut.to_zone("Europe/Stockholm")
ut2 = zt.to_utc()

Compare Time

ut1 = now_utc()
ut2 = now_utc()

print(ut1 < ut2)

Duration

d = ut2 - ut1

print(d.hours())
print(d.minutes())
print(d.days())

JSON

json_value = ut.to_json()
ut_back = type(ut).from_json(json_value)

Zones

from time_unifier import is_valid_zone, list_zones

print(is_valid_zone("Europe/Stockholm"))
print(list_zones()[:5])

What Happens When You Do It Wrong

Naive datetime

from datetime import datetime
from time_unifier import UTCTime

UTCTime(datetime.now())  # invalid

from time_unifier import now_utc

ut = now_utc()  # valid

Invalid timezone

now_utc().to_zone("Invalid/Timezone")  # invalid
now_utc().to_zone("Europe/Stockholm")  # valid

Mixed types

from time_unifier import now_utc, now_zone

ut = now_utc()
zt = now_zone("Europe/Stockholm")

ut == zt  # invalid
ut == zt.to_utc()  # valid

Design

TimeUnifier is built on a simple rule:

Incorrect time handling should be impossible, not just discouraged.

• Explicit over implicit
• No hidden conversions
• Fail fast on invalid usage
• Minimal API with strong guarantees

Comparison

• datetime: flexible but allows unsafe patterns
• pendulum / arrow: convenience-focused

TimeUnifier prioritizes correctness and predictability.

Recommended Style

import time_unifier as tu

ut = tu.now_utc()
zt = ut.to_zone("Europe/Stockholm")

Guarantees

• No naive datetimes
• No implicit conversions
• Clear and predictable errors
• Strict separation between time types