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!
Are there any more questions? Ask them in the Discussion section.
The Hexlet support team or other students will answer you.
For full access to the course you need a professional subscription.
A professional subscription will give you full access to all Hexlet courses, projects and lifetime access to the theory of lessons learned. You can cancel your subscription at any time.