importlib.resources – Läsning, öppning och åtkomst av paketresurser

Källkod: Lib/importlib/resources/__init__.py

Tillagd i version 3.7.

Denna modul utnyttjar Pythons importsystem för att ge tillgång till resurser inom paket.

”Resurser” är filliknande resurser som är associerade med en modul eller ett paket i Python. Resurserna kan finnas direkt i ett paket, i en underkatalog som ingår i paketet eller i anslutning till moduler utanför paketet. Resurserna kan vara text eller binära. Som ett resultat är Python-modulkällor (.py) för ett paket och kompileringsartefakter (pycache) tekniskt de facto-resurser för det paketet. I praktiken är dock resurser främst de artefakter som inte är Python-artefakter och som exponeras specifikt av paketets författare.

Resurser kan öppnas eller läsas i antingen binärt eller textläge.

Resurser är ungefär som filer i kataloger, men det är viktigt att komma ihåg att detta bara är en metafor. Resurser och paket behöver inte existera som fysiska filer och kataloger i filsystemet: ett paket och dess resurser kan till exempel importeras från en zip-fil med zipimport.

Anteckning

Den här modulen tillhandahåller funktionalitet som liknar pkg_resources Basic Resource Access utan prestandakostnaderna för det paketet. Detta gör det enklare att läsa resurser som ingår i paket, med en stabilare och mer konsekvent semantik.

I den fristående bakrapporten för den här modulen finns mer information om använda importlib.resources och flytta från pkg_resources till importlib.resources.

Loaders som vill stödja resursläsning bör implementera en get_resource_reader(fullname)-metod som specificeras av importlib.resources.abc.ResourceReader.

class importlib.resources.Anchor

Representerar ett ankare för resurser, antingen en modulobjekt eller ett modulnamn som en sträng. Definierad som Union[str, ModuleType].

importlib.resources.files(anchor: Anchor | None = None)

Returnerar ett Traversable-objekt som representerar resursbehållaren (tänk katalog) och dess resurser (tänk filer). En Traversable kan innehålla andra behållare (tänk underkataloger).

anchor är en valfri Anchor. Om ankaret är ett paket, löses resurser från det paketet. Om det är en modul löses resurserna i anslutning till den modulen (i samma paket eller i paketroten). Om ankaret utelämnas används den anropande modulen.

Tillagd i version 3.9.

Ändrad i version 3.12: package-parametern har bytt namn till anchor. anchor kan nu vara en icke-paketmodul och om den utelämnas kommer den att standardiseras till den anropande modulen. package accepteras fortfarande av kompatibilitetsskäl men kommer att ge upphov till en DeprecationWarning. Överväg att skicka ankaret positionellt eller använd importlib_resources >= 5.10 för ett kompatibelt gränssnitt på äldre Pythons.

importlib.resources.as_file(traversable)

Givet ett Traversable-objekt som representerar en fil eller katalog, typiskt från importlib.resources.files(), returnera en kontexthanterare för användning i en with-sats. Kontexthanteraren tillhandahåller ett pathlib.Path-objekt.

När du avslutar kontexthanteraren rensas alla temporära filer eller kataloger som skapades när resursen extraherades från t.ex. en zip-fil.

Använd as_file när Traversable-metoderna (read_text, etc) inte räcker till och en faktisk fil eller katalog i filsystemet krävs.

Tillagd i version 3.9.

Ändrad i version 3.12: Lagt till stöd för traversable som representerar en katalog.

Funktionellt API

En uppsättning förenklade, bakåtkompatibla hjälpfunktioner finns tillgängliga. Dessa tillåter vanliga operationer i ett enda funktionsanrop.

För alla följande funktioner:

  • anchor är en Anchor, som i files(). Till skillnad från i files kan det inte utelämnas.

  • path_names är komponenter i en resurs sökvägsnamn, i förhållande till ankaret. Om du t.ex. vill få fram texten i en resurs med namnet info.txt använder du:

    importlib.resources.read_text(min_modul, "info.txt")

    Som Traversable.joinpath, De enskilda komponenterna bör använda snedstreck (/) som sökvägsavgränsare. Till exempel är följande likvärdigt:

    importlib.resources.read_binary(my_module, "pics/painting.png")
importlib.resources.read_binary(my_module, "pics", "painting.png")

    Av bakåtkompatibilitetsskäl kräver funktioner som läser text ett explicit encoding-argument om flera path_names anges. Om du till exempel vill hämta texten i info/chapter1.txt använder du:

    importlib.resources.read_text(min_modul, "info", "chapter1.txt",
                              kodning='utf-8')
importlib.resources.open_binary(anchor, *path_names)

Öppna den namngivna resursen för binär läsning.

Se inledningen för detaljer om anchor och path_names.

Denna funktion returnerar ett BinaryIO-objekt, det vill säga en binär ström som är öppen för läsning.

Denna funktion är ungefär likvärdig med:

files(anchor).joinpath(*path_names).open('rb')

Ändrad i version 3.13: Flera väg_namn accepteras.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

Öppna den angivna resursen för textläsning. Som standard läses innehållet som strikt UTF-8.

Se introduktionen för detaljer om anchor och path_names. encoding och errors har samma betydelse som i inbyggda open().

Av bakåtkompatibilitetsskäl måste argumentet encoding anges explicit om det finns flera path_names. Denna begränsning kommer enligt planerna att tas bort i Python 3.15.

Denna funktion returnerar ett TextIO-objekt, det vill säga en textström som är öppen för läsning.

Denna funktion är ungefär likvärdig med:

files(anchor).joinpath(*path_names).open('r', encoding=kodning)

Ändrad i version 3.13: Flera path_names accepteras. encoding och errors måste anges som nyckelordsargument.

importlib.resources.read_binary(anchor, *path_names)

Läser och returnerar innehållet i den angivna resursen som bytes.

Se inledningen för detaljer om anchor och path_names.

Denna funktion är ungefär likvärdig med:

files(anchor).joinpath(*path_names).read_bytes()

Ändrad i version 3.13: Flera väg_namn accepteras.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

Läser och returnerar innehållet i den angivna resursen som str. Som standard läses innehållet som strikt UTF-8.

Se introduktionen för detaljer om anchor och path_names. encoding och errors har samma betydelse som i inbyggda open().

Av bakåtkompatibilitetsskäl måste argumentet encoding anges explicit om det finns flera path_names. Denna begränsning kommer enligt planerna att tas bort i Python 3.15.

Denna funktion är ungefär likvärdig med:

files(anchor).joinpath(*path_names).read_text(encoding=kodning)

Ändrad i version 3.13: Flera path_names accepteras. encoding och errors måste anges som nyckelordsargument.

importlib.resources.path(anchor, *path_names)

Ger sökvägen till resursen som en faktisk filsystemssökväg. Denna funktion returnerar en kontexthanterare för användning i en with-sats. Kontexthanteraren tillhandahåller ett pathlib.Path-objekt.

När du avslutar kontexthanteraren rensas eventuella temporära filer som skapats, t.ex. när resursen måste extraheras från en zip-fil.

Exempelvis kräver metoden stat() en faktisk sökväg till filsystemet; den kan användas så här:

med importlib.resources.path(anchor, "resource.txt") som fspath:
    resultat = fspath.stat()

Se inledningen för detaljer om anchor och path_names.

Denna funktion är ungefär likvärdig med:

as_file(files(anchor).joinpath(*path_names))

Ändrad i version 3.13: Flera path_names accepteras. encoding och errors måste anges som nyckelordsargument.

importlib.resources.is_resource(anchor, *path_names)

Returnerar True om den namngivna resursen finns, annars False. Denna funktion betraktar inte kataloger som resurser.

Se inledningen för detaljer om anchor och path_names.

Denna funktion är ungefär likvärdig med:

files(anchor).joinpath(*path_names).is_file()

Ändrad i version 3.13: Flera väg_namn accepteras.

importlib.resources.contents(anchor, *path_names)

Returnerar en iterabel över de namngivna objekten i paketet eller sökvägen. Iterabeln returnerar namn på resurser (t.ex. filer) och icke-resurser (t.ex. kataloger) som str. Iterabeln rekurserar inte i underkataloger.

Se inledningen för detaljer om anchor och path_names.

Denna funktion är ungefär likvärdig med:

för resurs i files(anchor).joinpath(*path_names).iterdir():
    ger resurs.namn

Föråldrad sedan version 3.11: Föredrar iterdir() som ovan, vilket ger mer kontroll över resultaten och rikare funktionalitet.