How to Manage Python Projects With pyproject.toml :

Reader
February 19, 2025
How to Manage Python Projects With pyproject.toml
by:
blow post content copied from  Real Python
click here to view original post

The pyproject.toml file simplifies Python project configuration by unifying package setup, managing dependencies, and streamlining builds. In this tutorial, you’ll learn how it can improve your day-to-day Python setup by exploring its key use cases, like configuring your build system, installing packages locally, handling dependencies, and publishing to PyPI.

By the end of this tutorial, you’ll understand that:

  • pyproject.toml is a key component for defining a Python project’s build system, specifying requirements and the build backend.
  • Dependencies and optional dependencies can be managed directly within the pyproject.toml file or combined with the traditional requirements.txt.
  • Scripts for command-line execution are defined in the [project.scripts] section, allowing you to automate common tasks.
  • Dynamic metadata in pyproject.toml enables flexible project configuration, with attributes like version being resolved at build time.
  • The Python packaging ecosystem includes various tools that leverage pyproject.toml for project management, enhancing collaboration, flexibility, and configurability.

To get the most out of this tutorial, you should be familiar with the basics of Python. You should know how to import modules and install packages with pip. You should also be able to navigate the terminal and understand how to create virtual environments.

The pyproject.toml package configuration file is the relatively new (circa 2016) standard in the Python ecosystem, intended to unify package configuration. It’s also supported by many major tools for managing your Python projects. Some of the project management tools that support the pyproject.toml file are pip, Setuptools, Poetry, Flit, pip-tools, Hatch, PDM, and uv.

The pyproject.toml file is a configuration file written in the TOML syntax. For many Python project management needs, a minimal pyproject.toml file doesn’t have to contain a lot of information:

TOML pyproject.toml 
[project]
name = "a-sample-project"
version = "1.0.0"

Different tools have different requirements, but the name and version of your project are officially the only required fields in the [project] table. Typically, you’ll want to include more fields, but if you only want to include a minimal pyproject.toml file, then that’s all you’ll need to get started. Just include this file at the root of your project.

To understand more about why using a pyproject.toml file may be useful, you’ll explore a sample CLI application to show you how the pyproject.toml file fits into a standard project workflow.

Setting Up a Python Project With pyproject.toml

The example project you’ll work with in this tutorial is inspired by the classic cowsay program. The example project is called snakesay and—once installed—you can run it with the ssay command:

Shell 
$ ssay Hello, World!

 _______________
( Hello, World! )
 ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
  \
   \    ___
    \  (o o)
        \_/ \
         λ \ \
           _\ \_
          (_____)_
         (________)=Oo°

As you can see, the program takes a string argument and echoes it back with a bit of ASCII art.

The structure of the example project follows a popular pattern for Python projects:

snakesay-project/    ← The project root
│
├── snakesay/        ← The main module of this project
│   ├── __init__.py
│   ├── __main__.py  ← The entry point to snakesay
│   └── snake.py     ← The core of the program
│
├── .gitignore
├── LICENSE
├── pyproject.toml   ← What this tutorial is about
└── README.md

The directory snakesay-project is the root location of your project. The main package, where most of the code goes, is the snakesay directory.

At the root level of the project, you’ve got the star of this tutorial, the pyproject.toml file. In this project, the pyproject.toml file currently contains the following content:

TOML pyproject.toml 
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "snakesay"
version = "1.0.0"

[project.scripts]
ssay = "snakesay.__main__:main"

[tool.setuptools.packages.find]
where = ["."]

As the tutorial progresses, you’ll examine what all this means in more detail. You’ll also expand this pyproject.toml to include more tables and fields. As it stands, this pyproject.toml file includes:

  • The [build-system] table: Specifies what’s needed to build the project. The requires key lists the required packages, and the build-backend key defines the module used for the build process.
  • The [project] table: Contains essential project metadata and has plenty of optional fields, some of which you’ll explore later in this tutorial.
  • The [project.scripts] table: Allows you to define one or several executable commands to be able to call your application from the command line. In this case, it’s ssay, but it can be anything you like.
  • The [tools.setuptools.packages.find] table: Tells your build-system, Setuptools, where to find packages in your project. In this case, it’s just the root directory.

With this pyproject.toml file, you’ve already defined all the configuration you need to build and run your project.

The [tools.setuptools.packages.find] table isn’t required since the value of ["."] is the default. Even though it’s the default, sometimes Setuptools can’t find other modules in the project root, and explicitly setting the where key can help with this.

Setuptools has various defaults for package discovery, which include the current project layout and the src layout.

Read the full article at https://realpython.com/python-pyproject-toml/ »

[ Improve Your Python With 🐍 Python Tricks 💌 – Get a short & sweet Python Trick delivered to your inbox every couple of days. >> Click here to learn more and see examples ]


February 19, 2025 at 07:30PM
Click here for more details...

=============================
The original post is available in Real Python by
this post has been published as it is through automation. Automation script brings all the top bloggers post under a single umbrella.
The purpose of this blog, Follow the top Salesforce bloggers and collect all blogs in a single place through automation.
============================

Salesforce