Metadata-Version: 2.4
Name: joyofpy
Version: 0.1.0
Summary: Companion teaching datasets and utilities for The Joy of Python
Author-email: John Francis Mukulu <john.f.mukulu@gmail.com>
License-Expression: MIT
Keywords: python,data-science,education,datasets,teaching
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
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 :: Education
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# joyofpy

`joyofpy` is the companion Python package for *The Joy of Python*.

The initial release provides the small, deterministic teaching datasets used
by the data-science lessons without requiring readers to manage lesson-data
filesystem paths manually.

## Installation

For ordinary use:

```bash
python -m pip install joyofpy
```

For a reproducible book environment, pin the version:

```bash
python -m pip install joyofpy==0.1.0
```

## Load a teaching dataset

```python
from joyofpy.datasets import load_sample_csv

learner_support = load_sample_csv("learner_support.csv")
print(learner_support.head())
```

The `.csv` suffix is optional:

```python
learner_support = load_sample_csv("learner_support")
```

Keyword arguments accepted by `pandas.read_csv` are forwarded:

```python
daily_support = load_sample_csv(
    "daily_support",
    parse_dates=["timestamp"],
)
```

## Discover the bundled datasets

```python
from joyofpy.datasets import list_datasets, describe_dataset

print(list_datasets())
print(describe_dataset("learner_support"))
```

## Initial datasets

| Dataset | Rows | Columns |
|---|---:|---:|
| `daily_support.csv` | 90 | 4 |
| `distance_cluster.csv` | 72 | 3 |
| `knn_activity.csv` | 60 | 3 |
| `learner_support.csv` | 240 | 12 |
| `location_week.csv` | 5 | 6 |
| `messy_learner.csv` | 6 | 6 |
| `monthly_location_support.csv` | 60 | 7 |
| `support_wait.csv` | 84 | 2 |

## Stability principle

Published CSV files are versioned teaching snapshots. They are not regenerated
at import time.

The R20 data-generation code and blueprint are retained under
`provenance/r20/` in the source repository so that the origin of each
snapshot remains auditable without making the generator itself part of the
stable learner-facing API.

## License

The package code is released under the MIT License.

The bundled R20 teaching fixtures are treated as project-created educational
fixtures. See `DATA_PROVENANCE.md` and `provenance/r20/` for their recorded
origin. If any fixture is later replaced with third-party data, its source and
license must be documented before release.
