Metadata-Version: 2.3
Name: simple-state-tracker
Version: 0.3.0
Summary: A minimal, type-safe, file-backed state tracker using Pydantic models.
License: LICENSE
Author: Max Chis
Author-email: maxachis@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: License :: Other/Proprietary License
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
Requires-Dist: pydantic (>=2.11,<3.0)
Project-URL: Homepage, https://github.com/maxachis/simple-state-tracker
Project-URL: Issues, https://github.com/maxachis/simple-state-tracker/issues
Project-URL: Repository, https://github.com/maxachis/simple-state-tracker
Description-Content-Type: text/markdown

# simple-state-tracker

A minimal, file-backed, type-safe state tracker using Pydantic models — ideal for scripts, scrapers, ETL pipelines, and resumable workflows.


![PyPI](https://img.shields.io/pypi/v/simple-state-tracker)
![Python](https://img.shields.io/pypi/pyversions/simple-state-tracker)
![License](https://img.shields.io/github/license/maxachis/simple-state-tracker)


## Features

- 🧠 Strong typing with `pydantic` models
- 💾 Transparent JSON persistence
- 🧰 Simple `.get()`, `.set()`, `.edit()` API
- ✅ Schema validation and strict key control
- 🪶 Lightweight — no databases, no DAGs, no dependencies beyond `pydantic`


## Installation

```bash
pip install simple-state-tracker
```

---

### Example

```markdown
## Quick Start

```python
from simple_state_tracker import SimpleStateTracker, KeyModel, DataModel

# First, define a key model
class ScrapeKey(KeyModel):
    county: str
    municipality: str
    year: int

# Next, define a data model
class ScrapeState(DataModel):
    scraped: bool = False
    scrape_error: str | None = None
    processed: bool = False
    process_error: str | None = None

# Initialize the tracker
tracker = SimpleStateTracker(ScrapeKey, ScrapeState, path="tracker.json")

key = ScrapeKey(county="DAUPHIN", municipality="HARRISBURG", year=2022)

with tracker.edit(key) as state:
    state.scraped = True
    state.scrape_error = None

tracker.save()

```


---

### Use Cases

- Track which URLs, files, or locations have been processed
- Resume scraping jobs or ETL pipelines
- Store structured state across CLI or batch job invocations
- Replace ad-hoc JSON or YAML logs with something type-safe and self-validating

### Non-Use Cases

Do not use this if
- You are looking for optimization in storage or performance. This is meant to be easy to use and simple to understand, not the fastest or most efficient

## API Overview

### `SimpleStateTracker(key_model, data_model, path)`
Creates a new tracker instance.

- `get(key)` → returns the data model (or `None`)
- `set(key, value)` → manually sets a value
- `edit(key)` → yields a context-managed editable state
- `save()` → writes the cache to disk
- `load()` → reads from disk
- `all()` → returns a shallow copy of all state



