Understanding pyproject.toml

00:00 In the last lesson, you saw various ways to set up a new Poetry project. In this lesson, I’ll walk you through the important sections of the pyproject.toml file, which is essential for managing your Python projects with Poetry.

00:13 The pyproject.toml isn’t unique to Poetry. It’s a configuration file standard defined by PEP 518. This PEP outlines how Python projects to define their build dependencies.

00:24 The format used is TOML, which stands for Tom’s Obvious Minimal Language. It was chosen for how flexible it can be while maintaining simplicity, making it more convenient to configure your projects without involving complex syntax.

00:39 When you create a new project with Poetry, this is the pyproject.toml that gets generated. It should look something like this.

00:48 Let’s break down the key parts of this file.

00:51 The sections are often referred to as tables, the first being the [tool.poetry] section. This section holds general information about your project.

01:01 Some essential fields you must specify include the name of your project. This will be an identifier in cases where you might publish your project or package to PyPI—Python Package index.

01:14 Two, the version of your project, typically following the semantic version and method. Major, dot minor, dot patch, 0.1.0, for example. Three, the project description. A brief description of what your project or package is about. Four, a list of authors that contributed to the project formatted as name and email in angled brackets. Five, a README.

01:40 This is where you specify your project’s documentation file.

01:44 These fields are important for publishing your project as they help others find and understand your project or package on PyPI. Next, you have the [tool.poetry .dependencies] section or table.

01:59 This is where you declare the Python version or any external packages that your project relies on. Initially, you see just the Python version listed like this.

02:10 One key thing to note here is that Poetry assumes the minimum Python version based on the environment in which it was installed. For example, if you installed Poetry using pipx on Python 3.12, it will automatically use that as the minimum version in the pyproject.toml file.

02:28 You can, of course, change this to fit your needs. As your project grows, this section will expand with additional dependencies and Poetry will help manage versioning for you, ensuring that you have the right versions for your projects installed.

02:43 Next, you have the build-system section. This section isn’t Poetry specific and it defines metadata used by Poetry and other tools to build your package. It follows the PEP 517 standard of Python packaging.

02:57 It includes two keys: one, requires, which is a list of build time dependencies for your package. Two, build-backend, the backend tool that Poetry uses to build your projects.

03:10 It’s a Python object used to perform the build process. As you continue developing your project, you’ll add more details and dependencies to the pyproject.toml file.

03:20 It’s designed to grow with your project, especially the tool.poetry.dependencies section, which will list all the external libraries you use in your project.

03:31 In the next lesson, you and I will move on to explore how to manage virtual environments with Poetry.