pkgutil — Verktyg för pakettillägg

Källkod: Lib/pkgutil.py


Denna modul innehåller verktyg för importsystemet, i synnerhet paketstöd.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

En namntuple som innehåller en kort sammanfattning av en moduls information.

Tillagd i version 3.6.

pkgutil.extend_path(path, name)

Utöka sökvägen för de moduler som ingår i ett paket. Avsedd användning är att placera följande kod i ett pakets __init__.py:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

För varje katalog i sys.path som har en underkatalog som matchar paketnamnet, lägg till underkatalogen i paketets __path__. Detta är användbart om man vill distribuera olika delar av ett enda logiskt paket som flera kataloger.

Den letar också efter *.pkg-filer som börjar där * matchar argumentet name. Den här funktionen liknar *.pth-filer (se modulen site för mer information), förutom att den inte specialklassar rader som börjar med import. En *.pkg-fil tolkas som den är: förutom att tomma rader hoppas över och kommentarer ignoreras, läggs alla poster som finns i en *.pkg-fil till i sökvägen, oavsett om de finns i filsystemet eller inte (detta är en funktion).

Om indatasökvägen inte är en lista (vilket är fallet för frysta paket) returneras den oförändrad. Inmatningsvägen ändras inte; en utökad kopia returneras. Objekten läggs bara till i kopian i slutet.

Det antas att sys.path är en sekvens. Element i sys.path som inte är strängar som hänvisar till befintliga kataloger ignoreras. Unicode-objekt i sys.path som orsakar fel när de används som filnamn kan leda till att denna funktion ger upphov till ett undantag (i linje med os.path.isdir()-beteendet).

pkgutil.get_importer(path_item)

Hämta en finder för den angivna path_item.

Den returnerade sökaren cachelagras i sys.path_importer_cache om den nyligen skapades av en sökvägs-hook.

Cachen (eller en del av den) kan tömmas manuellt om en ny sökning av sys.path_hooks är nödvändig.

Ändrad i version 3.3: Uppdaterad för att baseras direkt på importlib snarare än att förlita sig på paketets interna PEP 302 import-emulering.

pkgutil.iter_importers(fullname='')

Ger finder-objekt för det angivna modulnamnet.

Om fullname innehåller en '.' kommer sökarna att vara för paketet som innehåller fullname, annars kommer de att vara alla registrerade sökare på högsta nivån (dvs. de på både sys.meta_path och sys.path_hooks).

Om den namngivna modulen ingår i ett paket importeras paketet som en bieffekt av att funktionen anropas.

Om inget modulnamn anges produceras alla sökare på högsta nivån.

Ändrad i version 3.3: Uppdaterad för att baseras direkt på importlib snarare än att förlita sig på paketets interna PEP 302 import-emulering.

pkgutil.iter_modules(path=None, prefix='')

Ger ModuleInfo för alla undermoduler på path, eller, om path är None, alla moduler på högsta nivån på sys.path.

path ska vara antingen None eller en lista med sökvägar där moduler ska sökas.

prefix är en sträng som ska skrivas ut i början av varje modulnamn vid utmatning.

Anteckning

Fungerar endast för en finder som definierar en metod iter_modules(). Detta gränssnitt är inte standard, så modulen tillhandahåller även implementeringar för importlib.machinery.FileFinder och zipimport.zipimporter.

Ändrad i version 3.3: Uppdaterad för att baseras direkt på importlib snarare än att förlita sig på paketets interna PEP 302 import-emulering.

pkgutil.walk_packages(path=None, prefix='', onerror=None)

Ger ModuleInfo för alla moduler rekursivt på path, eller, om path är None, alla tillgängliga moduler.

path ska vara antingen None eller en lista med sökvägar där moduler ska sökas.

prefix är en sträng som ska skrivas ut i början av varje modulnamn vid utmatning.

Observera att denna funktion måste importera alla paket (inte alla moduler!) på den angivna vägen för att kunna komma åt attributet __path__ och hitta undermoduler.

onerror är en funktion som anropas med ett argument (namnet på det paket som importerades) om något undantag inträffar när du försöker importera ett paket. Om ingen onerror-funktion tillhandahålls fångas och ignoreras ImportError, medan alla andra undantag sprids och avslutar sökningen.

Exempel:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Anteckning

Fungerar endast för en finder som definierar en metod iter_modules(). Detta gränssnitt är inte standard, så modulen tillhandahåller även implementeringar för importlib.machinery.FileFinder och zipimport.zipimporter.

Ändrad i version 3.3: Uppdaterad för att baseras direkt på importlib snarare än att förlita sig på paketets interna PEP 302 import-emulering.

pkgutil.get_data(package, resource)

Hämta en resurs från ett paket.

Detta är en omslagslösning för API:et loader get_data. Argumentet package ska vara namnet på ett paket, i standardmodulformat (foo.bar). Argumentet resource ska vara i form av ett relativt filnamn, med / som sökvägsavgränsare. Det överordnade katalognamnet .. är inte tillåtet, och inte heller ett rotat namn (som börjar med /).

Funktionen returnerar en binär sträng som är innehållet i den angivna resursen.

För paket som finns i filsystemet och som redan har importerats är detta den ungefärliga motsvarigheten till:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

Om paketet inte kan hittas eller laddas, eller om det använder en loader som inte stöder get_data, returneras None. I synnerhet har loader för namespace packages inte stöd för get_data.

pkgutil.resolve_name(name)

Återkopplar ett namn till ett objekt.

Denna funktionalitet används på många ställen i standardbiblioteket (se bpo-12915) - och motsvarande funktionalitet finns också i allmänt använda tredjepartspaket som setuptools, Django och Pyramid.

Det förväntas att namn är en sträng i något av följande format, där W är en kortform för en giltig Python-identifierare och punkt står för en bokstavlig punkt i dessa pseudo-regexer:

  • W(.W)*

  • W(.W)*:(W(.W)*)?

Den första formen är endast avsedd för bakåtkompatibilitet. Den förutsätter att en del av det prickade namnet är ett paket och att resten är ett objekt någonstans i paketet, eventuellt nästlat inuti andra objekt. Eftersom platsen där paketet slutar och objekthierarkin börjar inte kan utläsas genom inspektion, måste upprepade försök att importera göras med den här formen.

I det andra formuläret klargör den som ringer upp uppdelningen genom att använda ett enda kolon: det prickade namnet till vänster om kolon är ett paket som ska importeras och det prickade namnet till höger är objekthierarkin inom det paketet. Endast en import behövs i denna form. Om den slutar med ett kolon returneras ett modulobjekt.

Funktionen kommer att returnera ett objekt (som kan vara en modul) eller ge upphov till något av följande undantag:

ValueError – om namn inte är i ett erkänt format.

ImportError – om en import misslyckades när den inte borde ha gjort det.

AttributeError – Om ett fel uppstod när objekthierarkin i det importerade paketet genomkorsades för att komma till det önskade objektet.

Tillagd i version 3.9.