Explain Python Entry Points

Explain Python entry points?

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.

Is it possible to define a hierarchy to python entry points?

Yes. Just wrote single entry point that would act as a dispatcher.

import argparse

parser = argparse.ArgumentParser()

parser.add_argument('cmd', default='help',
    choices=['help', 'do-good', 'do-evil'],
    help='Command to execute')

args = parser.parse_args()
cmd = args.cmd;

print(f"Your choice is {cmd}")

Works like this:

$ python cmd.py
usage: cmd.py [-h] {help,do-good,do-evil}
cmd.py: error: the following arguments are required: cmd
$ python cmd.py xyz
usage: cmd.py [-h] {help,do-good,do-evil}
cmd.py: error: argument cmd: invalid choice: 'xyz' (choose from 'help', 'do-good', 'do-evil')
$ python cmd.py do-good
Your choice is do-good

You can use argparse's subcommands for this as well: https://docs.python.org/3/library/argparse.html#sub-commands

Running entry point console_script in python development environment

As suggested by @Iguananaut, I ran pip install -e . instead.

It now works.

So I then did a pip uninstall mypackage and did a python setup.py develop again to reproduce. It didn't reproduce.

I now understand that load_entry_point literally reads the entry_points.txt from the mypackage.egg-info. My only guess is that somehow that file was bad... and not getting fixed by running python setup.py develop.

So -- the answer to my query is:

For running console scripts in a dev environment, use pip install -e . and run the scripts out of the virtualenv/bin/. It's designed to work that way, and if it doesn't -- something else is wrong.

How to define a function to be a package entry point?

as you probably know, Python is a scripting language, therefore the execution of the program is going to start from the very top of your source file, and continue until the very end.
So if you execute the file mycode.py with the command python mycode.py the execution will start at the very top of the source file mycode.py

However, this approach brings a few problems in large applications. Usually, the first commands you run are imports, which basically fetch some other Python file, and execute the code within in. So as a practical example, let's say you have 2 files first.py and second.py. first.py starts as follows:

    import second

and second start as follows:

    def a_function():
      # do something

then Python sees the import command, runs second.py, and initialize the function a_function() so that it is now available within first.py

However second.py may also contain code that is meant to be executed right away ehen the interpreter is ran on the file, like so:

    def a_function():
      # do something
    print("I am called upon execution")

Now we have a problem: the print statement will be executed when first.py imports second.py.

In order to get around this, the follwing measure is used ESPECIALLY IN FILES THAT ARE MEANT FOR FUTURE IMPORT:

    def a_function():
      # do something

    if __name__ == "__main__":
      print("I am executed")

This is NOT like a C entrypoint (int main(){...}). In fact C compiler looks for an entrypoint to start execution at a given point in the code.
Pyhton interpreted insted simply perform a check on a predifined global (__name__). If the variable equals "__main__", this is a very generic explanation, it means that the file is being executed, otherwise that the file is being imported (therefore the check fails and the code isn't executed).

So in your case, simply define your fuction (def remove_green_background():), and call it first thing in your source file (basically, first command with no indentation)

setup.py: what is a difference between entry points and cmdclass?

cmdclass is a way to modify behaviour of the very setup.py. For example you can override build or install commands to extend them.

entry_points are similar to scripts, they declares scripts that will be created on installation. Those scripts are intended to run by users.

How to add console_script/entry point to setup.py that call a class function python

According to setuptools' documentation on "Automatic Script Creation" entry-points can only be functions:

The way to use this feature is to define “entry points” in your setup script that indicate what function the generated script should import and run.

---

Related Topics