Metadata-Version: 2.4
Name: hse-sampletracker-client
Version: 0.1.1
Summary: A Pythonic client library for the SampleTracker SaaS API
Project-URL: Documentation, https://github.com/Alexander Schramm/sampletracker#readme
Project-URL: Issues, https://github.com/Alexander Schramm/sampletracker/issues
Project-URL: Source, https://github.com/Alexander Schramm/sampletracker
Author-email: Alexander Schramm <info@expectiq.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: api,client,hse,laboratory,samples,sampletracker
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
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
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# HSE SampleTracker Client

[![PyPI - Version](https://img.shields.io/pypi/v/hse-sampletracker-client.svg)](https://pypi.org/project/hse-sampletracker-client)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hse-sampletracker-client.svg)](https://pypi.org/project/hse-sampletracker-client)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)

A Pythonic client library for the HSE SampleTracker API - manage laboratory samples, processing steps, and observations with ease.

## Features

- **Synchronous API Client** - Simple, blocking HTTP client using `httpx`
- **Type Hints Throughout** - Fully typed for better IDE support and code safety
- **Command-Line Interface** - Interactive CLI for quick sample management
- **Pydantic-like Models** - Dataclass-based models with `from_dict` constructors
- **Comprehensive Exceptions** - Clear error hierarchy for different failure modes
- **Environment Configuration** - Support for `.env` files and environment variables
- **Pagination Support** - Built-in cursor-based pagination for listing samples

## Installation

```console
pip install hse-sampletracker-client
```

## Quick Start

### Using the Python API

```python
from sampletracker import SampleTrackerClient

# Create a client
client = SampleTrackerClient(
    api_key="your-api-key",
    base_url="https://your-instance.com/api/v1"
)

# List samples
samples = client.list_samples(limit=10)
for sample in samples:
    print(f"{sample.sample_id}: {sample.name}")

# Get detailed sample information
sample = client.load_sample("SAMPLE-123")
print(f"Description: {sample.description}")
print(f"Steps: {sample.stats.step_count}")
print(f"Observations: {sample.stats.observation_count}")

# View history
for event in sample.history:
    if hasattr(event, 'name'):  # StepEvent
        print(f"Step: {event.name}")
    else:  # ObservationEvent
        print(f"Observation: {event.content}")
```

### Using the CLI

Set up your environment:

```bash
# Option 1: Environment variables
export SAMPLETRACKER_API_KEY="your-api-key"
export SAMPLETRACKER_BASE_URL="https://your-instance.com/api/v1"

# Option 2: Create a .env file
echo "SAMPLETRACKER_API_KEY=your-api-key" > .env
echo "SAMPLETRACKER_BASE_URL=https://your-instance.com/api/v1" >> .env
```

List samples:

```console
$ sampletracker list --limit 5
    ID |       Sample ID |                           Name | Steps | Observations
--------------------------------------------------------------------------------
     1 |      sample-001 |                     test batch |     3 |            2
     2 |        M315SO23 |              test batch (Copy) |     3 |            2
```

View sample details:

```console
$ sampletracker view sample-001
Sample Details:
  ID:          1
  Sample ID:   sample-001
  Name:        test batch
  Description: mein erster test
  Owner ID:    2
  Owner Email: admin@example.com
  Created:     2026-04-25 13:14:13.126000+00:00
  Updated:     2026-04-25 13:14:13.126000+00:00
  Steps:       2
  Observations: 2

  History:
    [Step] Backen
      Performed: 2026-04-25 13:20:00+00:00
      Parameters:
        - Temperatur: 210 °C
    [Observation] Das Ding ist heiß
      Created: 2026-04-25 13:21:06.172000+00:00
```

## Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `SAMPLETRACKER_API_KEY` | Your API key | Yes |
| `SAMPLETRACKER_BASE_URL` | API base URL | No (defaults to official SaaS) |

### .env File

Create a `.env` file in your project root:

```
SAMPLETRACKER_API_KEY=your-api-key
SAMPLETRACKER_BASE_URL=https://your-instance.com/api/v1
```

The CLI automatically loads variables from `.env` files in the current or parent directories.

## API Reference

### SampleTrackerClient

The main client class for interacting with the API.

```python
client = SampleTrackerClient(
    api_key: str,           # Your API key
    base_url: str | None,   # Optional base URL
    timeout: float | None   # Optional timeout (default: 30s)
)
```

### Methods

#### `list_samples(limit: int = 10, after_id: int | None = None) -> list[SampleListItem]`

List samples with pagination support.

- `limit`: Number of samples to return (max: 100)
- `after_id`: Cursor for pagination (returns samples with ID > after_id)

#### `load_sample(sample_id: str) -> Sample | None`

Get detailed information about a specific sample, including history.

Returns `None` if the sample doesn't exist.

### Models

#### SampleListItem

Lightweight model for list responses:

- `id`: Internal database ID
- `sample_id`: User-facing sample identifier
- `name`: Sample name
- `description`: Optional description
- `owner_id`: Owner's user ID
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp
- `step_count`: Number of processing steps
- `observation_count`: Number of observations

#### Sample

Detailed model with full history:

- All fields from `SampleListItem`, plus:
- `owner_email`: Email of the owner
- `history`: List of `StepEvent` and `ObservationEvent`
- `stats`: `SampleStats` with aggregated counts

### Exceptions

All exceptions inherit from `SampleTrackerError`:

- `SampleTrackerAuthError` - Authentication failed (401)
- `SampleTrackerNotFoundError` - Resource not found (404)
- `SampleTrackerValidationError` - Request validation failed (422)
- `SampleTrackerRateLimitError` - Rate limit exceeded (429)
- `SampleTrackerAPIError` - Other API errors

## Supported Python Versions

- Python 3.10+
- Python 3.11+
- Python 3.12+
- Python 3.13+
- Python 3.14+
- PyPy 3.10+

## License

`hse-sampletracker-client` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

## Links

- **Documentation**: https://github.com/Alexander Schramm/sampletracker#readme
- **Issues**: https://github.com/Alexander Schramm/sampletracker/issues
- **Source**: https://github.com/Alexander Schramm/sampletracker
- **PyPI**: https://pypi.org/project/hse-sampletracker-client
