Metadata-Version: 2.1
Name: polars-scheduler
Version: 0.1.0
Summary: A Polars plugin for easily scheduling recurring events with constraints.
Author-Email: Louis Maddox <louismmx@gmail.com>
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: Implementation :: CPython
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
Project-URL: Homepage, https://github.com/lmmx/polars-scheduler
Project-URL: Repository, https://github.com/lmmx/polars-scheduler.git
Requires-Python: >=3.9
Provides-Extra: polars
Requires-Dist: polars>=1.21.0; extra == "polars"
Provides-Extra: polars-lts-cpu
Requires-Dist: polars-lts-cpu>=1.21.0; extra == "polars-lts-cpu"
Provides-Extra: dev
Requires-Dist: pre-commit>=4.1.0; extra == "dev"
Requires-Dist: pytest>=8.3.4; extra == "dev"
Description-Content-Type: text/markdown

# Polars Scheduler

A Polars plugin for easily scheduling recurring events with constraints.

## Installation

```python
pip install polars-scheduler[polars]
```

On older CPUs run:

```python
pip install polars-scheduler[polars-lts-cpu]
```

## Usage

The plugin adds a `scheduler` namespace to Polars DataFrames with methods for registering events and
constraints:

```python
import polars as pl
import polars_scheduler

# Create a new empty schedule
schedule = pl.DataFrame().scheduler.new()

# Add simple meal and medication schedule
schedule = schedule.scheduler.add(
    event="breakfast",
    category="meal",
    unit="serving",
    frequency="1x daily",
)

...
```

The idea is that you have a DataFrame with a schedule of the day so far perhaps
(in this case I don't as it's still a proof-of-concept) and then you have the recurring events
expressed as a schedule with constraints.

This schedule of constraints would get built up (as in this example, see `examples/nutrition.py`)
and then you would validate or schedule ahead.

```py
┌──────────────┬────────────┬─────────┬────────┬─────────┬───────────┬──────────────┬──────────────┐
│ Event        ┆ Category   ┆ Unit    ┆ Amount ┆ Divisor ┆ Frequency ┆ Constraints  ┆ Note         │
│ ---          ┆ ---        ┆ ---     ┆ ---    ┆ ---     ┆ ---       ┆ ---          ┆ ---          │
│ str          ┆ str        ┆ str     ┆ f64    ┆ i64     ┆ str       ┆ list[str]    ┆ str          │
╞══════════════╪════════════╪═════════╪════════╪═════════╪═══════════╪══════════════╪══════════════╡
│ breakfast    ┆ meal       ┆ serving ┆ null   ┆ null    ┆ 1x daily  ┆ []           ┆ null         │
│ lunch        ┆ meal       ┆ serving ┆ null   ┆ null    ┆ 1x daily  ┆ []           ┆ null         │
│ dinner       ┆ meal       ┆ serving ┆ null   ┆ null    ┆ 1x daily  ┆ []           ┆ null         │
│ vitamin      ┆ supplement ┆ pill    ┆ null   ┆ null    ┆ 1x daily  ┆ ["with       ┆ null         │
│              ┆            ┆         ┆        ┆         ┆           ┆ breakfast"]  ┆              │
│ antibiotic   ┆ medication ┆ pill    ┆ null   ┆ null    ┆ 2x daily  ┆ ["≥1h after  ┆ null         │
│              ┆            ┆         ┆        ┆         ┆           ┆ meal"]       ┆              │
│ probiotic    ┆ supplement ┆ capsule ┆ null   ┆ null    ┆ 1x daily  ┆ ["≥2h after  ┆ null         │
│              ┆            ┆         ┆        ┆         ┆           ┆ antibiotic"] ┆              │
│ protein      ┆ supplement ┆ gram    ┆ 30.0   ┆ null    ┆ 1x daily  ┆ ["≤30m after ┆ mix with     │
│ shake        ┆            ┆         ┆        ┆         ┆           ┆ gym OR with  ┆ 300ml water  │
│              ┆            ┆         ┆        ┆         ┆           ┆ breakfast"]  ┆              │
│ ginger       ┆ supplement ┆ shot    ┆ null   ┆ null    ┆ 1x daily  ┆ ["before     ┆ null         │
│              ┆            ┆         ┆        ┆         ┆           ┆ breakfast"]  ┆              │
│ gym          ┆ exercise   ┆ session ┆ null   ┆ null    ┆ 3x weekly ┆ []           ┆ null         │
└──────────────┴────────────┴─────────┴────────┴─────────┴───────────┴──────────────┴──────────────┘
```
