site — Modul für standortspezifische Konfiguration

Quellcode: Lib/site.py

Dieses Modul wird bei der Initialisierung automatisch importiert. Der automatische Import kann mit der -S Option des Interpreters unterdrückt werden.

Der normale Import dieses Moduls fügt standortspezifische Pfade zum Modulsuchpfad hinzu und fügt aufrufbare Funktionen, einschließlich help() zum Namespace der integrierten Funktionen hinzu. Die Python-Startoption -S blockiert dies jedoch, und dieses Modul kann sicher importiert werden, ohne automatische Änderungen am Modulsuchpfad oder Hinzufügungen zu den integrierten Funktionen vorzunehmen. Um die üblichen standortspezifischen Ergänzungen explizit auszulösen, rufen Sie die Funktion main() auf.

Geändert in Version 3.3: Der Import des Moduls löste früher auch dann Pfadmanipulationen aus, wenn -S verwendet wurde.

Es beginnt damit, bis zu vier Verzeichnisse aus einem Kopf- und einem Schwanzteil zu konstruieren. Für den Kopfteil werden sys.prefix und sys.exec_prefix verwendet; leere Köpfe werden übersprungen. Für den Schwanzteil wird der leere String und dann lib/site-packages (unter Windows) oder lib/pythonX.Y[t]/site-packages (unter Unix und macOS) verwendet. (Das optionale Suffix "t" kennzeichnet die Free-Threading-Builds und wird angehängt, wenn "t" in der Konstante sys.abiflags vorhanden ist.) Für jede der verschiedenen Kopf-Schwanz-Kombinationen wird geprüft, ob sie auf ein vorhandenes Verzeichnis verweist, und wenn ja, wird es zu sys.path hinzugefügt, und der neu hinzugefügte Pfad wird ebenfalls nach Konfigurationsdateien durchsucht.

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 werden Free-Threading-Python-Installationen durch das "t"-Suffix im versionsspezifischen Verzeichnisnamen identifiziert, z. B. lib/python3.13t/.

Geändert in Version 3.14: site ist nicht mehr für die Aktualisierung von sys.prefix und sys.exec_prefix in virtuellen Umgebungen verantwortlich. Dies geschieht nun während der Pfadinitialisierung. Infolgedessen hängen unter virtuellen Umgebungen sys.prefix und sys.exec_prefix nicht mehr von der site-Initialisierung ab und sind daher von -S unbeeinflusst.

Beim Ausführen in einer virtuellen Umgebung wird die Datei pyvenv.cfg in sys.prefix auf standortspezifische Konfigurationen überprüft. Wenn der Schlüssel include-system-site-packages vorhanden ist und auf true (Groß-/Kleinschreibung wird nicht beachtet) gesetzt ist, werden die systemweiten Präfixe nach site-packages durchsucht, andernfalls nicht.

Eine Pfadkonfigurationsdatei ist eine Datei, deren Name die Form name.pth hat und in einem der vier oben genannten Verzeichnisse existiert; ihr Inhalt sind zusätzliche Elemente (eins pro Zeile), die zu sys.path hinzugefügt werden. Nicht existierende Elemente werden niemals zu sys.path hinzugefügt, und es wird nicht geprüft, ob das Element auf eine Datei und nicht auf ein Verzeichnis verweist. Kein Element wird mehr als einmal zu sys.path hinzugefügt. Leere Zeilen und Zeilen, die mit # beginnen, werden übersprungen. Zeilen, die mit import beginnen (gefolgt von Leerzeichen oder Tabulator), werden ausgeführt.

Hinweis

Eine ausführbare Zeile in einer .pth-Datei wird bei jedem Python-Start ausgeführt, unabhängig davon, ob ein bestimmtes Modul tatsächlich verwendet wird. Ihre Auswirkungen sollten daher auf ein Minimum beschränkt werden. Der primäre Verwendungszweck ausführbarer Zeilen ist es, die entsprechenden Module importierbar zu machen (3rd-Party-Import-Hooks laden, PATH usw. anpassen). Jede andere Initialisierung soll bei der tatsächlichen Importierung eines Moduls erfolgen, falls und wenn sie stattfindet. Die Beschränkung eines Codeblocks auf eine einzige Zeile ist eine bewusste Maßnahme, um die Aufnahme von komplexerem Code hier zu verhindern.

Geändert in Version 3.13: Die .pth-Dateien werden zuerst mit UTF-8 und dann mit der Locale-Encoding dekodiert, wenn dies fehlschlägt.

Nehmen Sie zum Beispiel an, sys.prefix und sys.exec_prefix sind auf /usr/local gesetzt. Die Python X.Y-Bibliothek wird dann in /usr/local/lib/pythonX.Y installiert. Angenommen, dies hat ein Unterverzeichnis /usr/local/lib/pythonX.Y/site-packages mit drei Unterunterverzeichnissen, foo, bar und spam, sowie zwei Pfadkonfigurationsdateien, foo.pth und bar.pth. Angenommen, foo.pth enthält Folgendes

# foo package configuration

foo
bar
bletch

und bar.pth enthält

# 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

Beachten Sie, dass bletch ausgelassen wird, da es nicht existiert; das Verzeichnis bar kommt vor dem Verzeichnis foo, da bar.pth alphabetisch vor foo.pth kommt; und spam wird ausgelassen, da es in keiner der Pfadkonfigurationsdateien erwähnt wird.

sitecustomize

Nach diesen Pfadmanipulationen wird versucht, ein Modul namens sitecustomize zu importieren, das beliebige standortspezifische Anpassungen vornehmen kann. Es wird typischerweise von einem Systemadministrator im site-packages-Verzeichnis erstellt. Wenn dieser Import mit einem ImportError oder einer seiner Unterklassenausnahmen fehlschlägt und das Attribut name der Ausnahme gleich 'sitecustomize' ist, wird er stillschweigend ignoriert. Wenn Python ohne verfügbare Ausgabeströme gestartet wird, wie z. B. mit pythonw.exe unter Windows (das standardmäßig zum Starten von IDLE verwendet wird), werden versuchte Ausgaben von sitecustomize ignoriert. Jede andere Ausnahme führt zu einem stillen und möglicherweise mysteriösen Fehlschlag des Prozesses.

usercustomize

Danach wird versucht, ein Modul namens usercustomize zu importieren, das beliebige benutzerspezifische Anpassungen vornehmen kann, wenn ENABLE_USER_SITE wahr ist. Diese Datei soll im benutzerbezogenen site-packages-Verzeichnis (siehe unten) erstellt werden, das Teil von sys.path ist, sofern es nicht durch -s deaktiviert wurde. Wenn dieser Import mit einem ImportError oder einer seiner Unterklassenausnahmen fehlschlägt und das Attribut name der Ausnahme gleich 'usercustomize' ist, wird er stillschweigend ignoriert.

Beachten Sie, dass auf einigen Nicht-Unix-Systemen sys.prefix und sys.exec_prefix leer sind und die Pfadmanipulationen übersprungen werden; der Import von sitecustomize und usercustomize wird jedoch weiterhin versucht.

Readline-Konfiguration

Auf Systemen, die readline unterstützen, importiert und konfiguriert dieses Modul auch das Modul rlcompleter, wenn Python im interaktiven Modus und ohne die Option -S gestartet wird. Das Standardverhalten ist die Aktivierung der Tab-Vervollständigung und die Verwendung von ~/.python_history als Speicherdatei für den Verlauf. Um dies zu deaktivieren, löschen (oder überschreiben) Sie das Attribut sys.__interactivehook__ in Ihrem sitecustomize- oder usercustomize-Modul oder in Ihrer PYTHONSTARTUP-Datei.

Geändert in Version 3.4: Die Aktivierung von rlcompleter und Verlauf wurde automatisch vorgenommen.

Modulinhalt

site.PREFIXES

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

site.ENABLE_USER_SITE

Flagge, die den Status des benutzerspezifischen site-packages-Verzeichnisses anzeigt. True bedeutet, dass es aktiviert und zu sys.path hinzugefügt wurde. False bedeutet, dass es auf Benutzerwunsch deaktiviert wurde (mit -s oder PYTHONNOUSERSITE). None bedeutet, dass es aus Sicherheitsgründen (Ungleichheit zwischen Benutzer- oder Gruppen-ID und effektiver ID) oder von einem Administrator deaktiviert wurde.

site.USER_SITE

Pfad zum benutzerbezogenen site-packages-Verzeichnis für das laufende Python. Kann None sein, wenn getusersitepackages() noch nicht aufgerufen wurde. Der Standardwert ist ~/.local/lib/pythonX.Y[t]/site-packages für UNIX- und Nicht-Framework-macOS-Builds, ~/Library/Python/X.Y/lib/python/site-packages für macOS-Framework-Builds und %APPDATA%\Python\PythonXY\site-packages unter Windows. Das optionale "t" kennzeichnet den Free-Threading-Build. Dieses Verzeichnis ist ein site-Verzeichnis, was bedeutet, dass .pth-Dateien darin verarbeitet werden.

site.USER_BASE

Pfad zum Basisverzeichnis für die benutzerbezogenen site-packages. Kann None sein, wenn getuserbase() noch nicht aufgerufen wurde. Der Standardwert ist ~/.local für UNIX- und macOS-Nicht-Framework-Builds, ~/Library/Python/X.Y für macOS-Framework-Builds und %APPDATA%\Python für Windows. Dieser Wert wird verwendet, um die Installationsverzeichnisse für Skripte, Datendateien, Python-Module usw. für das Benutzerinstallationsschema zu berechnen. Siehe auch PYTHONUSERBASE.

site.main()

Fügt alle standardmäßigen standortspezifischen Verzeichnisse zum Modulsuchpfad hinzu. Diese Funktion wird automatisch aufgerufen, wenn dieses Modul importiert wird, es sei denn, der Python-Interpreter wurde mit der Option -S gestartet.

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

site.addsitedir(sitedir, known_paths=None)

Fügt ein Verzeichnis zu sys.path hinzu und verarbeitet seine .pth-Dateien. Wird typischerweise in sitecustomize oder usercustomize (siehe oben) verwendet.

site.getsitepackages()

Gibt eine Liste zurück, die alle globalen site-packages-Verzeichnisse enthält.

Hinzugefügt in Version 3.2.

site.getuserbase()

Gibt den Pfad zum Basisverzeichnis des Benutzers, USER_BASE, zurück. Wenn es noch nicht initialisiert ist, wird diese Funktion es auch setzen und dabei PYTHONUSERBASE berücksichtigen.

Hinzugefügt in Version 3.2.

site.getusersitepackages()

Gibt den Pfad zum benutzerspezifischen site-packages-Verzeichnis, USER_SITE, zurück. Wenn es noch nicht initialisiert ist, wird diese Funktion es auch setzen und dabei USER_BASE berücksichtigen. Um festzustellen, ob das benutzerbezogene site-packages-Verzeichnis zu sys.path hinzugefügt wurde, sollte ENABLE_USER_SITE verwendet werden.

Hinzugefügt in Version 3.2.

Kommandozeilenschnittstelle

Das Modul site bietet auch eine Möglichkeit, die Benutzerverzeichnisse von der Kommandozeile abzurufen

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

Wenn es ohne Argumente aufgerufen wird, gibt es den Inhalt von sys.path auf der Standardausgabe aus, gefolgt vom Wert von USER_BASE und ob das Verzeichnis existiert, 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 benutzerbezogenen site-packages-Verzeichnis aus.

Wenn beide Optionen angegeben sind, werden Benutzerbasis und Benutzer-Site ausgegeben (immer in dieser Reihenfolge), getrennt durch os.pathsep.

Wenn eine Option angegeben ist, wird das Skript mit einem der folgenden Werte beendet: 0, wenn das benutzerbezogene site-packages-Verzeichnis aktiviert ist, 1, wenn es vom Benutzer deaktiviert wurde, 2, wenn es aus Sicherheitsgründen oder von einem Administrator deaktiviert ist, und ein Wert größer als 2, wenn ein Fehler vorliegt.

Siehe auch