Poetry and scripts — Python: Setting up the environment

• Entry point in the example project
• Description of the scripts in the configuration file

When we develop a program for the end user, we put entry points in the code and get modules or packages ready to run.

But even if you do everything correctly, the user still has to write a very long command, python3 -m FULL_NAME_MODULE.

To simplify this, developers design their packages so users can enter short commands. Poetry calls these commands scripts.

Entry point in the example project

The entry point to the program can be any function located in any module. Let's place the entry point in the hello.scripts.say_hello module to keep things in order:

tree hello

hello/
├── __init__.py
└── scripts
    ├── __init__.py
    └── say_hello.py

cat hello/scripts/say_hello.py

def main():
    print("Hello!")


if __name__ == '__main__':
    main()

Check that the entry point works when the long command is specified:

poetry run python -m hello.scripts.say_hello

Hello!

Usually, all the complicated logic is placed somewhere in the library code. That's in the hello package in our case. But the scripts only contain the small code fragments necessary to run them.

Suppose you've written some essential code in one of the scripts package modules and want to import it elsewhere. In that case, you should stop and consider where that code should be. In other words, scripts can import from a library but not vice versa.

Description of the scripts in the configuration file

Now we know what scripts are, so the next step is to learn how to write them.

Open pyproject.toml and find the tool.poetry.dependencies section. Immediately after it, add a new section, tool.poetry.scripts, which looks like this:

[tool.poetry.scripts]
say-hello = "hello.scripts.say_hello:main"

Let us look at how a key-value pair works:

• The key is the name of the future short command
• The value is the full module name, colon, and declared function name

Note the difference in the names:

• The command is called say-hello
• The module is called say_hello

Compound command names are usually hyphenated, but Python module names can't have this symbol. Therefore, in this case, the hyphen is replaced by an underscore.

Remember that hello.scripts.say_hello is the full module name, which looks like the path hello/scripts/say_hello.py at first glance. If you accidentally give the file path instead of the module name or forget to enter the function name, the short command call will end with an error.

If we describe everything correctly, Poetry will allow us to call the newly declared short command in the usual way:

poetry run say-hello

Hello!