seven2one-questra 0.5.2

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

Questra Umbrella Package and Docs

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

Verwendung

Installation

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

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

# 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

# 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

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

uv sync

4. Optional: Tests & Linting

# 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

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

2. pyproject.toml erstellen

Erstelle packages/reporting/pyproject.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):

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

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

# Reporting Client
from questra_reporting import QuestraReporting

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

6. Workspace synchronisieren

uv sync --all-groups

7. MkDocs-Konfiguration erweitern (optional)

Falls Dokumentation generiert werden soll, in mkdocs.yml:

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

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

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

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:

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

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

Falsche Version installiert

Diagnose:

uv pip list | grep seven2one

Lösung:

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

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

Installation (für Entwickler)

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