Metadata-Version: 2.4
Name: time_unifier
Version: 0.1.2
Summary: Strict datetime safety layer and CI linter for Python backend reliability
Author: Nour Ibrahim
License: MIT License
        
        Copyright (c) 2026 Nour Ibrahim
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nourromeo/time_unifier
Project-URL: Repository, https://github.com/nourromeo/time_unifier
Project-URL: Issues, https://github.com/nourromeo/time_unifier/issues
Keywords: datetime,timezone,utc,time,python,timezone-safe,datetime-validation,lint,ci,backend
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
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
Provides-Extra: pydantic
Requires-Dist: pydantic>=1.10; extra == "pydantic"
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy>=1.4; extra == "sqlalchemy"
Provides-Extra: test
Requires-Dist: hypothesis>=6; extra == "test"
Requires-Dist: pydantic>=1.10; extra == "test"
Requires-Dist: sqlalchemy>=1.4; extra == "test"
Dynamic: license-file

# time_unifier

`time_unifier` is **not** a datetime library.  
It is a strict datetime safety layer + CI guardrail for backend systems.

**Positioning:** `time_unifier` prevents production incidents caused by datetime misuse.

## 30-Second Quickstart

```bash
pip install time_unifier
pip install -e .  # for local development
time-unifier check .
```

## Minimal Real Example (Bug Caught + Fixed)

```python
# bad
from datetime import datetime
created = datetime.utcnow()

# linter catch
# TU002 datetime.utcnow() usage detected

# fixed
from datetime import datetime, timezone
created = datetime.now(timezone.utc)
```

## Core Philosophy

- UTC internally
- Zoned time at boundaries only
- No naive datetime
- No implicit conversions
- Explicit conversion everywhere

## Real Bugs This Prevents

### JWT expiry drift
- Bad code: `datetime.utcnow() + timedelta(...)`
- Why tests pass: single timezone CI environment
- Why production fails: services interpret naive timestamps differently
- How caught: `TU002` + strict runtime parsing

### Scheduling errors
- Bad code: `datetime.fromtimestamp(ts)`
- Why tests pass: developer/CI host timezone matches assumption
- Why production fails: workers in different regions schedule at different wall times
- How caught: `TU004` + autofix to `tz=timezone.utc`

### Timezone ordering bugs
- Bad code: comparing datetime objects with string timestamps or mixed awareness
- Why tests pass: happy-path lexical ordering
- Why production fails: DST and offset shifts reorder events
- How caught: `TU012` + `TU013`

## Why not Pendulum/Arrow?

Pendulum and Arrow improve datetime ergonomics. They do not provide guardrails as workflow enforcement:

- no CI policy enforcement over your codebase
- no strict UTC-only backend boundary contract
- no static type guard against UTC/Zoned misuse

## Comparison

| Capability | time_unifier | Pendulum | Arrow | Ruff datetime rules |
|---|---|---|---|---|
| Strict UTC runtime contract | Yes | No | No | No |
| Zoned boundary separation | Yes | Partial | Partial | No |
| CI-enforced datetime linting | Yes | No | No | Partial |
| Autofix for backend datetime hazards | Yes | No | No | Partial |
| mypy static UTC/Zoned safety | Yes | No | No | No |

## How time_unifier Prevents Bugs Before Deployment

1. Runtime safety types reject ambiguous datetimes (`UTCTime`, `ZonedTime`).
2. Linter blocks unsafe patterns in PRs (`TU001`-`TU015`).
3. Autofix rewrites common high-risk patterns safely.
4. mypy plugin catches mixed UTC/Zoned misuse at type-check time.
5. CI integration fails builds before risky code merges.

## CLI UX

```bash
time-unifier check . --fail-on error
time-unifier check . --fix
```

Output format:

```text
path:line:column: RULE message
  consequence: real backend impact
  suggestion: exact fix
```

Exit behavior:
- `--fail-on error`: exit non-zero only if any `error` findings exist.
- `--fail-on warning`: exit non-zero for any finding.

## Integration in Developer Workflow

### GitHub Action

Use `.github/workflows/time-unifier.yml` to run:

```bash
time-unifier check .
```

### pre-commit

```yaml
repos:
  - repo: local
    hooks:
      - id: time-unifier
        name: time-unifier
        entry: time-unifier check .
        language: system
```

### Ruff compatibility (no conflict)

- Run Ruff and `time-unifier` side by side in CI.
- Keep Ruff for style/quality; keep `time_unifier` for strict datetime safety policy.
- Do not replace one with the other; they are complementary.

## Integrations

- Pydantic: strict typed field validation
- FastAPI: explicit UTC/zoned boundary parsing
- SQLAlchemy: UTC-only DB boundary type

## Examples and Migration

- Examples: `examples/auth_jwt_expiry.py`, `examples/scheduler_bug.py`, `examples/event_ordering_bug.py`
- Migration guide: `docs/MIGRATION.md`

## What This Is Not

- Not a replacement for `datetime`
- Not a convenience datetime toolkit
- Not a scheduling framework
