Metadata-Version: 2.4
Name: ed-api-client
Version: 0.1.8
Summary: A client for interacting with the Ed LMS
License: MIT
Author: David Milne
Author-email: d.n.milne@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
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
Requires-Dist: DateTime (>=5.1,<6.0)
Requires-Dist: pylcs (>=0.1.1,<0.2.0)
Requires-Dist: python-dateutil (>=2.9.0,<3.0.0)
Requires-Dist: requests (>=2.31.0,<3.0.0)
Requires-Dist: websocket-client (>=1.6,<2.0)
Description-Content-Type: text/markdown

# ed-api-client

A Python client for the [Ed LMS](https://edstem.org) API, with utilities for analysing student workspace activity.

## Installation

```bash
pip install ed-api-client
```

## Quick start

```python
from ed_api_client import EdClient

client = EdClient(token="your-api-token")

# Retrieve all students in a course
users = client.get_users(course_id=12345, role="student")

# Retrieve the module/lesson structure
modules = client.get_module_structure(course_id=12345)
for module in modules:
    for lesson in module.lessons:
        print(lesson.title)

# Fetch and analyse a student's workspace activity
log = client.get_workspace_log(workspace_id="abc123")
files = client.get_scaffold_files(challenge_id=99)
summary = WorkspaceSummary.from_log(files, log)

print(summary.total_active_time)
for file_id, file in summary.file_summaries.items():
    print(file.path, file.pasted_proportion, file.cursor_entropy)
```

Full API reference: https://dmilne.gitlab.io/ed-api-client

## Development

### Prerequisites

- Python 3.10+
- [Poetry](https://python-poetry.org/docs/#installation)

Install Poetry via Homebrew:

```bash
brew install poetry
```

### Setup

Clone the repository and install all dependencies (including dev dependencies):

```bash
git clone https://gitlab.com/dmilne/ed-api-client.git
cd ed-api-client
poetry install --with dev
```

### Running tests

```bash
poetry run pytest tests/ -v
```

Tests use the `responses` library to mock HTTP calls — no real Ed credentials are needed.

### Viewing the docs locally

```bash
poetry run mkdocs serve
```

Then open http://localhost:8000.

## Publishing a new version

1. Bump the version:

   ```bash
   poetry version patch   # or: minor, major
   ```

2. Configure your PyPI token (first time only):

   ```bash
   poetry config pypi-token.pypi your-token-here
   ```

   Get a token at https://pypi.org/manage/account/token/.

3. Build and publish:

   ```bash
   poetry publish --build
   ```

## CI/CD

The GitLab pipeline (`.gitlab-ci.yml`) runs on every push:

- **test** — runs `pytest` against Python 3.11
- **pages** (main branch only) — builds and deploys the MkDocs site to GitLab Pages at https://dmilne.gitlab.io/ed-api-client

## License

MIT

