Metadata-Version: 2.4
Name: heliclockter
Version: 3.0.0
Summary: A robust way of dealing with datetimes in python by ensuring all datetimes are timezone aware at runtime.
Author-email: Peter Nilsson <peter.nilsson@channable.com>
License: BSD 3-Clause License
        
        Copyright (c) 2022, Channable
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/channable/heliclockter
Keywords: datetime,heliclockter,timezone,timezones,tz,tzinfo
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: all
Requires-Dist: bandit; extra == "all"
Requires-Dist: ruff; extra == "all"
Requires-Dist: mypy; extra == "all"
Requires-Dist: pydantic>=2; extra == "all"
Requires-Dist: pylint; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: parameterized; extra == "all"
Requires-Dist: toml; extra == "all"
Requires-Dist: tzdata; extra == "all"
Dynamic: license-file

# Heliclockter

[![PyPI](https://img.shields.io/pypi/v/heliclockter)](https://pypi.org/project/heliclockter/)
[![License](https://img.shields.io/github/license/channable/heliclockter)](https://github.com/channable/heliclockter/blob/master/LICENSE)
[![Python Versions](https://img.shields.io/pypi/pyversions/heliclockter)](https://pypi.org/project/heliclockter/)

**Timezone-aware datetimes for Python that just work.**

`heliclockter` is a timezone-aware datetime library that ensures your timestamps are always timezone-aware. It's statically type checkable and runtime enforceable.

## Installation

```bash
pip install heliclockter
```

## Quick Start

```python
from heliclockter import datetime_utc, datetime_local, datetime_tz

# UTC datetime
utc_now = datetime_utc.now()
# datetime_utc(2022, 11, 4, 15, 28, 10, 478176, tzinfo=zoneinfo.ZoneInfo(key='UTC'))

# Local timezone datetime  
local_now = datetime_local.now()

# Any timezone datetime
from zoneinfo import ZoneInfo
paris_tz = datetime_tz.now(tz=ZoneInfo("Europe/Paris"))

# Create a timestamp 2 hours in the future
future = datetime_utc.future(hours=2)

# Parse strings (naive timestamps assumed UTC)
parsed = datetime_utc.strptime('2022-11-04T15:49:29', '%Y-%m-%dT%H:%M:%S')
```

## Why heliclockter?

Python's standard `datetime` allows "naive" datetimes without timezone info, leading to bugs when:
- Mixing naive and aware datetimes (causes runtime TypeErrors)
- Deploying across different timezones
- Forgetting to add `tzinfo` when creating datetimes

`heliclockter` enforces timezone-aware datetimes at the type level, catching these issues before production.

## Key Features

- **Always timezone-aware** - No more naive datetime accidents
- **Type safe** - Full typing support for better IDE experience  
- **Zero dependencies** - Lightweight, uses only standard library
- **Pydantic support** - Automatic integration when Pydantic is installed
- **Python 3.10+** - Modern Python for modern applications

## Examples

### Timezone conversions

```python
from heliclockter import datetime_utc, datetime_tz
from zoneinfo import ZoneInfo

# Start with UTC
utc_time = datetime_utc.now()

# To convert to different timezones, create custom classes
class datetime_tokyo(datetime_tz):
    assumed_timezone_for_timezone_naive_input = ZoneInfo('Asia/Tokyo')

class datetime_ny(datetime_tz):
    assumed_timezone_for_timezone_naive_input = ZoneInfo('America/New_York')

# Convert using from_datetime
tokyo_time = datetime_tokyo.from_datetime(utc_time)
ny_time = datetime_ny.from_datetime(utc_time)
```

### Handling naive datetimes

```python
from heliclockter import datetime_utc, datetime_tz
from datetime import datetime

# datetime_utc assumes UTC for naive inputs
naive_dt = datetime(2022, 11, 4, 15, 30, 0)
utc_dt = datetime_utc.from_datetime(naive_dt)  # OK - assumes UTC

# datetime_tz requires explicit timezone
try:
    tz_dt = datetime_tz.from_datetime(naive_dt)  # Raises error
except Exception as e:
    print(e)  # "Cannot create aware datetime from naive if no tz is assumed"
```

### Custom timezone classes

```python
from zoneinfo import ZoneInfo
from heliclockter import datetime_tz

class datetime_cet(datetime_tz):
    """Datetime guaranteed to be in CET timezone."""
    assumed_timezone_for_timezone_naive_input = ZoneInfo('CET')

# Parse naive timestamps as CET
aware_dt = datetime_cet.strptime('2022-11-04T15:49:29', '%Y-%m-%dT%H:%M:%S')
```

### Type safety with mypy

```python
from heliclockter import datetime_utc, datetime_local

def schedule_task(when: datetime_utc) -> None:
    """Schedule a task at a specific UTC time."""
    print(f"Task scheduled for {when.isoformat()}")

# Type checker ensures only UTC datetimes are passed
utc_time = datetime_utc.now()
schedule_task(utc_time)  # ✓ OK

local_time = datetime_local.now()  
schedule_task(local_time)  # ✗ Type error
```

## API Overview

### Core Classes

- **`datetime_tz`** - Base class for timezone-aware datetimes
- **`datetime_utc`** - Always UTC (naive inputs assumed UTC)
- **`datetime_local`** - Always local timezone (naive inputs assumed local)

### Key Methods

- `now()` - Current time
- `from_datetime()` - Convert from standard datetime
- `strptime()` - Parse string to datetime
- `future()/past()` - Create relative timestamps
- `astimezone()` - Convert to other timezone   

## About the Name

`heliclockter` is a portmanteau of "clock" and "helicopter". Like a [helicopter parent](https://en.wikipedia.org/wiki/Helicopter_parent), it strictly supervises your datetime handling, ensuring you never make timezone mistakes.

## Contributing

We welcome contributions! See [CONTRIBUTING.md](https://github.com/channable/heliclockter/blob/master/CONTRIBUTING.md).

## Python and Pydantic compatibility

The table below shows which Pydantic and Python versions are supported for which heliclockter version.
Note that the latest version of heliclockter dropped support for Pydantic v1 code completely, meaning that you
also can't use heliclockter in combination with the `pydantic.v1` module in Pydantic v2.

| heliclockter version | Pydantic support | Python support               |
|----------------------|------------------|------------------------------|
| 1.0                  | v1               | 3.9, 3.10, 3.11, 3.12, 3.13  |
| 1.1, 1.2, 1.3        | v1, v2           | 3.9, 3.10, 3.11, 3.12, 3.13  |
| 2.0                  | v1, v2           | 3.10, 3.11, 3.12, 3.13       |
| 3.0                  | v2               | 3.10, 3.11, 3.12, 3.13, 3.14 |

## License

BSD 3-Clause License. See [LICENSE](https://github.com/channable/heliclockter/blob/master/LICENSE).
