Metadata-Version: 2.4
Name: pyedstem
Version: 0.1.0
Summary: Easy-to-use Python client for the Ed Stem API
Project-URL: Homepage, https://github.com/AlexDrBanana/pyedstem
Project-URL: Repository, https://github.com/AlexDrBanana/pyedstem
Project-URL: Issues, https://github.com/AlexDrBanana/pyedstem/issues
Author: AlexDrBanana
Keywords: api-client,ed-stem,edstem,education,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Requires-Dist: markdownify>=1.2.0
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: pydantic>=2.11.3
Description-Content-Type: text/markdown

# pyedstem

Typed Python client for the Ed Stem API.

`pyedstem` provides a small, sync-first interface for common Ed Stem tasks such
as listing active courses, retrieving discussion threads, reading lessons, and
posting answers back to Ed using the XML document format the API expects.

## Installation

### Install with pip

```bash
pip install pyedstem
```

### Add to a uv project

```bash
uv add pyedstem
```

## Configuration

You can create a client directly with an API token:

```python
from pyedstem import EdStemClient

client = EdStemClient(api_token="your-edstem-token")
```

Or load configuration from environment variables:

- `EDSTEM_API_TOKEN` — required
- `EDSTEM_BASE_URL` — optional, defaults to `https://edstem.org/api`
- `EDSTEM_TIMEOUT_SECONDS` — optional, defaults to `30.0`

```python
from pyedstem import EdStemClient

with EdStemClient.from_env() as client:
    current_user = client.user.get_current_user()
```

## Quick start

### List active courses

```python
from pyedstem import EdStemClient

with EdStemClient.from_env() as client:
    active_courses = client.courses.list_active()

for course in active_courses:
    print(course.id, course.code, course.name)
```

### Fetch unanswered discussion threads

```python
from pyedstem import EdStemClient

course_id = 12345

with EdStemClient.from_env() as client:
    threads = client.workflows.list_course_unanswered_threads(course_id)

for thread in threads:
    print(f"#{thread.number}: {thread.title}")
```

### Post an answer

```python
from pyedstem import EdStemClient

with EdStemClient.from_env() as client:
    client.threads.post_answer(
        thread_id=67890,
        markdown="Hi there,\n\nThanks for the question...",
    )
```

## Features

- typed models for common Ed Stem responses
- sync-first client API with resource groups
- workflow helpers for active-course and unanswered-thread automation
- markdown-to-Ed document conversion for answer posting
- opt-in live contract tests for undocumented API drift detection

## Development

Clone the repository, then install development dependencies with uv:

```bash
uv sync --group dev
```

Run the test suite:

```bash
uv run pytest tests
```

### Live contract tests

The repository includes an opt-in live suite under `tests/live/` that probes
documented Ed endpoints so API changes can be detected early.

Safe read-only live tests:

```bash
EDSTEM_RUN_LIVE_TESTS=1 uv run pytest tests/live/test_endpoint_contracts.py tests/live/test_restricted_endpoint_contracts.py
```

Opt-in write test for posting answers:

```bash
EDSTEM_RUN_WRITE_TESTS=1 \
EDSTEM_WRITE_TEST_THREAD_ID=12345 \
uv run pytest tests/live/test_write_endpoint_contracts.py
```

Only enable the write suite when it is safe to mutate real Ed data.

## Publishing

Build distribution artifacts with:

```bash
uv build
```

Publish to PyPI with:

```bash
uv publish
```

`uv publish` expects PyPI credentials or trusted publishing to be configured in
the environment where you run the release.
