runpy — Lokalisering och exekvering av Python-moduler

Källkod: Lib/runpy.py

Modulen runpy används för att hitta och köra Python-moduler utan att importera dem först. Den används huvudsakligen för att implementera kommandoradsalternativet -m som gör att skript kan lokaliseras med hjälp av Python-modulens namnrymd i stället för filsystemet.

Observera att detta inte är en sandlådemodul - all kod exekveras i den aktuella processen och eventuella sidoeffekter (t.ex. cachad import av andra moduler) kommer att finnas kvar efter att funktionerna har returnerats.

Dessutom är det inte garanterat att funktioner och klasser som definieras av den exekverade koden fungerar korrekt efter att en runpy-funktion har returnerats. Om denna begränsning inte är acceptabel för ett visst användningsfall, är importlib sannolikt ett lämpligare val än denna modul.

Modulen runpy innehåller två funktioner:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

Exekverar koden för den angivna modulen och returnerar den resulterande modulens globals-ordbok. Modulens kod lokaliseras först med hjälp av standardimportmekanismen (se PEP 302 för detaljer) och exekveras sedan i ett nytt modulnamnrymd.

Argumentet mod_name bör vara ett absolut modulnamn. Om modulnamnet hänvisar till ett paket i stället för en vanlig modul importeras paketet och undermodulen __main__ i paketet exekveras och den resulterande modulens globala ordbok returneras.

Det valfria ordboksargumentet init_globals kan användas för att fylla på modulens globala ordbok innan koden exekveras. init_globals kommer inte att modifieras. Om någon av de speciella globala variablerna nedan är definierade i init_globals, åsidosätts dessa definitioner av run_module().

De speciella globala variablerna __name__, __spec__, __file__, __cached__, __loader__ och __package__ sätts i globals-ordlistan innan modulkoden exekveras. (Observera att detta är en minimal uppsättning variabler - andra variabler kan ställas in implicit som en implementationsdetalj för tolken)

__name__ sätts till run_name om detta valfria argument inte är None, till mod_name + '.__main__' om den namngivna modulen är ett paket och till argumentet mod_name i annat fall.

__spec__ kommer att ställas in på lämpligt sätt för den verkligen importerade modulen (dvs. __spec__.name kommer alltid att vara mod_name eller mod_name + '.__main__', aldrig run_name).

__file__, __cached__, __loader__ och __package__ är inställda som normala baserat på modulspecifikationen.

Om argumentet alter_sys anges och utvärderas till True, uppdateras sys.argv[0] med värdet för __file__ och sys.modules[__name__] uppdateras med ett temporärt modulobjekt för den modul som körs. Både sys.argv[0] och sys.modules[__name__] återställs till sina ursprungliga värden innan funktionen returneras.

Observera att denna manipulation av sys inte är trådsäker. Andra trådar kan se den delvis initialiserade modulen, liksom den ändrade listan med argument. Det rekommenderas att sys-modulen lämnas ifred när denna funktion anropas från trådad kod.

Se även

Alternativet -m erbjuder motsvarande funktionalitet från kommandoraden.

Ändrad i version 3.1: Lagt till möjligheten att exekvera paket genom att leta efter en __main__-undermodul.

Ändrad i version 3.2: Lagt till den globala variabeln __cached__ (se PEP 3147).

Ändrad i version 3.4: Uppdaterad för att dra nytta av modulspecifikationsfunktionen som lagts till av PEP 451. Detta gör att __cached__ kan ställas in korrekt för moduler som körs på detta sätt, samt att det verkliga modulnamnet alltid är tillgängligt som __spec__.name.

Ändrad i version 3.12: Inställningen av __cached__, __loader__ och __package__ är föråldrad. Se ModuleSpec för alternativ.

runpy.run_path(path_name, init_globals=None, run_name=None)

Exekvera koden på den angivna platsen i filsystemet och returnera den resulterande modulens globals-ordbok. Precis som med ett skriptnamn som anges på CPythons kommandorad kan file_path hänvisa till en Python-källfil, en kompilerad bytecode-fil eller en giltig sys.path-post som innehåller en __main__-modul (t.ex. en zip-fil som innehåller en __main__.py-fil på toppnivå).

För ett enkelt skript exekveras den angivna koden helt enkelt i ett nytt modulnamnrymd. För en giltig sys.path-post (vanligtvis en zip-fil eller katalog) läggs posten först till i början av sys.path. Funktionen söker sedan efter och exekverar en __main__-modul med den uppdaterade sökvägen. Observera att det inte finns något särskilt skydd mot att anropa en befintlig __main__-post som finns någon annanstans på sys.path om det inte finns någon sådan modul på den angivna platsen.

Det valfria ordboksargumentet init_globals kan användas för att fylla på modulens globala ordbok innan koden exekveras. init_globals kommer inte att modifieras. Om någon av de speciella globala variablerna nedan är definierade i init_globals, åsidosätts dessa definitioner av run_path().

De speciella globala variablerna __name__, __spec__, __file__, __cached__, __loader__ och __package__ sätts i globals-ordlistan innan modulkoden exekveras. (Observera att detta är en minimal uppsättning variabler - andra variabler kan ställas in implicit som en implementationsdetalj för tolken)

__name__ sätts till run_name om detta valfria argument inte är None och till '<run_path>' annars.

Om file_path direkt refererar till en skriptfil (antingen som källkod eller som förkompilerad bytekod), kommer __file__ att sättas till file_path, och __spec__, __cached__, __loader__ och __package__ kommer alla att sättas till None.

Om file_path är en referens till en giltig sys.path-post kommer __spec__ att ställas in på lämpligt sätt för den importerade __main__-modulen (det vill säga __spec__.name kommer alltid att vara __main__). __file__, __cached__, __loader__ och package__ kommer att ställas in som vanligt baserat på modulspecifikationen.

Ett antal ändringar görs också i modulen sys. För det första kan sys.path ändras enligt beskrivningen ovan. sys.argv[0] uppdateras med värdet för file_path och sys.modules[__name__] uppdateras med ett temporärt modulobjekt för den modul som exekveras. Alla ändringar av objekt i sys återställs innan funktionen returneras.

Observera att till skillnad från run_module() är ändringarna i sys inte valfria i denna funktion eftersom dessa justeringar är nödvändiga för att möjliggöra exekvering av sys.path-poster. Eftersom begränsningarna för trådsäkerhet fortfarande gäller, bör användning av denna funktion i trådad kod antingen serialiseras med importlåset eller delegeras till en separat process.

Se även

Alternativ för gränssnitt för motsvarande funktionalitet på kommandoraden (python path/to/script).

Tillagd i version 3.2.

Ändrad i version 3.4: Uppdaterad för att dra nytta av funktionen modulspecifikation som lagts till av PEP 451. Detta gör att __cached__ kan ställas in korrekt i de fall där __main__ importeras från en giltig sys.path-post istället för att exekveras direkt.

Ändrad i version 3.12: Inställningen av __cached__, __loader__ och __package__ är föråldrad.

Se även

PEP 338 – Exekvera moduler som skript

PEP skrivet och genomfört av Nick Coghlan.

PEP 366 – Huvudmodulens explicita relativa import

PEP skrivet och genomfört av Nick Coghlan.

PEP 451 – En ModuleSpec-typ för importsystemet

PEP skrivet och implementerat av Eric Snow

Kommandorad och miljö - CPython-kommandoradsdetaljer

Funktionen importlib.import_module()