site — Platsspecifik konfigurations-hook

Källkod: Lib/site.py

Denna modul importeras automatiskt under initieringen. Den automatiska importen kan undertryckas med hjälp av tolkens alternativ -S.

Import av denna modul lägger normalt till platsspecifika sökvägar till modulens sökväg och lägger till callables, inklusive help() till det inbyggda namnrymden. Pythons startalternativ -S blockerar dock detta och den här modulen kan importeras på ett säkert sätt utan automatiska ändringar av modulens sökväg eller tillägg till de inbyggda namnrymderna. För att uttryckligen utlösa de vanliga platsspecifika tilläggen, anropa funktionen main().

Ändrad i version 3.3: Import av modulen utlöste tidigare manipulering av sökvägar även när -S användes.

Den börjar med att konstruera upp till fyra kataloger från en huvud- och en svansdel. För huvuddelen används sys.prefix och sys.exec_prefix; tomma huvuden hoppas över. För tail-delen används den tomma strängen och sedan lib/site-packages (på Windows) eller lib/pythonX.Y[t]/site-packages (på Unix och macOS). (Det valfria suffixet ”t” anger free threading build, och läggs till om "t" finns i konstanten sys.abiflags) För var och en av de olika huvud-svans-kombinationerna undersöks om den hänvisar till en befintlig katalog, och om så är fallet läggs den till i sys.path och den nyligen tillagda sökvägen inspekteras även med avseende på konfigurationsfiler.

Ändrad i version 3.5: Stöd för katalogen ”site-python” har tagits bort.

Ändrad i version 3.13: På Unix identifieras Free threading Python-installationer med suffixet ”t” i det versionsspecifika katalognamnet, till exempel lib/python3.13t/.

Ändrad i version 3.14: site är inte längre ansvarig för uppdatering av sys.prefix och sys.exec_prefix på Virtuella miljöer. Detta görs nu under path initialization. Som ett resultat, under Virtuella miljöer, är sys.prefix och sys.exec_prefix inte längre beroende av initieringen av site, och påverkas därför inte av -S.

När du kör under en virtuell miljö, kontrolleras filen pyvenv.cfg i sys.prefix för platsspecifika konfigurationer. Om nyckeln include-system-site-packages finns och är satt till true (skiftlägesokänslig), kommer prefixen på systemnivå att sökas efter site-packages, annars inte.

En sökvägskonfigurationsfil är en fil vars namn har formen name.pth och som finns i en av de fyra kataloger som nämns ovan; dess innehåll är ytterligare objekt (ett per rad) som ska läggas till i sys.path. Icke-existerande objekt läggs aldrig till i sys.path, och ingen kontroll görs av att objektet hänvisar till en katalog snarare än en fil. Inget objekt läggs till i sys.path mer än en gång. Tomma rader och rader som börjar med # hoppas över. Rader som börjar med import (följt av mellanslag eller tabb) exekveras.

Anteckning

En exekverbar rad i en .pth-fil körs vid varje Python-start, oavsett om en viss modul faktiskt kommer att användas. Dess inverkan bör därför hållas till ett minimum. Det primära syftet med körbara rader är att göra motsvarande modul(er) importerbar (ladda import-hooks från tredje part, justera PATH etc). Alla andra initialiseringar ska göras när en modul faktiskt importeras, om och när det sker. Att begränsa en koddel till en enda rad är en avsiktlig åtgärd för att avskräcka från att lägga in något mer komplext här.

Ändrad i version 3.13: .pth -filerna avkodas nu först med UTF-8 och sedan med locale encoding om det misslyckas.

Anta till exempel att sys.prefix och sys.exec_prefix är inställda på /usr/local. Python X.Y-biblioteket installeras sedan i /usr/local/lib/pythonX.Y. Antag att detta har en underkatalog /usr/local/lib/pythonX.Y/site-packages med tre underkataloger, foo, bar och spam, och två sökvägskonfigurationsfiler, foo.pth och bar.pth. Antag att foo.pth innehåller följande:

# foo package configuration

foo
bar
bletch

och bar.pth innehåller:

# bar package configuration

bar

Sedan läggs följande versionsspecifika kataloger till i sys.path, i denna ordning:

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

Observera att bletch utelämnas eftersom den inte finns; katalogen bar föregår katalogen foo eftersom bar.pth kommer i alfabetisk ordning före foo.pth; och spam utelämnas eftersom den inte nämns i någon av sökvägskonfigurationsfilerna.

sitecustomize

Efter dessa sökvägsmanipulationer görs ett försök att importera en modul med namnet sitecustomize, som kan utföra godtyckliga platsspecifika anpassningar. Den skapas vanligtvis av en systemadministratör i katalogen site-packages. Om denna import misslyckas med ett ImportError eller dess underklassundantag, och undantagets name-attribut är lika med 'sitecustomize', ignoreras det tyst. Om Python startas utan tillgängliga utdataströmmar, som med pythonw.exe på Windows (som används som standard för att starta IDLE), ignoreras försök till utdata från sitecustomize. Alla andra undantag orsakar ett tyst och kanske mystiskt misslyckande av processen.

usercustomize

Efter detta görs ett försök att importera en modul med namnet usercustomize, som kan utföra godtyckliga användarspecifika anpassningar, om ENABLE_USER_SITE är true. Den här filen är avsedd att skapas i användarens site-packages-katalog (se nedan), som är en del av sys.path om den inte inaktiveras av -s. Om denna import misslyckas med ett ImportError eller dess underklass undantag, och undantagets name attribut är lika med 'usercustomize', ignoreras det i tysthet.

Observera att för vissa icke-Unix-system är sys.prefix och sys.exec_prefix tomma och sökvägsmanipulationerna hoppas över; dock försöker man fortfarande importera sitecustomize och usercustomize.

Konfiguration av läslinje

På system som stöder readline kommer denna modul även att importera och konfigurera modulen rlcompleter, om Python startas i interaktivt läge och utan alternativet -S. Standardinställningen är att aktivera tabkomplettering och att använda ~/.python_history som historikfil. För att inaktivera det, ta bort (eller åsidosätt) attributet sys.__interactivehook__ i din modul sitecustomize eller usercustomize eller din fil PYTHONSTARTUP.

Ändrad i version 3.4: Aktivering av rlcompleter och historik gjordes automatiskt.

Modulens innehåll

site.PREFIXES

En lista med prefix för kataloger för site-packages.

site.ENABLE_USER_SITE

Flagga som visar status för användarkatalogen site-packages. True betyder att den är aktiverad och har lagts till i sys.path. False betyder att den inaktiverades på begäran av användaren (med -s eller PYTHONNOUSERSITE). None betyder att den inaktiverades av säkerhetsskäl (felmatchning mellan användar- eller grupp-id och effektivt id) eller av en administratör.

site.USER_SITE

Sökväg till användarens site-paket för den Python som körs. Kan vara None om getusersitepackages() inte har anropats ännu. Standardvärdet är ~/.local/lib/pythonX.Y[t]/site-packages för UNIX och macOS-byggnader utan ramverk, ~/Library/Python/X.Y/lib/python/site-packages för macOS-ramverk och %APPDATA%\Python\PythonXY\site-packages på Windows. Det valfria ”t” indikerar fritt trådad byggnation. Den här katalogen är en site-katalog, vilket innebär att .pth -filer i den kommer att bearbetas.

site.USER_BASE

Sökväg till baskatalogen för användarens site-paket. Kan vara None om getuserbase() inte har anropats ännu. Standardvärdet är ~/.local för UNIX och macOS utan ramverk, ~/Library/Python/X.Y för macOS med ramverk och %APPDATA%\Python för Windows. Detta värde används för att beräkna installationskatalogerna för skript, datafiler, Python-moduler etc. för användarens installationsschema. Se även PYTHONUSERBASE.

site.main()

Lägger till alla standardkataloger som är specifika för webbplatsen till modulens sökväg. Denna funktion anropas automatiskt när denna modul importeras, såvida inte Python-tolken startades med flaggan -S.

Ändrad i version 3.3: Denna funktion brukade tidigare anropas villkorslöst.

site.addsitedir(sitedir, known_paths=None)

Lägg till en katalog i sys.path och bearbeta dess .pth-filer. Används vanligen i sitecustomize eller usercustomize (se ovan).

site.getsitepackages()

Returnerar en lista som innehåller alla globala site-packages-kataloger.

Tillagd i version 3.2.

site.getuserbase()

Returnerar sökvägen till användarens baskatalog, USER_BASE. Om den inte är initialiserad ännu kommer den här funktionen också att ställa in den, med respekt för PYTHONUSERBASE.

Tillagd i version 3.2.

site.getusersitepackages()

Returnerar sökvägen till den användarspecifika katalogen för webbplats-paket, USER_SITE. Om den inte är initialiserad ännu kommer den här funktionen också att ställa in den, med respekt för USER_BASE. För att avgöra om det användarspecifika webbplatspaketet har lagts till i sys.path bör ENABLE_USER_SITE användas.

Tillagd i version 3.2.

Kommandoradsgränssnitt

Modulen site ger också möjlighet att hämta användarkataloger från kommandoraden:

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

Om den anropas utan argument skrivs innehållet i sys.path ut på standardutmatningen, följt av värdet på USER_BASE och om katalogen finns, sedan samma sak för USER_SITE och slutligen värdet på ENABLE_USER_SITE.

--user-base

Skriv ut sökvägen till användarens baskatalog.

--user-site

Skriv ut sökvägen till användarens katalog för site-packages.

Om båda alternativen anges skrivs användarbas och användarwebbplats ut (alltid i denna ordning), åtskilda av os.pathsep.

Om något alternativ anges kommer skriptet att avslutas med ett av följande värden: 0 om användarkatalogen site-packages är aktiverad, 1 om den har inaktiverats av användaren, 2 om den har inaktiverats av säkerhetsskäl eller av en administratör, och ett värde större än 2 om ett fel har inträffat.

Se även