hse-sampletracker-client 0.1.2

A Pythonic client library for the SampleTracker SaaS API

HSE SampleTracker Client

A Pythonic client library for the 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

pip install hse-sampletracker-client

Quick Start

Using the Python API

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:

# 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:

$ sampletracker list --limit 5
    ID |       Sample ID |                           Name | Steps | Observations
--------------------------------------------------------------------------------
     1 |      sample-001 |                     test batch |     3 |            2
     2 |        M315SO23 |                     test batch |     4 |            1

View sample details:

$ sampletracker view sample-001
Sample Details:
  ID:          1
  Sample ID:   sample-001
  Name:        test batch
  Description: my first batch
  Owner ID:    2
  Owner Email: [e-mail]
  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.

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 license.