Metadata-Version: 2.4
Name: seven2one-questra
Version: 0.4.5
Summary: Unified Python Client für Questra Platform - Umbrella Package für Authentication und Data API
Author-email: Jürgen Talasch <juergen.talasch@seven2one.de>
Requires-Python: >=3.10
Requires-Dist: seven2one-questra-authentication<0.3.0,>=0.1.5
Requires-Dist: seven2one-questra-data>=0.7.6
Description-Content-Type: text/markdown

# Questra Umbrella Package and Docs

Dieses Repository bündelt alle Questra Python Packages als Submodule und generiert die gemeinsame Dokumentation.

## Verwendung

### Installation

```bash
pip install seven2one-questra
```

Dies installiert automatisch:

- `seven2one-questra-authentication` (OAuth2 Authentifizierung)
- `seven2one-questra-data` (GraphQL + REST Data API)

### Schnellstart

```python
from questra import QuestraAuthentication, QuestraData

# Authentication
auth = QuestraAuthentication(
    url="https://auth.example.com",
    username="service_user",
    password="secret"
)

# Data Client (High-Level API)
client = QuestraData(
    graphql_url="https://api.example.com/graphql",
    auth_client=auth
)

# Daten abrufen
items = client.list(
    inventory_name="Sensors",
    namespace="IoT"
)

# TimeSeries-Daten laden
from datetime import datetime
values = client.list_timeseries_values(
    inventory_name="Stromzaehler",
    namespace="Energie",
    timeseries_property="messwerte_Energie",
    from_time=datetime(2024, 1, 1),
    to_time=datetime(2024, 1, 31)
)
```

### Fortgeschrittene Verwendung

Alle Sub-Package-APIs bleiben direkt zugänglich:

```python
# Low-Level Data API
from questra import QuestraDataCore

core_client = QuestraDataCore(graphql_url="...", auth_client=auth)
inventories = core_client.queries.get_inventories()

# Spezifische Models
from questra import (
    Inventory, Namespace, TimeSeriesValue,
    SortOrder, ConflictAction
)

# Direkter Sub-Paket-Zugriff für erweiterte Features
from questra_data.models import InventoryPrivilege
from questra_authentication.authentication import OidcDiscoveryClient
```

### Verfügbare Komponenten

Das Umbrella-Package exportiert:

**Core Clients:**

- `QuestraAuthentication` - OAuth2 Authentifizierung
- `QuestraData` - High-Level Data API (empfohlen)
- `QuestraDataCore` - Low-Level Data API

**Häufig verwendete Models:**

- GraphQL: `Inventory`, `InventoryProperty`, `Namespace`, `Role`, `Unit`, `TimeZone`
- TimeSeries: `TimeSeriesValue`, `Aggregation`, `Quality`, `TimeUnit`, `Interval`
- Input Models: `StringPropertyConfig`, `FilePropertyConfig`, `TimeSeriesPropertyConfig`
- REST: `TimeSeriesData`, `SetTimeSeriesDataInput`, `File`

**Exceptions:**

- `AuthenticationError`, `InvalidCredentialsError`, `TokenExpiredError`

Siehe [src/questra/\_\_init\_\_.py](src/questra/__init__.py) für vollständige Liste.

## Struktur

```text
.
├── authentication/          # git submodule: questra-authentication
├── data/                    # git submodule: questra-data
├── docs/                    # zentrale Dokumentation
├── scripts/
│   └── update_versions.py   # Hook: sync Versionen → Docs & pyproject.toml
├── pyproject.toml          # Umbrella-Package Dependencies
└── mkdocs.yml              # Docs-Konfiguration
```

## Workflows

Alle Packages sind auf **PyPI** verfügbar.

### Workflow A: Submodul-Update (z.B. questra-data)

Wenn ein Submodul (data/authentication) aktualisiert wurde und bereits nach PyPI deployt wurde:

### 1. Lokale Änderungen pullen

```bash
cd data
git pull
cd ..
```

### 2. Neues Release nach PyPI deployen

Im Submodul (z.B. `data/`):

```bash
# Build
uv build

# Upload nach PyPI
uv publish --token <your-token>
```

Alternativ mit dem Build-Skript:

```bash
./buildAndPublish.sh <token> --pypi
```

### 3. Dependencies im Umbrella-Package aktualisieren

```bash
# Im Root-Verzeichnis - Version in pyproject.toml manuell anpassen, dann:
uv sync

# Oder direkt mit uv add:
uv add "seven2one-questra-data>=0.8.0"
uv add "seven2one-questra-authentication>=0.2.2"
```

### 4. Questra Version erhöhen

Version in `pyproject.toml` manuell anpassen oder mit einem Tool:

```bash
uv version --bump patch
```

### 4. Dokumentation bauen

```bash
uv run mkdocs build
```

**Was passiert beim Build:**

- **Hook** ([mkdocs.yml:57](mkdocs.yml#L57)) führt `scripts.update_versions:update_versions` aus
- Liest Versionen aus allen `pyproject.toml`-Dateien (Root + Submodule)
- Aktualisiert Versionsnummern in:
  - `docs/index.md` (Umbrella-Package)
  - `docs/data/index.md` (questra-data)
  - `docs/authentication/index.md` (questra-authentication)

### 5. Optional: Dokumentation lokal ansehen

```bash
uv run mkdocs serve
```

Öffnet Docs unter `http://127.0.0.1:8000`.

### Workflow B: Umbrella-Package Release

Wenn das Umbrella-Package selbst eine neue Version bekommen soll (z.B. nach Dependency-Updates):

#### 1. Version bumpen

```bash
# In pyproject.toml manuell editieren:
# version = "0.4.4"  # patch: 0.4.3 → 0.4.4
# version = "0.5.0"  # minor: 0.4.3 → 0.5.0
# version = "1.0.0"  # major: 0.4.3 → 1.0.0
```

#### 2. Build & Publish

```bash
uv build
uv publish --token <your-token>

# Oder mit Build-Skript:
./buildAndPublish.sh <token> --pypi
```

#### 3. Dokumentation aktualisieren

```bash
uv run mkdocs build
```

Der Hook aktualisiert automatisch die Version in [docs/index.md](docs/index.md).

#### 4. Optional: Deploy Docs

Wenn die Docs auf einem Server deployed werden sollen:

```bash
# Beispiel: rsync, S3, Azure Blob Storage, etc.
rsync -av site/ user@server:/var/www/docs/
```

## Dependency-Management

### PyPI als Quelle

Alle Packages (`seven2one-questra`, `seven2one-questra-authentication`, `seven2one-questra-data`) sind auf PyPI verfügbar und werden automatisch von dort bezogen.

### Version Constraints

Die Version-Ranges in [pyproject.toml](pyproject.toml) nutzen Standard-PEP 440 Syntax:

```toml
dependencies = [
    "seven2one-questra-authentication>=0.1.5,<0.3.0",
    "seven2one-questra-data>=0.7.3",
]
```

- Ermöglicht Patch- und Minor-Updates
- Verhindert Breaking Changes bei Major-Version-Bumps

**Manuelle Anpassung nötig bei:**

- Neuer Major-Version
- Besonderen Dependency-Anforderungen

## Häufige Probleme

### Neue Package-Version wird nicht gefunden

**Ursache:** Cache-Problem oder Package noch nicht auf PyPI.

```bash
# uv Cache löschen
uv cache clean

# Neu synchronisieren
uv sync
```

### Hook-Fehler beim Build

**Ursache:** `toml`-Package fehlt in docs-Dependencies.

**Lösung:** Bereits in [pyproject.toml](pyproject.toml) unter `[project.optional-dependencies.docs]` definiert.

### Falsche Version installiert

**Diagnose:**

```bash
uv pip list | grep seven2one
```

**Lösung:**

```bash
# Version in pyproject.toml anpassen, dann:
uv sync

# oder direkt:
uv add "seven2one-questra-data>=0.8.0"
```

## Installation (für Entwickler)

```bash
# Repository klonen mit Submodulen
git clone --recursive <repo-url>

# Dependencies installieren (inkl. docs)
uv sync --all-groups

# Docs bauen
uv run mkdocs build
```

## Erste Schritte

Nach erfolgreicher Installation:

1. **Lokaler Dev-Server:** `uv run mkdocs serve`
2. **Static Build:** `uv run mkdocs build` → Output in `site/`
3. **Tests laufen:** `cd data && uv run pytest`

## Weitere Infos

- **MkDocs Material:** <https://squidfunk.github.io/mkdocs-material/>
- **mkdocstrings:** <https://mkdocstrings.github.io/python/>
- **uv Documentation:** <https://docs.astral.sh/uv/>
