hse-sampletracker-client 0.1.1__tar.gz

hse_sampletracker_client-0.1.1/.gitea/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ['v*']
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install pytest mypy build hatch
+
+      - name: Run type checking
+        run: |
+          mypy src/sampletracker --ignore-missing-imports
+
+      - name: Run tests
+        run: |
+          pytest tests/ -v
+
+      - name: Build package
+        run: |
+          hatch build
+
+      - name: Check package
+        run: |
+          pip install twine
+          twine check dist/*
+
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Build package
+        run: |
+          hatch build
+
+      - name: Publish to PyPI
+        env:
+          HATCH_INDEX_USER: __token__
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_APIKEY }}
+        run: |
+          hatch publish

hse_sampletracker_client-0.1.1/.gitignore

@@ -0,0 +1,47 @@
+# Local environment variables
+.env
+.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db

hse_sampletracker_client-0.1.1/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-09
+
+### Added
+
+- Synchronous API client (`SampleTrackerClient`) for interacting with SampleTracker API
+- Support for listing samples with pagination (`list_samples` method)
+- Support for retrieving detailed sample information with history (`load_sample` method)
+- Command-line interface (`sampletracker`) for listing and viewing samples
+- Dataclass-based models with full type hints:
+  - `SampleListItem` for list responses
+  - `Sample` for detailed sample views with history
+  - `StepEvent` and `ObservationEvent` for timeline events
+  - `Parameter` for step parameters
+  - `SampleStats` for aggregated counts
+- Comprehensive exception hierarchy for error handling:
+  - `SampleTrackerError` (base)
+  - `SampleTrackerAuthError` (401)
+  - `SampleTrackerNotFoundError` (404)
+  - `SampleTrackerValidationError` (422)
+  - `SampleTrackerRateLimitError` (429)
+  - `SampleTrackerAPIError` (generic)
+- Environment variable configuration support (`SAMPLETRACKER_API_KEY`, `SAMPLETRACKER_BASE_URL`)
+- Automatic `.env` file loading for CLI
+- Bearer token authentication
+- Support for Python 3.8 through 3.14 and PyPy
+
+[unreleased]: https://github.com/Alexander Schramm/sampletracker/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Alexander Schramm/sampletracker/releases/tag/v0.1.0

hse_sampletracker_client-0.1.1/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Alexander Schramm <alexander.schramm96@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

hse_sampletracker_client-0.1.1/PKG-INFO

@@ -0,0 +1,238 @@
+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

hse_sampletracker_client-0.1.1/README.md

@@ -0,0 +1,208 @@
+# 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

hse_sampletracker_client-0.1.1/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hse-sampletracker-client"
+dynamic = ["version"]
+description = 'A Pythonic client library for the SampleTracker SaaS API'
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+keywords = ["sampletracker", "api", "client", "hse", "laboratory", "samples"]
+authors = [
+    {name = "Alexander Schramm", email = "info@expectiq.com"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.scripts]
+sampletracker = "sampletracker.run:main"
+
+[project.urls]
+Documentation = "https://github.com/Alexander Schramm/sampletracker#readme"
+Issues = "https://github.com/Alexander Schramm/sampletracker/issues"
+Source = "https://github.com/Alexander Schramm/sampletracker"
+
+[tool.hatch.version]
+path = "src/sampletracker/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sampletracker"]
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/sampletracker tests}"
+
+[tool.coverage.run]
+source_pkgs = ["sampletracker", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/sampletracker/__about__.py",
+]
+
+[tool.coverage.paths]
+sampletracker = ["src/sampletracker", "*/sampletracker/src/sampletracker"]
+tests = ["tests", "*/sampletracker/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

hse_sampletracker_client-0.1.1/src/sampletracker/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Alexander Schramm
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.1.1"