# Questra Umbrella Package and Docs

Dieses Package bündelt alle Questra Python Packages aus dem Mono-Repo und generiert die gemeinsame Dokumentation.

## Verwendung

### Installation

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

Dies installiert automatisch:

- `seven2one-questra-authentication` (OAuth2 Authentifizierung)
- `seven2one-questra-automation` (GraphQL Automation API)
- `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)
)
```

## Mono-Repo Struktur

Dieses Mono-Repo bündelt folgende Questra-Packages:

- [packages/authentication/](../authentication/) - `seven2one-questra-authentication`
- [packages/automation/](../automation/) - `seven2one-questra-automation`
- [packages/data/](../data/) - `seven2one-questra-data`
- [packages/questra/](.) - `seven2one-questra` (Umbrella-Package)

Alle Packages teilen sich zentrale Dev-Dependencies aus dem Root-`pyproject.toml`.

## Workflows

### Workflow A: Sub-Package aktualisieren (z.B. authentication)

Wenn ein Sub-Package (authentication/automation/data) eine neue Version bekommt:

#### 1. Version im Sub-Package erhöhen

```bash
# Beispiel: authentication auf 0.2.3
cd packages/authentication
# Version in pyproject.toml manuell anpassen: version = "0.2.3"
cd ../..
```

#### 2. Dependency im Umbrella-Package aktualisieren

```bash
# packages/questra/pyproject.toml manuell editieren:
# seven2one-questra-authentication>=0.2.3
# seven2one-questra-automation>=0.1.2
# seven2one-questra-data>=0.7.8

# Workspace synchronisieren
uv sync
```

**Wichtig:** Durch `[tool.uv.sources]` mit `{ workspace = true }` wird die **lokale Version** verwendet, auch wenn PyPI-Publish erst später erfolgt!

#### 3. Umbrella-Package Version erhöhen

```bash
# packages/questra/pyproject.toml manuell editieren:
# version = "0.5.2"  # patch bump

uv sync
```

#### 4. Optional: Tests & Linting

```bash
# Sub-Package testen
uv run pytest packages/authentication/tests

# Workspace-weites Linting
uv run ruff check packages/
```

### Workflow B: Neues Sub-Package einbinden

Wenn ein neuer Questra-Client (z.B. `questra-reporting`) hinzugefügt werden soll:

#### 1. Package-Ordner erstellen

```bash
mkdir -p packages/reporting/src/questra_reporting
mkdir -p packages/reporting/tests
```

#### 2. `pyproject.toml` erstellen

Erstelle `packages/reporting/pyproject.toml`:

```toml
[project]
name = "seven2one-questra-reporting"
version = "0.1.0"
description = "Reporting Client for Questra"
authors = [{name = "...", email = "..."}]
requires-python = ">=3.10"
dependencies = [
    "seven2one-questra-authentication>=0.2.3",
]

[tool.uv]
package = true

[tool.uv.sources]
seven2one-questra-authentication = { workspace = true }

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/questra_reporting"]
```

#### 3. Root-Workspace aktualisieren

In `pyproject.toml` (Root):

```toml
[tool.uv.workspace]
members = [
    "packages/authentication",
    "packages/automation",
    "packages/data",
    "packages/questra",
    "packages/reporting",  # NEU
]
```

#### 4. Umbrella-Package Dependency hinzufügen

In `packages/questra/pyproject.toml`:

```toml
[project]
dependencies = [
    "seven2one-questra-authentication>=0.2.3",
    "seven2one-questra-automation>=0.1.2",
    "seven2one-questra-data>=0.7.8",
    "seven2one-questra-reporting>=0.1.0",  # NEU
]

[tool.uv.sources]
seven2one-questra-authentication = { workspace = true }
seven2one-questra-automation = { workspace = true }
seven2one-questra-data = { workspace = true }
seven2one-questra-reporting = { workspace = true }  # NEU
```

#### 5. Package in `__init__.py` re-exportieren

Bearbeite `packages/questra/src/questra/__init__.py`:

```python
# Reporting Client
from questra_reporting import QuestraReporting

__all__ = [
    # ... existing exports
    "QuestraReporting",
]
```

#### 6. Workspace synchronisieren

```bash
uv sync --all-groups
```

#### 7. MkDocs-Konfiguration erweitern (optional)

Falls Dokumentation generiert werden soll, in `mkdocs.yml`:

```yaml
nav:
  - Home: index.md
  - Authentication: authentication/index.md
  - Automation: automation/index.md
  - Reporting: reporting/index.md  # NEU
  - Data: data/index.md

plugins:
  - mkdocstrings:
      handlers:
        python:
          paths:
            - packages/authentication/src
            - packages/automation/src
            - packages/reporting/src  # NEU
            - packages/data/src
```

#### 8. Tests & Linting

```bash
# Tests für neues Package
uv run pytest packages/reporting/tests

# Workspace-weites Linting
uv run ruff check packages/
```

## Dependency-Management

### Workspace-Referenzen

Alle internen Dependencies nutzen `{ workspace = true }`:

```toml
[tool.uv.sources]
seven2one-questra-authentication = { workspace = true }
```

**Vorteile:**

- Lokale Entwicklung ohne PyPI-Publish
- Version-Constraints in `dependencies` gelten für PyPI-Release
- Änderungen sofort im gesamten Workspace verfügbar

### Version Constraints

Version-Ranges nutzen PEP 440 Syntax:

```toml
dependencies = [
    "seven2one-questra-authentication>=0.2.3",  # Mindestversion
    "seven2one-questra-data>=0.7.8,<1.0.0",     # Mit Upper Bound
]
```

## Häufige Probleme

### `uv sync` findet Package nicht

**Ursache:** Package nicht in `[tool.uv.workspace].members` eingetragen.

**Lösung:**

```bash
# Root pyproject.toml prüfen
grep -A5 "tool.uv.workspace" pyproject.toml

# Workspace neu synchronisieren
uv sync
```

### Ruff-Plugin Auto-Format konfligiert mit Edit

**Ursache:** VS Code formatiert beim Speichern → Race Condition mit Edit-Tool.

**Lösung:** Bei Ruff-Fehlern `sed` verwenden:

```bash
sed -i 's/OLD_PATTERN/NEW_PATTERN/g' packages/data/src/file.py
uv run ruff check packages/
```

### Falsche Version installiert

**Diagnose:**

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

**Lösung:**

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

# Cache löschen (falls nötig)
uv cache clean && uv sync
```

## Installation (für Entwickler)

```bash
# Repository klonen
git clone <repo-url>
cd S2O.Questra.PythonPackages

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

# Docs bauen
uv run mkdocs build

# Lokaler Dev-Server
uv run mkdocs serve
```

## Weitere Infos

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