An "entry point" is typically a function (or other callable function-like object) that a developer or user of your Python package might want to use, though a non-callable object can be supplied as an entry point as well (as correctly pointed out in the comments!).
The most popular kind of entry point is the console_scripts entry point, which points to a function that you want made available as a command-line tool to whoever installs your package. This goes into your setup.py script like:
entry_points={
'console_scripts': [
'cursive = cursive.tools.cmd:cursive_command',
],
},
I have a package I've just deployed called cursive.tools, and I wanted it to make available a "cursive" command that someone could run from the command line, like:
$ cursive --help
usage: cursive ...
The way to do this is define a function, like maybe a cursive_command function in the file cursive/tools/cmd.py that looks like:
def cursive_command():
args = sys.argv[1:]
if len(args) < 1:
print "usage: ..."
and so forth; it should assume that it's been called from the command line, parse the arguments that the user has provided, and ... well, do whatever the command is designed to do.
Install the docutils package for a great example of entry-point use: it will install something like a half-dozen useful commands for converting Python documentation to other formats.
An "entry point" is typically a function (or other callable function-like object) that a developer or user of your Python package might want to use, though a non-callable object can be supplied as an entry point as well (as correctly pointed out in the comments!).
The most popular kind of entry point is the console_scripts entry point, which points to a function that you want made available as a command-line tool to whoever installs your package. This goes into your setup.py script like:
entry_points={
'console_scripts': [
'cursive = cursive.tools.cmd:cursive_command',
],
},
I have a package I've just deployed called cursive.tools, and I wanted it to make available a "cursive" command that someone could run from the command line, like:
$ cursive --help
usage: cursive ...
The way to do this is define a function, like maybe a cursive_command function in the file cursive/tools/cmd.py that looks like:
def cursive_command():
args = sys.argv[1:]
if len(args) < 1:
print "usage: ..."
and so forth; it should assume that it's been called from the command line, parse the arguments that the user has provided, and ... well, do whatever the command is designed to do.
Install the docutils package for a great example of entry-point use: it will install something like a half-dozen useful commands for converting Python documentation to other formats.
EntryPoints provide a persistent, filesystem-based object name registration and name-based direct object import mechanism (implemented by the setuptools package).
They associate names of Python objects with free-form identifiers. So any other code using the same Python installation and knowing the identifier can access an object with the associated name, no matter where the object is defined. The associated names can be any names existing in a Python module; for example name of a class, function or variable. The entry point mechanism does not care what the name refers to, as long as it is importable.
As an example, let's use (the name of) a function, and an imaginary python module with a fully-qualified name 'myns.mypkg.mymodule':
def the_function():
"function whose name is 'the_function', in 'mymodule' module"
print "hello from the_function"
Entry points are registered via an entry points declaration in setup.py. To register the_function under entrypoint called 'my_ep_func':
entry_points = {
'my_ep_group_id': [
'my_ep_func = myns.mypkg.mymodule:the_function'
]
},
As the example shows, entry points are grouped; there's corresponding API to look up all entry points belonging to a group (example below).
Upon a package installation (ie. running 'python setup.py install'), the above declaration is parsed by setuptools. It then writes the parsed information in special file. After that, the pkg_resources API (part of setuptools) can be used to look up the entry point and access the object(s) with the associated name(s):
import pkg_resources
named_objects = {}
for ep in pkg_resources.iter_entry_points(group='my_ep_group_id'):
named_objects.update({ep.name: ep.load()})
Here, setuptools read the entry point information that was written in special files. It found the entry point, imported the module (myns.mypkg.mymodule), and retrieved the_function defined there, upon call to pkg_resources.load().
Calling the_function would then be simple:
>>> named_objects'my_ep_func'
hello from the_function
Thus, while perhaps a bit difficult to grasp at first, the entry point mechanism is actually quite simple to use. It provides an useful tool for pluggable Python software development.
Instead of using the entry_points argument to setuptools.setup(), I'm as of recently supposed to put the file entry_points.txt into the .dist-info directory. But I don't understand how to do that because that directory gets automatically created during the package installation.
[EDIT]
I found that I have to make a [project.scripts] section in pyproject.toml, which upon installation creates the appropriate .dist-info/entry_points.txt. But it still doesn't install the actual callable command.
[EDIT 2]
I found that I made a totally stupid mistake and my executable ended up being named console_scripts. Please don't answer any more. I've downvoted my own OP.
I understand what entry points are, but I don't necessarily understand how they work. The only two entry point methods I know are, using the cli as an entry point and the if name = main to trigger the main function.
If you use a single function as an entry point, does that trigger a kind of snowball effect which causes def statements to start triggering one after another as they call each other?
How would an entry point work in automation? Say you have a package with a module made up of def statements to do some task. These are commands you can run manually in the cli, but you want to automate it. What would be used as the entry point? Just a helper.py with minimal lines to get the process going?
This might need to be its own question, but how would an entry point work for a flask or django web app? If everything is an object and everything is a def statement, what do web apps use for an entry point? Does each app just have it's own setup.py. But even still, if something is triggered by interaction on the website - how does an entry point work in that kind of situation?