How to Build and Publish Python Packages With Poetry

Poetry is a modern and useful tool for package development and distribution in Python that helps with dependency management. The entire process is consolidated into a single, intuitive interface with Poetry, in contrast to conventional methods that call for numerous tools and intricate setups. This greatly simplifies tasks like versioning, dependency management, and publishing to PyPI. We will outline the procedures and recommended practices to adhere to in this comprehensive how-to for developing and publishing Python packages with Poetry.

Benefits of Using Poetry

1. Dependency Management:
   Poetry makes adding, updating, and managing dependencies easier. This is one of the benefits of using poetry for dependency management. To create a consistent and repeatable environment, the project requirements and dependencies are defined using a 'pyproject.toml' file.
2. Versioning:
   Poetry automates versioning based on semantic versioning principles. This helps maintain clarity and consistency across different releases of your package.
3. Publishing:
   Poetry streamlines the process of publishing packages to PyPI. It handles the build and upload processes, reducing the likelihood of errors and making it easier to distribute your package.
4. Isolation:
   Poetry creates isolated virtual environments for your projects, preventing dependency conflicts and ensuring that your projects do not interfere with each other.

Creating a New Project Structure

The structure of the files and folder will look like this:

Note: "Name of the file and folder should be unique to publish it in PyPI. "

my_python_pack_ex/
├── my_python_pack_ex/
 |     └──__init__.py
│    └── my_python_pack_ex.py
├── tests/
│   └── test_my_python_pack_ex.py
├── pyproject.toml
├──  setup.py
└── README.md

Create directory using the following commands:

mkdir my_python_pack_ex
cd my_python_pack_ex

Initializing a Poetry Project

Step 1: Install the 'poetry' in the virtual environment.

Write the below command in the cmd terminal.

pip install poetry     

Step 2: Initialize a new Poetry project:

poetry init

To configure your project, simply follow the prompts and enter information such as the package name, version, description, and dependencies. This will create a 'pyproject.toml' file and will look like similar to below one.

[tool.poetry]
name = "my_python_pack_ex"
version = "0.1.0"
description = "A simple hello world package"
authors = ["Your Name <[email protected]>"]

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.dev-dependencies]
pytest = "^6.2.4"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Step 3: Develop Your Package

To the project, add your Python code. For instance, in the <my_python_pack_ex> directory, make a new file named <my_python_pack_ex.py>.

# my_demo_pack_ex/my_demo_pack_ex.py

def hello_world():
    return "Hello, world!"

Create '__init__.py' file.

# my_demo_pack_ex/__init__.py

from .my_demo_pack_ex import hello_world

Create a 'setup.py' file.

from setuptools import setup, find_packages

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

setup(
    name="my-demo-pack-ex",
    version="0.1.0",
    author="<athour name>",
    author_email="<author email>",
    description="A simple demo package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    packages=find_packages(),
    install_requires=[
        "requests",
    ],
    classifiers=[
        "Programming Language :: Python :: 3",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

Create a README.md file.

This is the demo for publishing the library or package using poetry library.

Step 4: Create Tests

# tests/test_my_demo_pack_ex.py

from my_demo_pack_ex import hello_world

def test_hello_world():
    assert hello_world() == "Hello, world!"

Step 5: Executing the tests on the package.

Run the code to be safe from any errors:

poetry env remove python
poetry install
poetry run pytest

Output:

Your output look like similar to this.

=============================== test session starts ===============================
platform win32 -- Python 3.9.12, pytest-7.1.1, pluggy-1.0.0
rootdir: ###################################  
plugins: anyio-3.5.0, Faker-22.2.0
collected 1 item

tests/test_my_demo_pack_ex.py .                                                   [100%]

=============================== 1 passed in 0.01s ===============================

Step 6: Build Your Package

After your code is complete and tested, use Poetry to assemble your package:

poetry build

Distribution archives (.whl and.tar.gz) in the dist directory will be created by this command.

Step 7: Publish Your Package

You must obtain a PyPI API token in order to publish your package on PyPI. To start, log into your PyPI account, then create a new token.

Include the token in your configuration for Poetry:

poetry config pypi-token.pypi <your-api-token>

Publish your package:

poetry publish --build

Output after publish:

Published python package

URL for the published package: pypi.org/project/my_demo_pack_ex/

Project Directory Layout:

Conclusion

Poetry facilitates the creation and publication of Python packages in a streamlined and effective manner. These actions will help to guarantee a seamless experience:

1. Select a Unique Project Name: Make sure the name you've chosen for your project isn't already in use on PyPI. To make sure your preferred project name is available, use the PyPI search page.
2. Update Project Configuration: Make sure the unique project name and version are reflected in your setup.py and pyproject.toml files. Conflicts during the upload process are lessened as a result.
3. Construct the Package: Incorporate poetry into your package. Your package is compiled and ready for distribution with this command.
4. Release the Package:Using Poetry, upload your package to PyPI. This stage releases your package for installation and usage by others.

These guidelines will help you manage your Python packages effectively and make sure they are built correctly and made available to others on PyPI. By using Poetry's robust features for Python package management, this method reduces errors.

Frequently Asked Questions (FAQs)

Q. What is Poetry and why should I use it?

Poetry is a dependency management and packaging tool for Python. It simplifies the process of managing project dependencies, versioning, and publishing packages to PyPI. By consolidating these tasks into a single tool, Poetry provides a streamlined and efficient workflow, making it easier to maintain consistent project environments and reduce errors.

Q. How do I install Poetry?

You can install Poetry using the following command:

curl -sSL https://install.python-poetry.org | python3 -

Alternatively, you can use pip:

pip install poetry

Q. How do I create a new project with Poetry?

To create a new project, use the command:

poetry new my_project

This initializes a new directory with a `pyproject.toml` file for your project configuration.

Q. How do I add dependencies to my project?

To add a package dependency, use:

poetry add requests

For development dependencies, use:

poetry add --dev pytest

Q. How do I build my package for distribution?

To build your package, run:

poetry build

This generates distribution files in the `dist` directory, such as `.whl` and `.tar.gz` files.

Q. How do I publish my package to PyPI?

First, ensure you have an account on PyPI and obtain an API token. Then, use the following command to publish your package:

poetry publish --build

Poetry will prompt you for your PyPI username and password, but using an API token is recommended for security.

Q. How do I configure my PyPI token for publishing?

Configure your PyPI token in your environment or `.pypirc` file. For example, you can set the token as an environment variable:

export POETRY_PYPI_TOKEN_PYPI=your-token

Q. What should I do if I encounter issues during publishing?

Use the verbose option to get more details about the error:

poetry publish --build -vvv

abhilashgaurav003

Follow

Improve

Article Tags :

• Python
• Python Poetry

Practice Tags :

• python