Introduction

Poetry is a powerful dependency management and packaging tool for Python. It simplifies project creation, dependency installation, and environment isolation. In this tutorial, we'll walk through the steps to create and initialize a "Hello, World!" Python project using Poetry. For a practical example, you can refer to the actual code in this GitHub repository: jdevto/python-poetry-hello. 🎉

Prerequisites

Before we start, make sure you have the following installed on your system:

1. Python (version 3.7 or later)
2. Poetry (follow the official installation guide)

You can verify your installations by running:

python --version
poetry --version

Step 1: Create a New Project

Start by creating a new directory for your project. Navigate to the directory where you want to store your project and run:

poetry new hello-world

This command creates a new folder named hello-world with the following structure:

hello-world/
├── README.rst
├── hello_world
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_hello_world.py

Key Components

• hello_world/: Contains your Python package.
• pyproject.toml: Defines your project dependencies and metadata.
• tests/: Directory for your test cases.

Step 2: Add a "Hello, World!" Script

Navigate to the hello_world directory:

cd hello-world/hello_world

Edit the __init__.py file or create a new file, main.py:

# hello_world/main.py
def main():
    print("Hello, World!")

if __name__ == "__main__":
    main()

Step 3: Update pyproject.toml

Ensure the pyproject.toml file includes an entry point so you can run the script as a command. Add the following under the [tool.poetry.scripts] section:

[tool.poetry.scripts]
hello-world = "hello_world.main:main"

[tool.poetry.dependencies]
python = ">=3.9"

[tool.poetry.group.dev.dependencies]
pytest = "^6.0.0"
pytest-cov = "^3.0.0"
black = "^22.0.0"
flake8 = "^3.9.0"
mypy = "^0.910"

Step 4: Install Dependencies

Run the following command to install any dependencies and prepare the environment:

poetry install

Step 5: Run Your Script

To test your script, use:

poetry run hello-world

You should see the output:

Hello, World!

Step 6: Adding Tests

To ensure your script works correctly, add a test case in the tests/test_hello_world.py file:

def test_main(capsys):
    from hello_world.main import main

    main()
    captured = capsys.readouterr()
    assert captured.out == "Hello, World!\n"

Run the tests using Poetry:

poetry run pytest

Reminder: Running poetry lock After Changes

After changing the prerequisites or modifying dependencies in the pyproject.toml file (such as adding new dependencies or updating versions), always run poetry lock to regenerate the poetry.lock file and ensure that the correct versions are installed in your environment.

poetry lock

This step ensures that your lock file stays up-to-date with the pyproject.toml configuration and guarantees consistency across your development and production environments.

Conclusion

Congratulations! You've successfully created a "Hello, World!" Python project using Poetry with a working example, visit the GitHub repository: jdevto/python-poetry-hello. This setup provides a solid foundation for building more complex applications while managing dependencies and packaging effortlessly.

Feel free to explore additional features of Poetry, like dependency version constraints, virtual environments, and publishing packages.