Entry points¶

importlib.metadata.entry_points(**select_params)¶

Returns aEntryPoints instance describing entry points for thecurrent environment. Any given keyword parameters are passed to theselect() method for comparison to the attributes ofthe individual entry point definitions.

Note: it is not currently possible to query for entry points based ontheirEntryPoint.dist attribute (as differentDistributioninstances do not currently compare equal, even if they have the same attributes)

classimportlib.metadata.EntryPoints¶

Details of a collection of installed entry points.

Also provides a.groups attribute that reports all identified entrypoint groups, and a.names attribute that reports all identified entrypoint names.

classimportlib.metadata.EntryPoint¶

Details of an installed entry point.

EachEntryPoint instance has.name,.group, and.valueattributes and a.load() method to resolve the value. There are also.module,.attr, and.extras attributes for getting thecomponents of the.value attribute, and.dist for obtaininginformation regarding the distribution package that provides the entry point.

Query all entry points:

>>>eps=entry_points()

Theentry_points() function returns aEntryPoints object,a collection of allEntryPoint objects withnames andgroupsattributes for convenience:

>>>sorted(eps.groups)['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']

EntryPoints has aselect() method to select entry pointsmatching specific properties. Select entry points in theconsole_scripts group:

>>>scripts=eps.select(group='console_scripts')

Equivalently, sinceentry_points() passes keyword argumentsthrough to select:

>>>scripts=entry_points(group='console_scripts')

Pick out a specific script named "wheel" (found in the wheel project):

>>>'wheel'inscripts.namesTrue>>>wheel=scripts['wheel']

Equivalently, query for that entry point during selection:

>>>(wheel,)=entry_points(group='console_scripts',name='wheel')>>>(wheel,)=entry_points().select(group='console_scripts',name='wheel')

Inspect the resolved entry point:

>>>wheelEntryPoint(name='wheel', value='wheel.cli:main', group='console_scripts')>>>wheel.module'wheel.cli'>>>wheel.attr'main'>>>wheel.extras[]>>>main=wheel.load()>>>main<function main at 0x103528488>

Thegroup andname are arbitrary values defined by the package authorand usually a client will wish to resolve all entry points for a particulargroup. Readthe setuptools docsfor more information on entry points, their definition, and usage.

Distribution metadata¶

importlib.metadata.metadata(distribution_name)¶

Return the distribution metadata corresponding to the nameddistribution package as aPackageMetadata instance.

RaisesPackageNotFoundError if the named distributionpackage is not installed in the current Python environment.

classimportlib.metadata.PackageMetadata¶

A concrete implementation of thePackageMetadata protocol.

In addition to providing the defined protocol methods and attributes, subscriptingthe instance is equivalent to calling theget() method.

EveryDistribution Packageincludes some metadata, which you can extract using themetadata() function:

>>>wheel_metadata=metadata('wheel')

The keys of the returned data structure name the metadata keywords, andthe values are returned unparsed from the distribution metadata:

>>>wheel_metadata['Requires-Python']'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

PackageMetadata also presents ajson attribute that returnsall the metadata in a JSON-compatible form perPEP 566:

>>>wheel_metadata.json['requires_python']'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'

The full set of available metadata is not described here.See the PyPACore metadata specification for additional details.

Distribution versions¶

importlib.metadata.version(distribution_name)¶

Return the installed distribution packageversionfor the named distribution package.

RaisesPackageNotFoundError if the named distributionpackage is not installed in the current Python environment.

Theversion() function is the quickest way to get aDistribution Package's versionnumber, as a string:

>>>version('wheel')'0.32.3'

Distribution files¶

importlib.metadata.files(distribution_name)¶

Return the full set of files contained within the nameddistribution package.

RaisesPackageNotFoundError if the named distributionpackage is not installed in the current Python environment.

ReturnsNone if the distribution is found but the installationdatabase records reporting the files associated with the distribuion packageare missing.

classimportlib.metadata.PackagePath¶

Apathlib.PurePath derived object with additionaldist,size, andhash properties corresponding to the distributionpackage's installation metadata for that file.

Thefiles() function takes aDistribution Packagename and returns all of the files installed by this distribution. Each file is reportedas aPackagePath instance. For example:

>>>util=[pforpinfiles('wheel')if'util.py'instr(p)][0]>>>utilPackagePath('wheel/util.py')>>>util.size859>>>util.dist<importlib.metadata._hooks.PathDistribution object at 0x101e0cef0>>>>util.hash<FileHash mode: sha256 value: bYkw5oMccfazVCoYQwKkkemoVyMAFoR34mmKBx8R1NI>

Once you have the file, you can also read its contents:

>>>print(util.read_text())import base64import sys...def as_bytes(s):    if isinstance(s, text_type):        return s.encode('utf-8')    return s

You can also use thelocate() method to get the absolutepath to the file:

>>>util.locate()PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')

In the case where the metadata file listing files(RECORD orSOURCES.txt) is missing,files() willreturnNone. The caller may wish to wrap calls tofiles() inalways_iterableor otherwise guard against this condition if the targetdistribution is not known to have the metadata present.

Distribution requirements¶

importlib.metadata.requires(distribution_name)¶

Return the declared dependency specifiers for the nameddistribution package.

RaisesPackageNotFoundError if the named distributionpackage is not installed in the current Python environment.

To get the full set of requirements for aDistribution Package,use therequires()function:

>>>requires('wheel')["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]

Mapping import to distribution packages¶

importlib.metadata.packages_distributions()¶

Return a mapping from the top level module and import packagenames found viasys.meta_path to the names of the distributionpackages (if any) that provide the corresponding files.

To allow for namespace packages (which may have members provided bymultiple distribution packages), each top level import name maps to alist of distribution names rather than mapping directly to a single name.

A convenience method to resolve theDistribution Packagename (or names, in the case of a namespace package)that provide each importable top-levelPython module orImport Package:

>>>packages_distributions(){'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}

Some editable installs,do not supply top-level names, and thus thisfunction is not reliable with such installs.

Example¶

Consider for example a custom finder that loads Pythonmodules from a database:

classDatabaseImporter(importlib.abc.MetaPathFinder):def__init__(self,db):self.db=dbdeffind_spec(self,fullname,target=None)->ModuleSpec:returnself.db.spec_from_name(fullname)sys.meta_path.append(DatabaseImporter(connect_db(...)))

That importer now presumably provides importable modules from adatabase, but it provides no metadata or entry points. For thiscustom importer to provide metadata, it would also need to implementDistributionFinder:

fromimportlib.metadataimportDistributionFinderclassDatabaseImporter(DistributionFinder):...deffind_distributions(self,context=DistributionFinder.Context()):query=dict(name=context.name)ifcontext.nameelse{}fordist_recordinself.db.query_distributions(query):yieldDatabaseDistribution(dist_record)

In this way,query_distributions would return records foreach distribution served by the database matching the query. Forexample, ifrequests-1.0 is in the database,find_distributionswould yield aDatabaseDistribution forContext(name='requests')orContext(name=None).

For the sake of simplicity, this example ignorescontext.path. Thepath attribute defaults tosys.path and is the set of import paths tobe considered in the search. ADatabaseImporter could potentially functionwithout any concern for a search path. Assuming the importer does nopartitioning, the "path" would be irrelevant. In order to illustrate thepurpose ofpath, the example would need to illustrate a more complexDatabaseImporter whose behavior varied depending onsys.path/PYTHONPATH. In that case, thefind_distributions shouldhonor thecontext.path and only yieldDistributions pertinent to thatpath.

DatabaseDistribution, then, would look something like:

classDatabaseDistribution(importlib.metadata.Distribution):def__init__(self,record):self.record=recorddefread_text(self,filename):"""        Read a file like "METADATA" for the current distribution.        """iffilename=="METADATA":returnf"""Name:{self.record.name}Version:{self.record.version}"""iffilename=="entry_points.txt":return"\n".join(f"""[{ep.group}]\n{ep.name}={ep.value}"""forepinself.record.entry_points)deflocate_file(self,path):raiseRuntimeError("This distribution has no file system")

This basic implementation should provide metadata and entry points forpackages served by theDatabaseImporter, assuming that therecord supplies suitable.name,.version, and.entry_points attributes.

TheDatabaseDistribution may also provide other metadata files, likeRECORD (required forDistribution.files) or override theimplementation ofDistribution.files. See the source for more inspiration.