Register to get access to free programming courses with interactive exercises

Poetry and scripts Python: Setting up the environment

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!

asciicast


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.

Get access
130
courses
1000
exercises
2000+
hours of theory
3200
tests

Sign up

Programming courses for beginners and experienced developers. Start training for free

  • 130 courses, 2000+ hours of theory
  • 1000 practical tasks in a browser
  • 360 000 students
By sending this form, you agree to our Personal Policy and Service Conditions

Our graduates work in companies:

Bookmate
Health Samurai
Dualboot
ABBYY
Suggested learning programs
profession
new
Developing web applications with Django
10 months
from scratch
under development
Start at any time

Use Hexlet to the fullest extent!

  • Ask questions about the lesson
  • Test your knowledge in quizzes
  • Practice in your browser
  • Track your progress

Sign up or sign in

By sending this form, you agree to our Personal Policy and Service Conditions
Toto Image

Ask questions if you want to discuss a theory or an exercise. Hexlet Support Team and experienced community members can help find answers and solve a problem.