py_compile — Kompilera Python-källfiler

Källkod: Lib/py_compile.py

Modulen py_compile innehåller en funktion för att generera en bytekodfil från en källfil och en annan funktion som används när modulens källfil anropas som ett skript.

Även om den här funktionen inte behövs ofta kan den vara användbar när du installerar moduler för gemensamt bruk, särskilt om vissa av användarna kanske inte har behörighet att skriva bytekodcachefilerna i katalogen som innehåller källkoden.

exception py_compile.PyCompileError

Undantag som uppstår när ett fel inträffar vid försök att kompilera filen.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Kompilera en källfil till byte-code och skriv ut cache-filen för byte-code. Källkoden laddas från filen med namnet file. Bytekoden skrivs till cfile, som som standard är sökvägen PEP 3147/PEP 488, som slutar på .pyc. Om file till exempel är /foo/bar/baz.py kommer cfile som standard att vara /foo/bar/__pycache__/baz.cpython-32.pyc för Python 3.2. Om dfile anges används det i stället för file som namn på källfilen från vilken källrader hämtas för visning i spårningar av undantag. Om doraise är true, skapas ett PyCompileError när ett fel uppstår under kompileringen av file. Om doraise är false (standard) skrivs en felsträng till sys.stderr, men inget undantag görs. Denna funktion returnerar sökvägen till den bytekompilerade filen, dvs. det värde för cfile som användes.

Argumenten doraise och quiet bestämmer hur fel ska hanteras vid kompilering av filen. Om quiet är 0 eller 1, och doraise är false, aktiveras standardbeteendet: en felsträng skrivs till sys.stderr, och funktionen returnerar None istället för en sökväg. Om doraise är true skapas istället ett PyCompileError. Men om quiet är 2 skrivs inget meddelande och doraise har ingen effekt.

Om den sökväg som cfile blir (antingen explicit angiven eller beräknad) är en symlänk eller en icke-vanlig fil, kommer FileExistsError att tas upp. Detta är för att fungera som en varning om att import kommer att göra dessa sökvägar till vanliga filer om det är tillåtet att skriva bytekompilerade filer till dessa sökvägar. Detta är en bieffekt av att import använder filomdöpning för att placera den slutliga bytekompilerade filen på plats för att förhindra problem med samtidig filskrivning.

optimize styr optimeringsnivån och skickas till den inbyggda funktionen compile(). Standardvärdet -1 väljer optimeringsnivån för den aktuella tolken.

invalidation_mode bör vara en medlem av enum PycInvalidationMode och styr hur den genererade bytecode-cachen ogiltigförklaras vid körning. Standardvärdet är PycInvalidationMode.CHECKED_HASH om miljövariabeln SOURCE_DATE_EPOCH är inställd, annars är standardvärdet PycInvalidationMode.TIMESTAMP.

Ändrad i version 3.2: Ändrat standardvärde för cfile för att vara PEP 3147-kompatibelt. Tidigare standard var file + 'c' ('o' om optimering var aktiverad). Parametern optimize har också lagts till.

Ändrad i version 3.4: Ändrade koden så att den använder importlib för skrivning av bytekodcache-filer. Detta innebär att semantiken för att skapa/skriva filer nu matchar vad importlib gör, t.ex. behörigheter, skriv-och-flytta-semantik, etc. Jag har också lagt till en varning om att FileExistsError uppstår om cfile är en symlänk eller en icke vanlig fil.

Ändrad i version 3.7: Parametern invalidation_mode lades till enligt specifikationen i PEP 552. Om miljövariabeln SOURCE_DATE_EPOCH är inställd, kommer invalidation_mode att tvingas till PycInvalidationMode.CHECKED_HASH.

Ändrad i version 3.7.2: Miljövariabeln SOURCE_DATE_EPOCH åsidosätter inte längre värdet på argumentet invalidation_mode, utan fastställer istället dess standardvärde.

Ändrad i version 3.8: Parametern quiet har lagts till.

class py_compile.PycInvalidationMode

En uppräkning av möjliga metoder som tolken kan använda för att avgöra om en bytecode-fil är uppdaterad med en källfil. Filen .pyc anger önskat invalidiseringsläge i sitt huvud. Se Inaktivering av cachad bytekod för mer information om hur Python ogiltigförklarar .pyc-filer vid körning.

Tillagd i version 3.7.

TIMESTAMP

Filen .pyc innehåller tidsstämpel och storlek på källfilen, som Python kommer att jämföra med metadata för källfilen vid körning för att avgöra om filen .pyc behöver återskapas.

CHECKED_HASH

Filen .pyc innehåller en hash av källfilens innehåll, som Python kommer att jämföra med källan vid körning för att avgöra om filen .pyc behöver återskapas.

UNCHECKED_HASH

Precis som CHECKED_HASH innehåller filen .pyc en hash av källfilens innehåll. Python kommer dock vid körning att anta att filen .pyc är uppdaterad och inte validera .pyc mot källfilen alls.

Detta alternativ är användbart när .pycs hålls uppdaterade av något system utanför Python, t.ex. ett byggsystem.

Kommandoradsgränssnitt

Denna modul kan anropas som ett skript för att kompilera flera källfiler. Filerna som anges i filnamn kompileras och den resulterande bytekoden cachelagras på vanligt sätt. Programmet söker inte igenom en katalogstruktur för att hitta källfiler, utan kompilerar endast filer som uttryckligen namnges. Exit-statusen är ung om en av filerna inte kunde kompileras.

<file> ... <fileN>
-

Positionella argument är filer som ska kompileras. Om - är den enda parametern hämtas listan med filer från standardinmatningen.

-q, --quiet

Undertrycka fel i utmatningen.

Ändrad i version 3.2: Lagt till stöd för -.

Ändrad i version 3.10: Lagt till stöd för -q.

Se även

Modul compileall

Verktyg för att kompilera alla Python-källfiler i ett katalogträd.