Metadata-Version: 2.4
Name: calgebra
Version: 0.7.0
Summary: A tiny DSL for calendar interval algebra - compose, filter, and query time ranges using set operations.
Author: ashenfad
License: MIT
Project-URL: Homepage, https://github.com/ashenfad/calgebra
Project-URL: Bug Tracker, https://github.com/ashenfad/calgebra/issues
Project-URL: Documentation, https://github.com/ashenfad/calgebra#readme
Project-URL: Source, https://github.com/ashenfad/calgebra
Keywords: calendar,scheduling,intervals,time,algebra,dsl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Scheduling
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: sortedcontainers>=2.4.0
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: uv; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: gcsa>=2.6.0; extra == "dev"
Provides-Extra: google-calendar
Requires-Dist: gcsa>=2.6.0; extra == "google-calendar"
Dynamic: license-file

# calgebra 🗓️

A tiny DSL for merging and searching over calendar-like intervals.

## Installation

```bash
pip install calgebra

# Or with Google Calendar support
pip install calgebra[google-calendar]
```

## Quick Start

```python
from calgebra import day_of_week, time_of_day, hours, at_tz, HOUR

# Compose time windows
weekdays = day_of_week(["monday", "tuesday", "wednesday", "thursday", "friday"])
work_hours = time_of_day(start=9*HOUR, duration=8*HOUR, tz="US/Pacific")
business_hours = weekdays & work_hours

# Find free time
busy = monday_meetings | friday_focus
free = business_hours - busy
long_slots = free & (hours >= 2)

# Query results
at = at_tz("US/Pacific")
meeting_options = list(long_slots[at("2025-01-01"):at("2025-02-01")])
```

Intervals use **exclusive end bounds** (`[start, end)`), matching Python slicing. `Interval(start=10, end=13)` represents 3 seconds. Intervals are automatically clipped to query bounds.

**Core Features:**
- **Set operations**: `|` (union), `&` (intersection), `-` (difference), `~` (complement)
- **Recurring patterns**: `recurring()`, `day_of_week()`, `time_of_day()` (RFC 5545 via `python-dateutil`)
- **Aggregations**: `total_duration`, `max_duration`, `min_duration`, `count_intervals`, `coverage_ratio`
- **Transformations**: `buffer()` (add time around intervals), `merge_within()` (coalesce nearby intervals)
- **Google Calendar**: `calgebra.gcsa.calendars()` for read/write operations

**→ [Tutorial](TUTORIAL.md)** | **[API Reference](API.md)** | **[Google Calendar Guide](calgebra/docs/GCSA.md)**


## License

MIT License - see LICENSE file for details.
