seven2one-questra 0.5.0

Unified Python Client für Questra Platform - Umbrella Package für Authentication und Data API

Questra Umbrella Package and Docs

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

Verwendung

Installation

pip install seven2one-questra

Dies installiert automatisch:

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

Schnellstart

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/ - seven2one-questra-authentication
• automation/ - seven2one-questra-automation
• 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

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

# 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://[e-mail]/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 unter dependencies hinzu:

[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 und füge Re-Exports hinzu:

# Reporting Client
from questra_reporting import QuestraReporting

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

4. MkDocs-Konfiguration erweitern

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

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

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

5. Dokumentations-Index erstellen

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

# Questra Reporting

::: questra_reporting

6. Synchronisieren und testen

# 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

cd data
git pull
cd ..

2. Neues Release nach PyPI deployen

Im Submodul (z.B. data/):

# Build
uv build

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

Alternativ mit dem Build-Skript:

./buildAndPublish.sh <token> --pypi

3. Dependencies im Umbrella-Package aktualisieren

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

uv version --bump patch

4. Dokumentation bauen

uv run mkdocs build

Was passiert beim Build:

• Hook (mkdocs.yml:57) 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

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

# 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

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

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

3. Dokumentation aktualisieren

uv run mkdocs build

Der Hook aktualisiert automatisch die Version in docs/index.md.

4. Optional: Deploy Docs

Wenn die Docs auf einem Server deployed werden sollen:

# 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 nutzen Standard-PEP 440 Syntax:

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.

# 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 unter [project.optional-dependencies.docs] definiert.

Falsche Version installiert

Diagnose:

uv pip list | grep seven2one

Lösung:

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

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

Installation (für Entwickler)

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