Metadata-Version: 2.3
Name: trap-schema
Version: 0.1.1
Summary: An unofficial implementation of the Camtrap DP 1.0.2 datapackage standard with explicit Python dataclasses and pydantic. Intended to help developers with exporting their data to the Camtrap DP 1.0.2 datapackage format.
Author: asgersvenning
Author-email: asgersvenning <asgersvenning@ecos.au.dk>
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: frictionless>=5.19.0
Requires-Dist: geojson>=3.2.0
Requires-Dist: numpy>=2.4.4
Requires-Dist: pandas>=3.0.2
Requires-Dist: pydantic>=2.13.3
Requires-Dist: ipykernel>=7.2.0 ; extra == 'notebook'
Requires-Dist: ipywidgets>=8.1.8 ; extra == 'notebook'
Requires-Dist: pytest>=8.0.0 ; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0 ; extra == 'test'
Requires-Dist: pytest-benchmark>=4.0.0 ; extra == 'test'
Requires-Python: >=3.12
Provides-Extra: notebook
Provides-Extra: test
Description-Content-Type: text/markdown

[![PyPI version](https://img.shields.io/pypi/v/trap-schema.svg)](https://pypi.org/project/trap-schema/)
[![Python Versions](https://img.shields.io/pypi/pyversions/trap-schema.svg)](https://pypi.org/project/trap-schema/)
[![CI Status](https://github.com/asgersvenning/trap-schema/actions/workflows/ci.yaml/badge.svg)](https://github.com/asgersvenning/trap-schema/actions)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# trap-schema

An unofficial, strictly-typed implementation of the [Camtrap DP 1.0.2](https://camtrap-dp.tdwg.org/) datapackage standard. 

`trap-schema` uses Python dataclasses and Pydantic to provide robust, schema-aware data structures. It is designed to help developers easily parse, validate, and export camera trap data into the official Frictionless Data format without second-guessing schema constraints or having the documentation open on a second monitor.

## Features

* **Strict Validation:** Built on `pydantic` to enforce constraints (e.g., coordinate bounds, unique IDs, valid media types) at instantiation.
* **Ergonomic Tables:** Treat tabular data natively. Tables act as columnar data structures but guarantee per-row validation.
* **Auto-Synced Documentation:** Docstrings and schema attributes are automatically kept in sync with the official Camtrap DP JSON Schemas using a custom AST transformer.

## Installation

This project uses [`uv`](https://github.com/astral-sh/uv) for fast and reliable package management.

To add `trap-schema` to your project:

```bash
uv add trap-schema
```

## Quick Start

```py
from trap_schema.tables import DeploymentRow, DeploymentTable

# 1. Create validated rows
deployment = DeploymentRow(
    deploymentID="dep_001",
    latitude=56.2,
    longitude=10.4,
    deploymentStart="2026-04-25T10:00:00Z",
    deploymentEnd="2026-05-25T10:00:00Z",
)

# 2. Group into a Table (validates unique keys and types)
table = DeploymentTable(rows=[deployment])

# 3. Export to Camtrap DP standard CSV
table.save("out_dir")
```

## Development

```bash
git clone https://github.com/asgersvenning/trap-schema.git
cd trap-schema
uv sync --all-groups
```

### Update docstrings

We use `libcst` and `frictionless` to seamlessly and automatically integrate the official docstrings for table and metadata fields.

To update these run:

```py
uv run tools/docstrings.py
```

### Linting

```bash
[uv] ruff check --ignore E501
```

### Testing

```bash
uv run pytest tests
```

## License

[MIT](LICENSE)