seven2one-questra 0.4.4

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

Fortgeschrittene Verwendung

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

# 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 für vollständige Liste.

Struktur

.
├── 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

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/