Links
setup.cfg
filespyproject.toml
filespkg_resources
Project
setup()
Keywordsdependency_links
zip_safe
flagsetuptools
commandsEntry points are a type of metadata that can be exposed by packages on installation.They are a very useful feature of the Python ecosystem,and come specially handy in two scenarios:
1. The package would like to provide commands to be run at the terminal.This functionality is known asconsole scripts. The command may alsoopen up a GUI, in which case it is known as aGUI script. An exampleof a console script is the one provided by thepip package, whichallows you to run commands likepipinstall
in the terminal.
2. A package would like to enable customization of its functionalitiesviaplugins. For example, the test frameworkpytest allowscustomization via thepytest11
entry point, and the syntaxhighlighting toolpygments allows specifying additional stylesusing the entry pointpygments.styles
.
Let us start with console scripts.First consider an example without entry points. Imagine a packagedefined thus:
project_root_directory├── pyproject.toml # and/or setup.cfg, setup.py└── src └── timmins ├── __init__.py └── ...
with__init__.py
as:
defhello_world():print("Hello world")
Now, suppose that we would like to provide some way of executing thefunctionhello_world()
from the command-line. One way to do thisis to create a filesrc/timmins/__main__.py
providing a hook asfollows:
from.importhello_worldif__name__=='__main__':hello_world()
Then, after installing the packagetimmins
, we may invoke thehello_world()
function as follows, through therunpymodule:
$python-mtimminsHelloworld
Instead of this approach using__main__.py
, you can also create auser-friendly CLI executable that can be called directly withoutpython-m
.In the above example, to create a commandhello-world
that invokestimmins.hello_world
, add a console script entry point to yourconfiguration:
[project.scripts]hello-world="timmins:hello_world"
[options.entry_points]console_scripts=hello-world=timmins:hello_world
fromsetuptoolsimportsetupsetup(# ...,entry_points={'console_scripts':['hello-world = timmins:hello_world',]})
After installing the package, a user may invoke that function by simply callinghello-world
on the command line:
$hello-worldHelloworld
Note that any function used as a console script, i.e.hello_world()
inthis example, should not accept any arguments. If your function requires any inputfrom the user, you can use regular command-line argument parsing utilities likeargparse
within the body ofthe function to parse user input given viasys.argv
.
You may have noticed that we have used a special syntax to specify the functionthat must be invoked by the console script, i.e. we have writtentimmins:hello_world
with a colon:
separating the package name and the function name. The fullspecification of this syntax is discussed in thelast sectionof this document, and this can be used to specify a function located anywhere inyour package, not just in__init__.py
.
In addition toconsole_scripts
, Setuptools supportsgui_scripts
, whichwill launch a GUI application without running in a terminal window.
For example, if we have a project with the same directory structure as before,with an__init__.py
file containing the following:
importPySimpleGUIassgdefhello_world():sg.Window(title="Hello world",layout=[[]],margins=(100,50)).read()
Then, we can add a GUI script entry point:
[project.gui-scripts]hello-world="timmins:hello_world"
[options.entry_points]gui_scripts=hello-world=timmins:hello_world
fromsetuptoolsimportsetupsetup(# ...,entry_points={'gui_scripts':['hello-world = timmins:hello_world',]})
Note
To be able to importPySimpleGUI
, you need to addpysimplegui
to your package dependencies.SeeDependencies Management in Setuptools for more information.
Now, running:
$hello-world
will open a small application window with the title ‘Hello world’.
Note that just as with console scripts, any function used as a GUI scriptshould not accept any arguments, and any user input can be parsed within thebody of the function. GUI scripts also use the same syntax (discussed in thelast section) for specifying the function to be invoked.
Note
The difference betweenconsole_scripts
andgui_scripts
only affectsWindows systems.[1]console_scripts
are wrapped in a consoleexecutable, so they are attached to a console and can usesys.stdin
,sys.stdout
andsys.stderr
for input and output.gui_scripts
arewrapped in a GUI executable, so they can be started without a console, butcannot use standard streams unless application code redirects them. Otherplatforms do not have the same distinction.
Note
Console and GUI scripts work because behind the scenes, installers likepipcreate wrapper scripts around the function(s) being invoked. For example,thehello-world
entry point in the above two examples would create acommandhello-world
launching a script like this:[1]
importsysfromtimminsimporthello_worldsys.exit(hello_world())
Console/GUI scripts are one use of the more general concept of entry points. Entrypoints more generally allow a packager to advertise behavior for discovery byother libraries and applications. This feature enables “plug-in”-likefunctionality, where one library solicits entry points and any number of otherlibraries provide those entry points.
A good example of this plug-in behavior can be seen inpytest plugins,where pytest is a test framework that allows other libraries to extendor modify its functionality through thepytest11
entry point.
The console/GUI scripts work similarly, where libraries advertise their commandsand tools likepip
create wrapper scripts that invoke those commands.
Let us consider a simple example to understand how we can implement entry pointscorresponding to plugins. Say we have a packagetimmins
with the followingdirectory structure:
timmins├── pyproject.toml # and/or setup.cfg, setup.py└── src └── timmins └── __init__.py
and insrc/timmins/__init__.py
we have the following code:
defhello_world():print('Hello world')
Basically, we have defined ahello_world()
function which will print the text‘Hello world’. Now, let us say we want to print the text ‘Hello world’ in differentways. The current function just prints the text as it is - let us say we want anotherstyle in which the text is enclosed within exclamation marks:
!!! Hello world !!!
Let us see how this can be done using plugins. First, let us separate the style ofprinting the text from the text itself. In other words, we can change the code insrc/timmins/__init__.py
to something like this:
defdisplay(text):print(text)defhello_world():display('Hello world')
Here, thedisplay()
function controls the style of printing the text, and thehello_world()
function calls thedisplay()
function to print the text ‘Helloworld`.
Right now thedisplay()
function just prints the text as it is. In order to be ableto customize it, we can do the following. Let us introduce a newgroup of entry pointsnamedtimmins.display
, and expect plugin packages implementing this entry pointto supply adisplay()
-like function. Next, to be able to automatically discover pluginpackages that implement this entry point, we can use theimportlib.metadata
module,as follows:
fromimportlib.metadataimportentry_pointsdisplay_eps=entry_points(group='timmins.display')
Note
Eachimportlib.metadata.EntryPoint
object is an object containing aname
, agroup
, and avalue
. For example, after setting up the plugin package asdescribed below,display_eps
in the above code will look like this:[2]
(EntryPoint(name='excl',value='timmins_plugin_fancy:excl_display',group='timmins.display'),...,)
display_eps
will now be a list ofEntryPoint
objects, each referring todisplay()
-likefunctions defined by one or more installed plugin packages. Then, to import a specificdisplay()
-like function - let us choose the one corresponding to the first discoveredentry point - we can use theload()
method as follows:
display=display_eps[0].load()
Finally, a sensible behaviour would be that if we cannot find any plugin packages customizingthedisplay()
function, we should fall back to our default implementation which printsthe text as it is. With this behaviour included, the code insrc/timmins/__init__.py
finally becomes:
fromimportlib.metadataimportentry_pointsdisplay_eps=entry_points(group='timmins.display')try:display=display_eps[0].load()exceptIndexError:defdisplay(text):print(text)defhello_world():display('Hello world')
That finishes the setup ontimmins
’s side. Next, we need to implement a pluginwhich implements the entry pointtimmins.display
. Let us name this plugintimmins-plugin-fancy
, and set it up with the following directory structure:
timmins-plugin-fancy├── pyproject.toml # and/or setup.cfg, setup.py└── src └── timmins_plugin_fancy └── __init__.py
And then, insidesrc/timmins_plugin_fancy/__init__.py
, we can put a functionnamedexcl_display()
that prints the given text surrounded by exclamation marks:
defexcl_display(text):print('!!!',text,'!!!')
This is thedisplay()
-like function that we are looking to supply to thetimmins
package. We can do that by adding the following in the configurationoftimmins-plugin-fancy
:
# Note the quotes around timmins.display in order to escape the dot .[project.entry-points."timmins.display"]excl="timmins_plugin_fancy:excl_display"
[options.entry_points]timmins.display=excl=timmins_plugin_fancy:excl_display
fromsetuptoolsimportsetupsetup(# ...,entry_points={'timmins.display':['excl = timmins_plugin_fancy:excl_display']})
Basically, this configuration states that we are a supplying an entry pointunder the grouptimmins.display
. The entry point is namedexcl
and itrefers to the functionexcl_display
defined by the packagetimmins-plugin-fancy
.
Now, if we install bothtimmins
andtimmins-plugin-fancy
, we should getthe following:
>>>fromtimminsimporthello_world>>>hello_world()!!! Hello world !!!
whereas if we only installtimmins
and nottimmins-plugin-fancy
, we shouldget the following:
>>>fromtimminsimporthello_world>>>hello_world()Hello world
Therefore, our plugin works.
Our plugin could have also defined multiple entry points under the grouptimmins.display
.For example, insrc/timmins_plugin_fancy/__init__.py
we could have twodisplay()
-likefunctions, as follows:
defexcl_display(text):print('!!!',text,'!!!')deflined_display(text):print(''.join(['-'for_intext]))print(text)print(''.join(['-'for_intext]))
The configuration oftimmins-plugin-fancy
would then change to:
[project.entry-points."timmins.display"]excl="timmins_plugin_fancy:excl_display"lined="timmins_plugin_fancy:lined_display"
[options.entry_points]timmins.display=excl=timmins_plugin_fancy:excl_displaylined=timmins_plugin_fancy:lined_display
fromsetuptoolsimportsetupsetup(# ...,entry_points={'timmins.display':['excl = timmins_plugin_fancy:excl_display','lined = timmins_plugin_fancy:lined_display',]})
On thetimmins
side, we can also use a different strategy of loading entrypoints. For example, we can search for a specific display style:
display_eps=entry_points(group='timmins.display')try:display=display_eps['lined'].load()exceptKeyError:# if the 'lined' display is not available, use something else...
Or we can also load all plugins under the given group. Though this might notbe of much use in our current example, there are several scenarios in which thisis useful:
display_eps=entry_points(group='timmins.display')forepindisplay_eps:display=ep.load()# do something with display...
Another point is that in this particular example, we have used plugins tocustomize the behaviour of a function (display()
). In general, we can use entrypoints to enable plugins to not only customize the behaviour of functions, but alsoof entire classes and modules. This is unlike the case of console/GUI scripts,where entry points can only refer to functions. The syntax used for specifying theentry points remains the same as for console/GUI scripts, and is discussed in thelast section.
Tip
The recommended approach for loading and importing entry points is theimportlib.metadata
module,which is a part of the standard library since Python 3.8 and is non-provisionalsince Python 3.10. For older versions of Python, its backportimportlib_metadata should be used. While using the backport, the onlychange that has to be made is to replaceimportlib.metadata
withimportlib_metadata
, i.e.
fromimportlib_metadataimportentry_points...
In summary, entry points allow a package to open its functionalities forcustomization via plugins.The package soliciting the entry points need not have any dependencyor prior knowledge about the plugins implementing the entry points, anddownstream users are able to compose functionality by pulling togetherplugins implementing the entry points.
The syntax for entry points is specified as follows:
<name>=<package_or_module>[:<object>[.<attr>[.<nested-attr>]*]]
Here, the square brackets[]
denote optionality and the asterisk*
denotes repetition.name
is the name of the script/entry point you want to create, the left handside of:
is the package or module that contains the object you want to invoke(think about it as something you would write in an import statement), and the righthand side is the object you want to invoke (e.g. a function).
To make this syntax more clear, consider the following examples:
If you supply:
<name>=<package_or_module>
as the entry point, where<package_or_module>
can contain.
in the caseof sub-modules or sub-packages, then, tools in the Python ecosystem will roughlyinterpret this value as:
import<package_or_module>parsed_value=<package_or_module>
If you supply:
<name>=<package_or_module>:<object>
where<object>
does not contain any.
, this will be roughly interpretedas:
from<package_or_module>import<object>parsed_value=<object>
If you supply:
<name>=<package_or_module>:<object>.<attr>.<nested_attr>
this will be roughly interpreted as:
from<package_or_module>import<object>parsed_value=<object>.<attr>.<nested_attr>
In the case of console/GUI scripts, this syntax can be used to specify a function, whilein the general case of entry points as used for plugins, it can be used to specify a function,class or module.
Reference:https://packaging.python.org/en/latest/specifications/entry-points/#use-for-scripts
[2]