entrypoints 0.4¶
This package is in maintenance-only mode. New code should use the importlib.metadata module in the Python standard library to find and load entry points.
Entry points are a way for Python packages to advertise objects with some
common interface. The most common examples are console_scripts
entry points,
which define shell commands by identifying a Python function to run.
Groups of entry points, such as console_scripts
, point to objects with
similar interfaces. An application might use a group to find its plugins, or
multiple groups if it has different kinds of plugins.
The entrypoints module contains functions to find and load entry points.
You can install it from PyPI with pip install entrypoints
.
To advertise entry points when distributing a package, see entry_points in the Python Packaging User Guide.
The pkg_resources
module distributed with setuptools
provides a way to
discover entrypoints as well, but it contains other functionality unrelated to
entrypoint discovery, and it does a lot of work at import time. Merely
importing pkg_resources
causes it to scan the files of all installed
packages. Thus, in environments where a large number of packages are installed,
importing pkg_resources
can be very slow (several seconds).
By contrast, entrypoints
is focused solely on entrypoint discovery and it
is faster. Importing entrypoints
does not scan anything, and getting a
given entrypoint group performs a more focused scan.
When there are multiple versions of the same distribution in different
directories on sys.path
, entrypoints
follows the rule that the first
one wins. In most cases, this follows the logic of imports. Similarly,
Entrypoints relies on pip
to ensure that only one .dist-info
or
.egg-info
directory exists for each installed package. There is no reliable
way to pick which of several .dist-info folders accurately relates to the
importable modules.
Contents:
entrypoints API¶
High-level API¶
-
entrypoints.
get_single
(group, name, path=None)¶ Find a single entry point.
Returns an
EntryPoint
object, or raisesNoSuchEntryPoint
if no match is found.
-
entrypoints.
get_group_named
(group, path=None)¶ Find a group of entry points with unique names.
Returns a dictionary of names to
EntryPoint
objects.
-
entrypoints.
get_group_all
(group, path=None)¶ Find all entry points in a group.
Returns a list of
EntryPoint
objects.
These functions will all use sys.path
by default if you don’t specify the
path parameter. This is normally what you want, so you shouldn’t need to
pass path.
EntryPoint objects¶
-
class
entrypoints.
EntryPoint
(name, module_name, object_name, extras=None, distro=None)¶ -
name
¶ The name identifying this entry point
-
module_name
¶ The name of an importable module to which it refers
-
object_name
¶ The dotted object name within the module, or None if the entry point refers to a module itself.
-
extras
¶ Extra setuptools features related to this entry point as a list, or None
-
distro
¶ The distribution which advertised this entry point - a
Distribution
instance or None
-
load
()¶ Load the object to which this entry point refers.
-
classmethod
from_string
(epstr, name, distro=None)¶ Parse an entry point from the syntax in entry_points.txt
Parameters: - epstr (str) – The entry point string (not including ‘name =’)
- name (str) – The name of this entry point
- distro (Distribution) – The distribution in which the entry point was found
Return type: Raises: BadEntryPoint – if epstr can’t be parsed as an entry point.
-
Exceptions¶
-
exception
entrypoints.
BadEntryPoint
(epstr)¶ Raised when an entry point can’t be parsed.
-
exception
entrypoints.
NoSuchEntryPoint
(group, name)¶ Raised by
get_single()
when no matching entry point is found.