Python > Deployment and Distribution > Packaging Python Projects > Creating `setup.py` or `pyproject.toml` files

Creating a `pyproject.toml` file for packaging with Poetry

This example demonstrates how to create a pyproject.toml file for packaging a Python project using Poetry. Poetry is a modern dependency management and packaging tool that simplifies the process of creating, managing, and publishing Python packages. This is a recommended standard for modern Python projects.

Basic `pyproject.toml` Structure (Poetry)

This code snippet creates a basic pyproject.toml file using Poetry. Let's break down the key parts: * [tool.poetry]: This section contains the project's metadata, such as the name, version, description, authors, license, and readme file. * name: The name of your package. * version: The version number of your package. Follow semantic versioning (e.g., 0.1.0, 1.0.0). * description: A short, one-line description of your package. * authors: A list of authors and their email addresses. * license: The license of your package. * readme: The path to the readme file. * [tool.poetry.dependencies]: This section lists the dependencies required by your package. * python: Specifies the supported Python versions. * requests and numpy: Example dependencies with version constraints. * [tool.poetry.dev-dependencies]: This section lists dependencies used for development, such as testing and linting tools. * pylint and pytest: Example development dependencies with version constraints. * [build-system]: This section specifies the build system used for packaging your project. It requires poetry-core and uses poetry.core.masonry.api as the build backend.

[tool.poetry]
name = "my_package"
version = "0.1.0"
description = "A short description of the package"
authors = ["Your Name <your.email@example.com>"]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = ">=3.7,<3.11"
requests = "^2.28.1"
numpy = "^1.23.0"

[tool.poetry.dev-dependencies]
pylint = "^2.15.0"
pytest = "^7.2.0"

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

Concepts Behind the Snippet

The pyproject.toml file is a configuration file that specifies the build system and package metadata for a Python project. Poetry uses this file to manage dependencies, build packages, and publish them to PyPI. It provides a declarative way to define your project's configuration, making it easier to manage dependencies and ensure reproducibility.

Real-Life Use Case

Imagine you're starting a new Python project that requires several dependencies. Using Poetry and a pyproject.toml file simplifies dependency management, ensures that your project is reproducible, and makes it easy to build and publish your package.

Best Practices

  • Use Poetry's CLI to manage dependencies. Avoid manually editing the pyproject.toml file unless necessary.
  • Use version constraints to specify the compatible versions of your dependencies. Poetry supports a variety of version constraint operators, such as ^, ~, and >=.
  • Keep your dependencies up-to-date by running poetry update.
  • Use a virtual environment to isolate your project's dependencies. Poetry automatically manages virtual environments for your projects.
  • Test your package thoroughly before publishing it.

When to Use It

Use pyproject.toml with Poetry (or other modern build backends) for all new Python projects. It provides a more modern and convenient way to manage dependencies, build packages, and ensure reproducibility compared to setup.py.

Alternatives

Alternatives to Poetry include other build backends like Flit and Hatch, which also use pyproject.toml. You can also use setup.py directly, but it's generally recommended to use a modern build backend for new projects.

Pros and Cons of pyproject.toml with Poetry

  • Pros: Declarative configuration, simplified dependency management, reproducible builds, virtual environment management, easy publishing.
  • Cons: Requires learning a new tool (Poetry), may not be compatible with older projects that rely on setup.py.

← Creating `pyproject.toml` using Poetry Creating a `requirements.txt` file →

FAQ

  • How do I install Poetry?

    You can install Poetry by following the instructions on the Poetry website: https://python-poetry.org/docs/#installation.
  • How do I add a dependency using Poetry?

    Use the poetry add command. For example, to add the requests library, run poetry add requests.
  • How do I build a distribution package using Poetry?

    Run the poetry build command. This will create a wheel distribution and a source distribution in the dist directory.
  • How do I install the dependencies defined in pyproject.toml?

    Run the poetry install command. This will create a virtual environment and install all the dependencies specified in your pyproject.toml file.