# 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)
)
```

## Git Submodules

Dieses Repository bündelt folgende Questra-Packages als Git Submodules:

- [authentication/](authentication/) - `seven2one-questra-authentication`
- [automation/](automation/) - `seven2one-questra-automation`
- [data/](data/) - `seven2one-questra-data`

### Neues Client-Submodul einbinden

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

#### 1. Submodul hinzufügen

```bash
git submodule add <repository-url> <target-directory>
# Beispiel:
git submodule add https://github.com/seven2one/questra-reporting.git reporting
```

##### Sonderfall: Nur Unterordner aus Repository auschecken

Wenn der Python-Client in einem Unterordner des Repositories liegt (z.B. `src/python-client`):

```bash
# Submodule mit Branch hinzufügen
git submodule add --branch <branch-name> <repository-url> <target-directory>

cd <target-directory>

# Sparse-checkout aktivieren (nur Unterordner auschecken)
git sparse-checkout init --cone
git sparse-checkout set <subdirectory-path>

# Branch auschecken
git checkout <branch-name>

cd ..

# Beispiel: questra-automation aus Azure DevOps
git submodule add --branch feat/python-package \
  https://seven2one@dev.azure.com/seven2one/Seven2one.Questra/_git/S2O.Questra.Automation \
  automation

cd automation
git sparse-checkout init --cone
git sparse-checkout set src/python-client
git checkout feat/python-package
cd ..
```

**Hinweis:** Bei sparse-checkout ist nur `src/python-client/` sichtbar, nicht das gesamte Repository.

#### 2. Dependency in pyproject.toml eintragen

Füge das neue Package in [pyproject.toml](pyproject.toml) unter `dependencies` hinzu:

```toml
[project]
dependencies = [
    "seven2one-questra-authentication>=0.1.5,<0.3.0",
    "seven2one-questra-data>=0.7.3",
    "seven2one-questra-reporting>=0.1.0",  # NEU
]
```

#### 3. Package in **init**.py re-exportieren

Bearbeite [src/questra/**init**.py](src/questra/__init__.py) und füge Re-Exports hinzu:

```python
# Reporting Client
from questra_reporting import QuestraReporting

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

#### 4. MkDocs-Konfiguration erweitern

Füge in [mkdocs.yml](mkdocs.yml) unter `nav` und `plugins.mkdocstrings.handlers.python.paths` das neue Submodul hinzu:

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

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

##### Bei Submodule mit Unterordner-Struktur

Beispiel: `automation/src/python-client/src`

```yaml
paths:
  - authentication/src
  - automation/src/python-client/src  # Angepasster Pfad
  - data/src
```

#### 5. Dokumentations-Index erstellen

Erstelle `docs/reporting/index.md` mit folgendem Inhalt:

```markdown
# Questra Reporting

::: questra_reporting
```

#### 6. Synchronisieren und testen

```bash
# Dependencies installieren
uv sync

# Dokumentation bauen
uv run mkdocs build

# Lokal testen
uv run mkdocs serve
```

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