skyview.astronomiemuseum.de/public/py/README_KI_CODER_PYTHON.md

Python-Nutzung in diesem Projekt

Diese Anleitung ist fuer KI-Coder und Entwickler gedacht, die in diesem Projekt Python-Skripte aus PHP heraus verwenden oder erweitern wollen.

Ziel

Python soll hier nicht als dauerhaft laufender Dienst verwendet werden, sondern als einzelnes Skript, das von einer PHP-Seite per exec(...) gestartet wird.

Bevorzugtes Muster in diesem Projekt:

• eine zentrale Python-Datei als Einstiegspunkt: public/py/api.py
• darin mehrere Aktionen, z. B. sun_moon_rise_set
• PHP uebergibt zuerst den Aktionsnamen und danach die Argumente

Typischer Ablauf:

1. Eine PHP-Seite sammelt Eingabedaten.
2. PHP ruft public/py/api.py auf.
3. Das Python-Skript berechnet das Ergebnis.
4. Python gibt das Ergebnis als JSON auf stdout aus.
5. PHP liest dieses JSON ein und rendert die Seite.

Wichtige Projektregeln

• Der zentrale Einstiegspunkt fuer Webaufrufe liegt in public/py/api.py.
• Wenn moeglich, soll Python JSON ausgeben, nicht frei formatierten Text.
• Fehler sollen ebenfalls als JSON ausgegeben werden, damit PHP sie sauber anzeigen kann.
• Die PHP-Seite ist fuer Eingabevalidierung, Aufruf und Darstellung zustaendig.
• Das Python-Skript ist fuer die Berechnung zustaendig.
• Neue Funktionen sollen bevorzugt als neue Aktion in api.py ergaenzt werden, nicht als neue Einzeldatei.

Lokale Astronomy Engine

In diesem Projekt liegt die Python-Version der Astronomy Engine bereits lokal als:

• public/py/astronomy.py

Deshalb koennen Python-Skripte aus demselben Ordner sie direkt importieren, zum Beispiel:

import os
import sys

SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
if SCRIPT_DIR not in sys.path:
    sys.path.insert(0, SCRIPT_DIR)

import astronomy

Das ist wichtig, damit der Import auch auf Hosting-Systemen funktioniert, auf denen kein global installiertes Paket vorhanden ist.

PHP-Aufruf

Die Python-Skripte werden in diesem Projekt per exec(...) aus PHP gestartet.

Beispielmuster:

$command = '/usr/bin/python ' . escapeshellarg($scriptPath) . ' ' . implode(' ', $args) . ' 2>&1';
$output = [];
$resultCode = 0;
exec($command, $output, $resultCode);

Mit zentraler API-Datei sieht der Aufruf typischerweise so aus:

$args = [
    escapeshellarg($scriptPath),
    escapeshellarg('sun_moon_rise_set'),
    escapeshellarg($latitude),
    escapeshellarg($longitude),
    escapeshellarg($elevation),
    escapeshellarg($date),
    escapeshellarg($timezone),
];

Wichtig:

• Immer escapeshellarg(...) fuer alle dynamischen Argumente verwenden.
• 2>&1 anhängen, damit Fehlermeldungen mitgelesen werden.
• Rueckgabecode pruefen.
• Ausgabe mit json_decode(...) verarbeiten.

Hosting-Hinweis fuer All-Inkl

Nach der All-Inkl-Anleitung werden Shell-Skripte bzw. Python-Skripte ueber PHP typischerweise so gestartet:

exec("/usr/bin/python Pfad/zum/script 2>&1", $out, $result);

Quelle:

• https://all-inkl.com/wichtig/anleitungen/skripte/sonstiges/per-skript/shellskripte-ausfuehren_304.html

Wichtige Punkte aus der Anleitung:

• Python kann per /usr/bin/python aufgerufen werden.
• Nicht alle Shell-Befehle sind auf dem Hosting erlaubt.
• Groessere Skripte koennen an Serverrestriktionen scheitern.
• Falls zusaetzliche Python-Module gebraucht werden, koennen sie per SSH in ein eigenes Zielverzeichnis installiert werden.
• Falls ein eigenes Modulverzeichnis genutzt wird, muss dieses im Python-Skript per sys.path.append(...) eingebunden werden.

Beispiel aus der All-Inkl-Logik:

import sys
sys.path.append("/www/htdocs/ACCOUNTNAME/python-module")

Empfohlenes JSON-Format

Python sollte moeglichst ein einheitliches Antwortformat liefern.

Erfolg:

{
  "ok": true,
  "data": {
    "example": 123
  }
}

Fehler:

{
  "ok": false,
  "error": "Beschreibung des Fehlers"
}

So kann PHP sehr einfach unterscheiden:

$decoded = json_decode($joinedOutput, true);
if (!is_array($decoded) || !($decoded['ok'] ?? false)) {
    // Fehler behandeln
}

Beispiel in diesem Projekt

Bereits umgesetzt ist:

• public/index_py.php
• public/py/api.py

Dort wird gezeigt:

• wie Standortdaten aus PHP uebergeben werden,
• wie Python mit astronomy.py rechnet,
• wie JSON zurueckgegeben wird,
• und wie Fehler im PHP angezeigt werden.

Best Practices fuer KI-Coder

• Vor neuen Python-Dateien zuerst pruefen, ob die neue Funktion als weitere Aktion in api.py eingebaut werden kann.
• CLI-Argumente immer strikt validieren.
• Niemals unescaped Benutzereingaben in Shell-Kommandos einsetzen.
• Python-Ausgabe kompakt halten, idealerweise genau eine JSON-Zeile.
• Bei Fehlern maschinenlesbar bleiben.
• Zeitangaben moeglichst mit Zeitzone oder als ISO-Format ausgeben.
• Rechenlogik in Python halten, HTML-Ausgabe in PHP.
• Bei Hosting-Fragen zuerst mit /usr/bin/python planen, weil das fuer All-Inkl dokumentiert ist.

Checkliste vor dem Einbau

• Wird moeglichst public/py/api.py verwendet?
• Sind alle CLI-Argumente in PHP mit escapeshellarg(...) abgesichert?
• Gibt Python gueltiges JSON aus?
• Werden Fehlerfaelle ebenfalls als JSON behandelt?
• Ist der Import lokaler Module ueber sys.path abgesichert?
• Ist klar, welche Zeitzone verwendet wird?
• Ist das Skript klein genug fuer Shared-Hosting?

Kurzfassung

In diesem Projekt gilt:

• PHP startet Python per exec(...).
• Zentraler Einstiegspunkt ist public/py/api.py.
• Die gewuenschte Funktion wird ueber einen Aktionsnamen ausgewaehlt.
• Ergebnisse kommen als JSON zurueck.
• Lokale Bibliotheken wie astronomy.py werden direkt aus dem py-Ordner importiert.
• Auf All-Inkl ist /usr/bin/python der Standardweg fuer den Aufruf.