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 modulensite
för mer information), förutom att den inte specialklassar rader som börjar medimport
. 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 isys.path
som inte är strängar som hänvisar till befintliga kataloger ignoreras. Unicode-objekt isys.path
som orsakar fel när de används som filnamn kan leda till att denna funktion ger upphov till ett undantag (i linje medos.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.
- 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ådesys.meta_path
ochsys.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.
- pkgutil.iter_modules(path=None, prefix='')¶
Ger
ModuleInfo
för alla undermoduler på path, eller, om path ärNone
, 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örimportlib.machinery.FileFinder
ochzipimport.zipimporter
.
- pkgutil.walk_packages(path=None, prefix='', onerror=None)¶
Ger
ModuleInfo
för alla moduler rekursivt på path, eller, om path ärNone
, 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örimportlib.machinery.FileFinder
ochzipimport.zipimporter
.
- 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
, returnerasNone
. I synnerhet har loader för namespace packages inte stöd förget_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.