site — Einhängepunkt für installationsspezifische Konfiguration

Quellcode: Lib/site.py

Dieses Modul wird während der Initialisierung selbsttätig importiert. Der selbsttätige Import lässt sich mit der Option -S des Interpreters unterdrücken.

Dieses Modul zu importieren hängt normalerweise installationsspezifische Pfade an den Suchpfad für Module an und fügt aufrufbare Objekte einschließlich help() dem integrierten Namensraum hinzu. Die Startoption -S von Python verhindert das. Das Modul lässt sich dann ohne selbsttätige Änderungen am Suchpfad und ohne Ergänzungen der integrierten Namen bedenkenlos importieren. Um die üblichen installationsspezifischen Ergänzungen ausdrücklich auszulösen, rufe die Funktion main() auf.

Geändert in Version 3.3: Früher löste der Import des Moduls die Pfadanpassung selbst mit -S aus.

Zunächst werden bis zu vier Verzeichnisse aus einem Kopf- und einem Endteil zusammengesetzt. Als Kopfteil dienen sys.prefix und sys.exec_prefix. Leere Köpfe werden übersprungen. Als Endteil dienen die leere Zeichenkette und dann lib/site-packages (unter Windows) beziehungsweise lib/pythonX.Y[t]/site-packages (unter Unix und macOS). Die optionale Endung „t“ steht für den Build mit freien Threads und wird angehängt, wenn "t" in der Konstante sys.abiflags vorkommt. Für jede der verschiedenen Kopf-Ende-Kombinationen wird geprüft, ob sie auf ein vorhandenes Verzeichnis verweist. Ist das der Fall, wird es sys.path hinzugefügt und der neu hinzugefügte Pfad zusätzlich auf Konfigurationsdateien untersucht.

Geändert in Version 3.5: Die Unterstützung für das Verzeichnis „site-python“ wurde entfernt.

Geändert in Version 3.13: Unter Unix sind Python-Installationen mit freien Threads an der Endung „t“ im versionsspezifischen Verzeichnisnamen zu erkennen, etwa lib/python3.13t/.

Geändert in Version 3.14: site ist nicht mehr dafür zuständig, sys.prefix und sys.exec_prefix bei Virtual Environments zu aktualisieren. Das geschieht nun während der Pfadinitialisierung. Damit hängen sys.prefix und sys.exec_prefix bei Virtual Environments nicht mehr von der Initialisierung von site ab und werden daher von -S nicht beeinflusst.

Läuft Python in einer virtuellen Umgebung, wird die Datei pyvenv.cfg in sys.prefix auf installationsspezifische Konfigurationen geprüft. Ist der Schlüssel include-system-site-packages vorhanden und auf true gesetzt (Groß- und Kleinschreibung spielt keine Rolle), werden die Präfixe der Systemebene nach site-packages durchsucht, andernfalls nicht. Werden die Präfixe der Systemebene nicht durchsucht, werden damit auch die Präfixe des Benutzers nicht nach site-packages durchsucht.

Das Modul site kennt zwei Konfigurationsdateien für den Start: name.pth für Pfadkonfigurationen und name.start für Code, der vor der ersten Zeile ausgeführt wird. Beide Dateien können in einem der vier oben genannten Verzeichnisse liegen. Innerhalb jedes Verzeichnisses werden diese Dateien alphabetisch nach Dateinamen sortiert und dann in dieser Reihenfolge eingelesen.

Pfaderweiterungen (.pth-Dateien)

name.pth enthält zusätzliche Einträge (einen je Zeile), die an sys.path angehängt werden. Einträge, die auf nicht vorhandene Verzeichnisse verweisen, werden nie zu sys.path hinzugefügt. Es wird nicht geprüft, ob ein Eintrag auf ein Verzeichnis und nicht auf eine Datei verweist. Kein Eintrag wird mehr als einmal zu sys.path hinzugefügt. Leerzeilen und Zeilen, die mit # beginnen, werden übersprungen.

Aus Gründen der Rückwärtskompatibilität werden Zeilen, die mit import beginnen (gefolgt von einem Leerzeichen oder Tabulator), mit exec() ausgeführt.

Geändert in Version 3.13: Die .pth-Dateien werden jetzt zuerst mit UTF-8 dekodiert und, falls das fehlschlägt, mit der Locale-Kodierung.

Geändert in Version 3.15: Zeilen in .pth-Dateien, die mit import beginnen, sind veraltet. Während der Übergangszeit werden solche Zeilen weiterhin ausgeführt (außer im unten genannten Fall), eine Diagnosemeldung erscheint aber nur, wenn das Flag -v angegeben ist.

import-Zeilen in name.pth werden stillschweigend übergangen, wenn eine passende Datei name.start vorhanden ist.

Fehler in einzelnen Zeilen brechen die Verarbeitung des restlichen Dateiinhalts nicht mehr ab. Jeder Fehler wird gemeldet und die übrigen Zeilen werden weiter verarbeitet.

Veraltet seit Version 3.15, wird in Version 3.20 entfernt: name.pth-Dateien in einer anderen Kodierung als utf-8-sig zu dekodieren ist in Python 3.15 veraltet. Die Unterstützung für das Dekodieren anhand der Locale-Kodierung wird in Python 3.20 entfernt.

import-Zeilen in name.pth-Dateien sind veraltet und werden in Python 3.18 und 3.19 stillschweigend übergangen. In Python 3.20 wird für import-Zeilen in name.pth-Dateien eine Warnung ausgegeben.

Einsprungpunkte beim Start (.start-Dateien)

Added in version 3.15.

Eine Datei mit Einsprungpunkten für den Start ist eine Datei, deren Name die Form name.start hat und die in einem der oben beschriebenen site-packages-Verzeichnisse liegt. Jede Datei gibt Einsprungpunkte an, die beim Start des Interpreters aufgerufen werden, in der Syntax pkg.mod:callable, die pkgutil.resolve_name() versteht.

Jede nicht leere Zeile, die nicht mit # beginnt, muss einen Verweis auf einen Einsprungpunkt in der Form pkg.mod:callable enthalten. Der Doppelpunkt und der aufrufbare Teil sind zwingend. Jedes aufrufbare Objekt wird ohne Argumente aufgerufen, ein etwaiger Rückgabewert wird verworfen.

.start-Dateien werden verarbeitet, nachdem alle Pfaderweiterungen aus .pth-Dateien auf sys.path angewendet wurden. So stehen die Pfade bereit, bevor Code beim Start läuft.

Anders als bei den sys.path-Erweiterungen aus .pth-Dateien werden mehrfach vorkommende Einsprungpunkte nicht zusammengefasst — erscheint ein Einsprungpunkt mehrfach, wird er mehrfach aufgerufen.

Tritt beim Auflösen oder Aufrufen eines Einsprungpunkts eine Ausnahme auf, wird ein Traceback nach sys.stderr ausgegeben und die Verarbeitung mit den übrigen Einsprungpunkten fortgesetzt.

.start-Dateien müssen in UTF-8 kodiert sein.

PEP 829 legte die ursprüngliche Spezifikation dieser Merkmale fest.

Bemerkung

Liegt eine Datei name.start neben einer Datei name.pth mit demselben Basisnamen, werden alle import-Zeilen in der .pth-Datei zugunsten der Einsprungpunkte in der .start-Datei übergangen.

Bemerkung

Ausführbare Zeilen (import-Zeilen in name.pth-Dateien und Einsprungpunkte in name.start-Dateien) werden beim Start von Python immer ausgeführt, unabhängig davon, ob ein bestimmtes Modul tatsächlich verwendet wird – es sei denn, -S schaltet das Modul site.py ganz ab.

Bemerkung

name.start-Dateien rufen pkgutil.resolve_name() mit strict=True auf, was die vollständige Form pkg.mod:callable voraussetzt.

Beispiele für Startdateien

Nehmen wir zum Beispiel an, sys.prefix und sys.exec_prefix seien auf /usr/local gesetzt. Die Python-X.Y-Bibliothek ist dann in /usr/local/lib/pythonX.Y installiert. Nehmen wir weiter an, dort gebe es ein Unterverzeichnis /usr/local/lib/pythonX.Y/site-packages mit drei Unterverzeichnissen foo, bar und spam sowie zwei Pfadkonfigurationsdateien foo.pth und bar.pth. foo.pth enthalte Folgendes:

# foo package configuration

foo
bar
bletch

und bar.pth enthalte:

# bar package configuration

bar

Dann werden die folgenden versionsspezifischen Verzeichnisse in dieser Reihenfolge zu sys.path hinzugefügt:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

Beachte, dass bletch wegfällt, weil es nicht vorhanden ist; dass das Verzeichnis bar vor dem Verzeichnis foo steht, weil bar.pth alphabetisch vor foo.pth kommt; und dass spam wegfällt, weil es in keiner der beiden Pfadkonfigurationsdateien genannt wird.

Nehmen wir an, es gebe außerdem eine Datei foo.start mit folgendem Inhalt:

# foo package startup code

foo.submod:initialize

Nachdem sys.path wie oben erweitert wurde und bevor Python die Kontrolle an den Code des Benutzers übergibt, wird nun das Modul foo.submod importiert und die Funktion initialize() aus diesem Modul aufgerufen.

Von import-Zeilen in .pth-Dateien auf .start-Dateien umstellen

Liefert dein Paket derzeit eine Datei name.pth mit, kannst du alle Zeilen zur Erweiterung von sys.path unverändert lassen. Nur die import-Zeilen müssen umgestellt werden.

Erzeuge zum Umstellen ein aufrufbares Objekt ohne Argumente in einem importierbaren Modul deines Pakets. Verweise darauf als Einsprungpunkt pkg.mod:callable in einer passenden Datei name.start. Verschiebe alles, was in deiner import-Zeile nach dem ersten Semikolon steht, in die Funktion callable().

Muss dein Paket sowohl mit älteren Python-Versionen ohne PEP 829-Unterstützung als auch mit neueren mit ihr zurechtkommen, ändere die import-Zeilen in name.pth in folgende Form:

import pkg.mod; pkg.mod.callable()

Ältere Python-Versionen führen diese import-Zeilen aus, neuere übergehen sie zugunsten der Datei name.start. Entferne danach alle import-Zeilen aus deinen .pth-Dateien.

sitecustomize

Nach diesen Pfadanpassungen wird versucht, ein Modul namens sitecustomize zu importieren, das beliebige installationsspezifische Anpassungen vornehmen kann. Üblicherweise legt es ein Systemverwalter im site-packages-Verzeichnis an. Schlägt dieser Import mit einem ImportError oder einer Ausnahme einer Unterklasse davon fehl und ist das Attribut name der Ausnahme gleich 'sitecustomize', wird das stillschweigend übergangen. Wird Python ohne verfügbare Ausgabeströme gestartet, etwa über pythonw.exe unter Windows (das voreingestellt IDLE startet), werden Ausgabeversuche von sitecustomize übergangen. Jede andere Ausnahme führt zu einem stillen und möglicherweise schwer erklärlichen Scheitern des Prozesses.

usercustomize

Danach wird versucht, ein Modul namens usercustomize zu importieren, das beliebige benutzerspezifische Anpassungen vornehmen kann, sofern ENABLE_USER_SITE wahr ist. Diese Datei ist dafür gedacht, im site-packages-Verzeichnis des Benutzers angelegt zu werden (siehe unten), das Teil von sys.path ist, sofern es nicht mit -s abgeschaltet wurde. Schlägt dieser Import mit einem ImportError oder einer Ausnahme einer Unterklasse davon fehl und ist das Attribut name der Ausnahme gleich 'usercustomize', wird das stillschweigend übergangen.

Beachte, dass sys.prefix und sys.exec_prefix auf manchen Nicht-Unix-Systemen leer sind und die Pfadanpassungen dann übersprungen werden. Der Import von sitecustomize und usercustomize wird dennoch versucht.

Readline-Konfiguration

Auf Systemen, die readline unterstützen, importiert und konfiguriert dieses Modul auch das Modul rlcompleter, sofern Python im interaktiven Modus und ohne die Option -S gestartet wird. Voreingestellt werden die Vervollständigung per Tabulatortaste eingeschaltet und ~/.python_history als Datei für den Verlauf verwendet. Zum Abschalten lösche (oder überschreibe) das Attribut sys.__interactivehook__ in deinem Modul sitecustomize oder usercustomize oder in deiner Datei PYTHONSTARTUP.

Geändert in Version 3.4: rlcompleter und der Verlauf werden jetzt selbsttätig aktiviert.

Inhalt des Moduls

site.PREFIXES

Eine Liste von Präfixen für site-packages-Verzeichnisse.

site.ENABLE_USER_SITE

Flag, das den Zustand des site-packages-Verzeichnisses des Benutzers angibt. True bedeutet, dass es eingeschaltet und zu sys.path hinzugefügt wurde. False bedeutet, dass es auf Wunsch des Benutzers abgeschaltet wurde (mit -s oder PYTHONNOUSERSITE). None bedeutet, dass es aus Sicherheitsgründen abgeschaltet wurde (Benutzer- oder Gruppenkennung stimmt nicht mit der effektiven Kennung überein) oder durch einen Systemverwalter.

site.USER_SITE

Pfad zum site-packages-Verzeichnis des Benutzers für das laufende Python. Kann None sein, wenn getusersitepackages() noch nicht aufgerufen wurde. Der voreingestellte Wert ist ~/.local/lib/pythonX.Y[t]/site-packages für UNIX und macOS-Builds ohne Framework, ~/Library/Python/X.Y/lib/python/site-packages für macOS-Framework-Builds und %APPDATA%\Python\PythonXY\site-packages unter Windows. Das optionale „t“ steht für den Build mit freien Threads. Dieses Verzeichnis ist ein Site-Verzeichnis, das heißt, darin liegende .pth-Dateien werden verarbeitet.

site.USER_BASE

Pfad zum Basisverzeichnis für die site-packages des Benutzers. Kann None sein, wenn getuserbase() noch nicht aufgerufen wurde. Der voreingestellte Wert ist ~/.local für UNIX und macOS-Builds ohne Framework, ~/Library/Python/X.Y für macOS-Framework-Builds und %APPDATA%\Python unter Windows. Aus diesem Wert werden die Installationsverzeichnisse für Skripte, Datendateien, Python-Module und so weiter für das Installationsschema des Benutzers berechnet. Siehe auch PYTHONUSERBASE.

site.main()

Fügt alle üblichen installationsspezifischen Verzeichnisse dem Suchpfad für Module hinzu. Diese Funktion wird selbsttätig aufgerufen, wenn dieses Modul importiert wird, es sei denn, der Python-Interpreter wurde mit dem Flag -S gestartet.

Geändert in Version 3.3: Diese Funktion wurde früher bedingungslos aufgerufen.

site.makepath(*paths)

Verbindet paths mit os.path.join(), versucht das Ergebnis mit os.path.abspath() absolut zu machen und gibt ein Zweiertupel aus dem absoluten Pfad und seiner von os.path.normcase() erzeugten Form mit angeglichener Groß- und Kleinschreibung zurück. Löst os.path.abspath() einen OSError aus, wird der verbundene Pfad unverändert für das Angleichen der Schreibweise verwendet.

Das zweite Element des zurückgegebenen Tupels ist die Form, die im gesamten Modul site zum Vergleichen von Pfaden auf Dateisystemen ohne Beachtung der Groß- und Kleinschreibung dient. Sie füllt die Mengen known_paths, die in verschiedenen APIs dieses Moduls doppelte Einträge in sys.path verhindern.

class site.StartupState(known_paths=None)

Instanzen dieser Klasse sammeln Konfigurationsdaten für den Start des Interpreters aus einem oder mehreren Site-Verzeichnissen. Sie sind die bevorzugte Schnittstelle, um die Verarbeitung von .pth- und .start-Dateien über mehrere Site-Verzeichnisse hinweg zu bündeln, sodass jede Erweiterung von sys.path sichtbar ist, bevor Code beim Start läuft.

Das optionale Argument known_paths ist eine Menge von Pfaden mit angeglichener Groß- und Kleinschreibung (wie sie makepath() erzeugt), die doppelte Einträge in sys.path verhindert. Bei None (der Voreinstellung) wird die Menge aus dem aktuellen sys.path gebildet. main() verwendet implizit eine Instanz dieser Klasse.

Typische Verwendung:

state = site.StartupState()
for sitedir in site_dirs:
    state.addsitedir(sitedir)
state.process()

Added in version 3.15.

addsitedir(sitedir)

Liest die .pth- und .start-Dateien in sitedir und vermerkt deren Erweiterungen von sys.path, die veralteten import-Zeilen aus .pth sowie die Einsprungpunkte aus .start in diesem Zustand. Die vermerkten Daten werden erst angewendet, wenn process() aufgerufen wird.

addusersitepackages()

Fügt das benutzereigene site-packages-Verzeichnis hinzu, sofern es eingeschaltet und vorhanden ist. Die Startdaten des Verzeichnisses werden für die spätere Verarbeitung durch process() gesammelt.

addsitepackages(prefixes=None)

Fügt globale site-packages-Verzeichnisse hinzu, berechnet aus prefixes oder, wenn prefixes None ist, aus dem globalen PREFIXES. Die Startdaten jedes Verzeichnisses werden für die spätere Verarbeitung durch process() gesammelt.

process()

Wendet den gesammelten Zustand an: Zuerst kommen die Pfaderweiterungen zu sys.path hinzu, dann werden die Einsprungpunkte der .start-Dateien und die import-Zeilen der .pth-Dateien (veraltet) ausgeführt.

Diese Methode ist nicht idempotent und darf an derselben Instanz nicht mehrfach aufgerufen werden. Sonst wird der gesammelte Zustand mehrfach angewendet und Einsprungpunkte und import-Zeilen laufen erneut.

site.addsitedir(sitedir, known_paths=None)

Fügt ein Verzeichnis zu sys.path hinzu und liest die .pth- und .start-Dateien in diesem Verzeichnis ein. Üblicherweise in sitecustomize oder usercustomize verwendet (siehe oben).

Das Argument known_paths ist eine optionale Menge von Pfaden mit angeglichener Groß- und Kleinschreibung, die doppelte Einträge in sys.path verhindert. Bei None (der Voreinstellung) wird die Menge aus dem aktuellen sys.path gebildet.

Für die gebündelte Verarbeitung über mehrere Site-Verzeichnisse hinweg baue ausdrücklich einen StartupState auf und rufe daran StartupState.addsitedir() auf. Damit wird die Verarbeitung von .pth und .start auf einen einzigen StartupState.process()-Aufruf verschoben, sodass jede Erweiterung von sys.path sichtbar ist, bevor Code beim Start läuft.

Geändert in Version 3.15: Verarbeitet auch .start-Dateien. Siehe Einsprungpunkte beim Start (.start-Dateien).

site.getsitepackages(prefixes=None)

Gibt eine Liste aller globalen site-packages-Verzeichnisse zurück.

Für jedes in prefixes angegebene Verzeichnis (oder PREFIXES, wenn prefixes None ist) berechnet diese Funktion abhängig von der Systemumgebung das zugehörige site-packages-Unterverzeichnis und gibt eine Liste vollständiger Pfade zurück, die nicht auf ihr Vorhandensein geprüft werden.

Added in version 3.2.

Geändert in Version 3.3: Der optionale Parameter prefixes kam hinzu.

site.getuserbase()

Gibt den Pfad des Basisverzeichnisses des Benutzers, USER_BASE, zurück. Ist es noch nicht initialisiert, setzt diese Funktion es auch, unter Beachtung von PYTHONUSERBASE.

Added in version 3.2.

site.getusersitepackages()

Gibt den Pfad des benutzerspezifischen site-packages-Verzeichnisses, USER_SITE, zurück. Ist es noch nicht initialisiert, setzt diese Funktion es auch, unter Beachtung von USER_BASE. Um festzustellen, ob die benutzerspezifischen site-packages zu sys.path hinzugefügt wurden, ist ENABLE_USER_SITE zu verwenden.

Added in version 3.2.

Befehlszeilenschnittstelle

Das Modul site bietet auch eine Möglichkeit, die Verzeichnisse des Benutzers über die Befehlszeile zu erfahren:

$ python -m site --user-site
/home/user/.local/lib/python3.11/site-packages

Ohne Argumente aufgerufen, gibt es den Inhalt von sys.path auf der Standardausgabe aus, gefolgt vom Wert von USER_BASE und der Angabe, ob das Verzeichnis vorhanden ist, dann dasselbe für USER_SITE und schließlich den Wert von ENABLE_USER_SITE.

--user-base

Gibt den Pfad zum Basisverzeichnis des Benutzers aus.

--user-site

Gibt den Pfad zum site-packages-Verzeichnis des Benutzers aus.

Sind beide Optionen angegeben, werden Basisverzeichnis und site-packages-Verzeichnis des Benutzers ausgegeben (immer in dieser Reihenfolge), getrennt durch os.pathsep.

Ist eine Option angegeben, endet das Skript mit einem dieser Werte: 0, wenn das site-packages-Verzeichnis des Benutzers eingeschaltet ist, 1, wenn es vom Benutzer abgeschaltet wurde, 2, wenn es aus Sicherheitsgründen oder durch einen Systemverwalter abgeschaltet ist, und einen Wert größer als 2 bei einem Fehler.

Siehe auch