Metadata-Version: 2.4
Name: dateutil-gorman
Version: 0.1.3
Summary: Utilities and value objects for working with the Gorman calendar.
Project-URL: Homepage, https://github.com/BGarber42/dateutil_gorman
Project-URL: Repository, https://github.com/BGarber42/dateutil_gorman
Project-URL: Issues, https://github.com/BGarber42/dateutil_gorman/issues
Project-URL: Changelog, https://github.com/BGarber42/dateutil_gorman/releases
Author-email: Brent Garber <me@bgarber.work>
License: MIT
Keywords: calendar,date,datetime,gorman-calendar,utilities
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.11.0; extra == 'dev'
Provides-Extra: lint
Requires-Dist: ruff>=0.11.0; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Provides-Extra: typecheck
Requires-Dist: mypy>=1.10.0; extra == 'typecheck'
Description-Content-Type: text/markdown

# dateutil-gorman

`dateutil-gorman` is a typed Python package for converting between Gregorian
dates and the Gorman calendar.

## Features

- `src/` layout with a small, explicit public API.
- Immutable value objects for regular Gorman dates and intermission days.
- Bidirectional Gregorian conversion helpers.
- String parsing for common Gorman date formats.
- No runtime dependencies outside the Python standard library.

## Installation

```bash
pip install dateutil-gorman
```

For local development with `uv`:

```bash
uv sync --extra dev
```

## Quick Start

```python
from datetime import date, datetime

from dateutil_gorman import (
    GormanDate,
    gregorian_to_gorman,
    gorman_to_gregorian,
    parse_gorman,
)

gorman_value = gregorian_to_gorman(date(2024, 1, 1))
assert str(gorman_value) == "1 March 2024"

gregorian_value = gorman_to_gregorian(2024, 6, 15)
assert gregorian_value.isoformat() == "2024-06-03"

parsed = parse_gorman("June 15, 2024 14:30")
assert parsed == datetime(2024, 4, 8, 14, 30)

same_day = GormanDate.fromisoformat("2024-06-10")
assert same_day.to_gregorian().isoformat() == "2024-06-10"
```

## Usage

### Convert Gregorian values

```python
from datetime import date

from dateutil_gorman import gregorian_to_gorman

assert str(gregorian_to_gorman(date(2024, 12, 30))) == "Intermission 1 2024"
assert str(gregorian_to_gorman(date(2024, 12, 31))) == "Intermission 2 2024"
```

### Work with immutable value objects

```python
from dateutil_gorman import GormanDate

gorman_date = GormanDate(year=2024, month=6, day=15)
updated = gorman_date.replace(day=1)

assert str(gorman_date) == "15 Sextilis 2024"
assert str(updated) == "1 Sextilis 2024"
```

### Parse Gorman strings

```python
from dateutil_gorman import parse_gorman

assert parse_gorman("15 June 2024").isoformat() == "2024-04-08T00:00:00"
assert parse_gorman("Intermission 1 2024 08:15").isoformat() == "2024-12-30T08:15:00"
```

## Public API

### Classes

- `GormanDate`: Immutable regular-month date with conversion, week-calendar,
  ordinal, and replacement helpers.
- `Intermission`: Immutable year-end intermission day with Gregorian
  conversion and replacement helpers.

### Functions

- `gregorian_to_gorman(d)`: Convert a Gregorian `date` or `datetime`.
- `gorman_to_gregorian(year, month, day)`: Convert a regular Gorman date.
- `intermission_to_gregorian(year, day)`: Convert an intermission day.
- `parse_gorman(date_string)`: Parse supported Gorman date strings into a
  Gregorian `datetime`.

### Constants

- `GORMAN_MONTHS`: Ordered tuple of month names used by the Gorman calendar.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy src
```

## Contributing

1. Fork the repository and create a feature branch.
2. Keep the public API typed and documented with Google-style docstrings.
3. Add or update tests for behavior changes.
4. Run `uv run pytest`, `uv run ruff check .`, and `uv run mypy src` before opening a pull request.

## License

Released under the MIT License.
