compileall — Byte-kompilera Python-bibliotek

Källkod: Lib/compileall.py

Den här modulen innehåller några verktygsfunktioner för att stödja installation av Python-bibliotek. Dessa funktioner kompilerar Python-källfiler i ett katalogträd. Den här modulen kan användas för att skapa cachade bytekodfiler vid biblioteksinstallationen, vilket gör att de kan användas även av användare som inte har skrivbehörighet till bibliotekskatalogerna.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Användning av kommandoraden

Denna modul kan fungera som ett skript (med python -m compileall) för att kompilera Python-källor.

directory ...
file ...

Positionella argument är filer som ska kompileras eller kataloger som innehåller källfiler, som genomkorsas rekursivt. Om inget argument anges, beter sig programmet som om kommandoraden var -l <kataloger från sys.path>.

-l

Gå inte tillbaka till underkataloger, utan kompilera endast källkodsfiler som finns direkt i de namngivna eller underförstådda katalogerna.

-f

Tvinga fram en ombyggnad även om tidsstämplarna är uppdaterade.

-q

Skriv inte ut listan över kompilerade filer. Om det anges en gång kommer felmeddelanden fortfarande att skrivas ut. Om det skickas två gånger (-qq), kommer alla utdata att undertryckas.

-d destdir

Katalog som föregås av sökvägen till varje fil som kompileras. Detta visas i spårningar under kompileringstiden och kompileras också in i byte-kodfilen, där det används i spårningar och andra meddelanden i de fall källfilen inte finns när byte-kodfilen körs.

-s strip_prefix

Tar bort det angivna prefixet från sökvägar som registrerats i filerna .pyc. Sökvägarna görs relativt till prefixet.

Detta alternativ kan användas med -p men inte med -d.

-p prepend_prefix

Lägg till det angivna prefixet till sökvägar som registrerats i filerna .pyc. Använd -p / för att göra sökvägarna absoluta.

Detta alternativ kan användas med -s men inte med -d.

-x regex

regex används för att söka igenom hela sökvägen till varje fil som övervägs för kompilering, och om regex ger en träff hoppas filen över.

-i list

Läs filen list och lägg till varje rad som den innehåller i listan över filer och kataloger som ska kompileras. Om list är -, läs rader från stdin.

-b

Skriv byte-kodfilerna till deras äldre platser och namn, vilket kan skriva över byte-kodfiler som skapats av en annan version av Python. Standardinställningen är att skriva filer till deras PEP 3147-platser och namn, vilket gör att byte-kodfiler från flera versioner av Python kan samexistera.

-r

Styr den maximala rekursionsnivån för underkataloger. Om detta anges kommer alternativet -l inte att beaktas. python -m compileall <directory> -r 0 är likvärdigt med python -m compileall <directory> -l.

-j N

Använd N arbetare för att kompilera filerna i den angivna katalogen. Om 0 används, kommer resultatet av os.process_cpu_count() att användas.

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

Kontrollera hur de genererade byte-kodfilerna ogiltigförklaras vid körning. Värdet timestamp innebär att .pyc -filer med källkodens tidsstämpel och storlek inbäddade kommer att genereras. Värdena checked-hash och unchecked-hash gör att hash-baserade pycs genereras. Hash-baserade pycs inbäddar en hash av källfilens innehåll istället för en tidsstämpel. Se Inaktivering av cachad bytekod för mer information om hur Python validerar bytecode-cachefiler vid körning. Standardvärdet är timestamp om miljövariabeln SOURCE_DATE_EPOCH inte är inställd, och checked-hash om miljövariabeln SOURCE_DATE_EPOCH är inställd.

-o level

Kompilera med den angivna optimeringsnivån. Kan användas flera gånger för att kompilera för flera nivåer åt gången (t.ex. compileall -o 1 -o 2).

-e dir

Ignorera symlänkar som pekar utanför den angivna katalogen.

Om två .pyc-filer med olika optimeringsnivå har samma innehåll, använd hårda länkar för att konsolidera duplicerade filer.

Ändrad i version 3.2: Lagt till alternativen -i, -b och -h.

Ändrad i version 3.5: Lagt till alternativen -j, -r och -qq. alternativet -q ändrades till ett värde med flera nivåer. -b kommer alltid att producera en bytekodfil som slutar på .pyc, aldrig .pyo.

Ändrad i version 3.7: Lagt till alternativet --invalidation-mode.

Ändrad i version 3.9: Lade till alternativen -s, -p, -e och --hardlink-dupes. Höjde standardrekursionsgränsen från 10 till sys.getrecursionlimit(). Lagt till möjligheten att ange alternativet -o flera gånger.

Det finns inget kommandoradsalternativ för att styra optimeringsnivån som används av compile()-funktionen, eftersom Python-tolken själv redan tillhandahåller alternativet: python -O -m compileall.

På samma sätt respekterar funktionen compile() inställningen sys.pycache_prefix. Den genererade bytecode-cachen kommer bara att vara användbar om compile() körs med samma sys.pycache_prefix (om något) som kommer att användas vid körning.

Offentliga funktioner

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Går rekursivt ner i katalogträdet som namnges av dir och kompilerar alla .py-filer längs vägen. Returnerar ett sant värde om alla filer har kompilerats framgångsrikt, och ett falskt värde annars.

Parametern maxlevels används för att begränsa djupet på rekursionen; standardvärdet är sys.getrecursionlimit().

Om ddir anges läggs den till sökvägen till varje fil som kompileras för att användas i spårningar under kompileringstiden och kompileras även in i byte-kodfilen, där den används i spårningar och andra meddelanden i de fall källfilen inte finns när byte-kodfilen körs.

Om force är sant kompileras moduler om även om tidsstämplarna är uppdaterade.

Om rx anges, anropas dess search-metod på den fullständiga sökvägen till varje fil som övervägs för kompilering, och om den returnerar ett sant värde hoppas filen över. Detta kan användas för att utesluta filer som matchar ett reguljärt uttryck, givet som ett re.Pattern-objekt.

Om quiet är False eller 0 (standard) skrivs filnamnen och annan information ut till standardutskriften. Om värdet är 1 skrivs endast fel ut. Om värdet är 2 undertrycks alla utdata.

Om legacy är sant skrivs byte-kodfiler till sina äldre platser och namn, vilket kan skriva över byte-kodfiler som skapats av en annan version av Python. Standardinställningen är att skriva filer till deras PEP 3147-platser och namn, vilket gör att byte-kodfiler från flera versioner av Python kan samexistera.

optimize anger optimeringsnivån för kompilatorn. Den skickas till den inbyggda funktionen compile(). Accepterar även en sekvens av optimeringsnivåer som leder till flera kompileringar av en .py-fil i ett anrop.

Argumentet workers anger hur många workers som används för att kompilera filer parallellt. Standardinställningen är att inte använda flera arbetare. Om plattformen inte kan använda flera arbetare och argumentet workers anges, kommer sekventiell kompilering att användas som en reservlösning. Om workers är 0 används antalet kärnor i systemet. Om workers är lägre än 0, kommer ett ValueError att uppstå.

invalidation_mode bör vara en medlem av enum py_compile.PycInvalidationMode och styr hur de genererade pycs ogiltigförklaras vid körning.

Argumenten stripdir, prependdir och limit_sl_dest motsvarar alternativen -s, -p och -e som beskrivs ovan. De kan anges som str eller os.PathLike.

Om hardlink_dupes är true och två .pyc-filer med olika optimeringsnivå har samma innehåll, används hårda länkar för att konsolidera duplicerade filer.

Ändrad i version 3.2: Lagt till parametrarna legacy och optimize.

Ändrad i version 3.5: Parametern workers har lagts till.

Ändrad i version 3.5: parametern quiet har ändrats till ett värde med flera nivåer.

Ändrad i version 3.5: Parametern legacy skriver bara ut .pyc -filer, inte .pyo -filer oavsett värdet på optimize.

Ändrad i version 3.6: Accepterar en path-like object.

Ändrad i version 3.7: Parametern invalidation_mode har lagts till.

Ändrad i version 3.7.2: Parametern invalidation_mode:s standardvärde uppdateras till None.

Ändrad i version 3.8: Om workers sätts till 0 väljs nu det optimala antalet kärnor.

Ändrad i version 3.9: Argumenten stripdir, prependdir, limit_sl_dest och hardlink_dupes lades till. Standardvärdet för maxlevels ändrades från 10 till sys.getrecursionlimit()

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

Kompilera filen med sökvägen fullname. Returnerar ett sant värde om filen har kompilerats framgångsrikt, och ett falskt värde annars.

Om ddir anges, läggs den till sökvägen till den fil som kompileras för att användas i spårningar under kompileringstiden och kompileras även in i byte-kodfilen, där den används i spårningar och andra meddelanden i de fall källfilen inte finns när byte-kodfilen körs.

Om rx anges får dess metod search det fullständiga sökvägsnamnet till den fil som ska kompileras och om den returnerar ett sant värde kompileras inte filen och True returneras. Detta kan användas för att utesluta filer som matchar ett reguljärt uttryck, givet som ett re.Pattern-objekt.

Om quiet är False eller 0 (standard) skrivs filnamnen och annan information ut till standardutskriften. Om värdet är 1 skrivs endast fel ut. Om värdet är 2 undertrycks alla utdata.

Om legacy är sant skrivs byte-kodfiler till sina äldre platser och namn, vilket kan skriva över byte-kodfiler som skapats av en annan version av Python. Standardinställningen är att skriva filer till deras PEP 3147-platser och namn, vilket gör att byte-kodfiler från flera versioner av Python kan samexistera.

optimize anger optimeringsnivån för kompilatorn. Den skickas till den inbyggda funktionen compile(). Accepterar även en sekvens av optimeringsnivåer som leder till flera kompileringar av en .py-fil i ett anrop.

invalidation_mode bör vara en medlem av enum py_compile.PycInvalidationMode och styr hur de genererade pycs ogiltigförklaras vid körning.

Argumenten stripdir, prependdir och limit_sl_dest motsvarar alternativen -s, -p och -e som beskrivs ovan. De kan anges som str eller os.PathLike.

Om hardlink_dupes är true och två .pyc-filer med olika optimeringsnivå har samma innehåll, används hårda länkar för att konsolidera duplicerade filer.

Tillagd i version 3.2.

Ändrad i version 3.5: parametern quiet har ändrats till ett värde med flera nivåer.

Ändrad i version 3.5: Parametern legacy skriver bara ut .pyc -filer, inte .pyo -filer oavsett värdet på optimize.

Ändrad i version 3.7: Parametern invalidation_mode har lagts till.

Ändrad i version 3.7.2: Parametern invalidation_mode:s standardvärde uppdateras till None.

Ändrad i version 3.9: Lagt till argumenten stripdir, prependdir, limit_sl_dest och hardlink_dupes.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Bytekompilera alla .py-filer som finns längs sys.path. Returnerar ett sant värde om alla filer har kompilerats framgångsrikt, och ett falskt värde annars.

Om skip_curdir är true (standard) inkluderas inte den aktuella katalogen i sökningen. Alla andra parametrar skickas till funktionen compile_dir(). Observera att till skillnad från de andra kompileringsfunktionerna är maxlevels standardvärdet 0.

Ändrad i version 3.2: Lagt till parametrarna legacy och optimize.

Ändrad i version 3.5: parametern quiet har ändrats till ett värde med flera nivåer.

Ändrad i version 3.5: Parametern legacy skriver bara ut .pyc -filer, inte .pyo -filer oavsett värdet på optimize.

Ändrad i version 3.7: Parametern invalidation_mode har lagts till.

Ändrad i version 3.7.2: Parametern invalidation_mode:s standardvärde uppdateras till None.

För att tvinga fram en omkompilering av alla .py-filer i Lib/-underkatalogen och alla dess underkataloger:

import compileall

compileall.compile_dir('Lib/', force=True)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

Se även

Modul py_compile

Bytekompilera en enda källfil.