Metadata-Version: 2.4
Name: time_unifier
Version: 0.1.0
Summary: Strict timezone-safe datetime handling for Python
Author: Nour Ibrahim
License: MIT
Project-URL: Homepage, https://github.com/yourusername/time_unifier
Project-URL: Repository, https://github.com/yourusername/time_unifier
Project-URL: Issues, https://github.com/yourusername/time_unifier/issues
Keywords: datetime,timezone,utc,time,python,timezone-safe,datetime-validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tzdata
Dynamic: license-file

# 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.

```python
from datetime import datetime

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

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

```python
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

```python
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

```python
from time_unifier import now_utc, now_zone

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

### Convert Time

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

### Compare Time

```python
ut1 = now_utc()
ut2 = now_utc()

print(ut1 < ut2)
```

### Duration

```python
d = ut2 - ut1

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

### JSON

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

### Zones

```python
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

```python
from datetime import datetime
from time_unifier import UTCTime

UTCTime(datetime.now())  # invalid
```

```python
from time_unifier import now_utc

ut = now_utc()  # valid
```

### Invalid timezone

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

### Mixed types

```python
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

```python
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
