Pyproject.toml

Pyproject.toml#

The primary way to configure the process of building Python packages is by specifying the pyproject.toml configuration file. There are several features you may encounter.

For more information, check writing your pyproject.toml guide.

Dependencies#

With project.dependencies variable you can specify which packages your packages depends on - so they’ll automatically installed by pip.

The following cell creates pyproject.toml which requires python-dotenv==1.0.1 and installs “package” based on this pyproject.toml.

#init
#file pyproject.toml
[project]
name = "toy_package"
version = "0.0.0"
dependencies = ["python-dotenv==1.0.1"]

The installation of the package:

mkdir target
pip3 install . --target target &> /dev/null

The following cell shows the contents of the installation target, there are files belonging to python_dotenv that depend on it.

ls target

bin  dotenv  python_dotenv-1.0.1.dist-info  toy_package-0.0.0.dist-info

Optional#

You can specify dependencies that would not be installed by default. To install these, you must explicitly specify the corresponding keyword in the square brackets after the package name.

To specify optional dependencies in the pyproject.toml, use the [project.optional-dependencies] table, assigning the list of dependencies to the keyword.

Consider the common scenario: you are use flake8 to check your code in the dev environment, but you don’t need this dependency to be installed with the package.

#init
#file pyproject.toml
[project]
name = "toy_package"
version = "0.0.0"

[project.optional-dependencies]
dev = ["flake8"]

Installing the package without specifying any additional specification just produces an empty installation.

pip3 install . --target ./result &> /dev/null
ls result

toy_package-0.0.0.dist-info

However, if you specify [dev] after the package name, all the packages required by flake8 will be included in installation target.

pip3 install --upgrade .[dev] --target ./result &> /dev/null
ls result

bin                     pycodestyle-2.14.0.dist-info
flake8                  pycodestyle.py
flake8-7.3.0.dist-info  pyflakes
mccabe-0.7.0.dist-info  pyflakes-3.4.0.dist-info
mccabe.py               result
__pycache__             toy_package-0.0.0.dist-info

Extra files#

If your package contains some resources that do not have the py extension by default, they will not be included in the final distribution. You have to make extra configuration to make thing work.

The following cell creates an example that will be used to demonstrate the feature.

#init
#file pyproject.toml
[project]
name = "toy_package"
version = "0.0.0"

The “project” files are created in the following cell.

mkdir -p src/my_files
touch src/my_files/data_file{1..5}.txt
touch src/my_files/script_file{1..5}.py
tree src

src
└── my_files
    ├── data_file1.txt
    ├── data_file2.txt
    ├── data_file3.txt
    ├── data_file4.txt
    ├── data_file5.txt
    ├── script_file1.py
    ├── script_file2.py
    ├── script_file3.py
    ├── script_file4.py
    └── script_file5.py

2 directories, 10 files

src folder contains some .txt and some .py files.

The following cell installs the package in the result folder and lists its contents:

rm -rf result
mkdir result
pip3 install . --target result &> /dev/null 
ls result/my_files

__pycache__      script_file2.py  script_file4.py
script_file1.py  script_file3.py  script_file5.py

As the result there are only .py files comes with installed package.

The following cell shows options to correct the configuration saving .txt files in distibution.

#init
#file pyproject.toml
[project]
name = "toy_package"
version = "0.0.0"

[tool.setuptools]
include-package-data = true

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

You have to specify the additional packages that the build must include in the MANIFEST.in.

#file MANIFEST.in
include src/my_files/*.txt

The project structure is created in the following cell.

mkdir -p src/my_files
touch src/my_files/data_file{1..5}.txt
touch src/my_files/script_file{1..5}.py
tree src

src
└── my_files
    ├── data_file1.txt
    ├── data_file2.txt
    ├── data_file3.txt
    ├── data_file4.txt
    ├── data_file5.txt
    ├── script_file1.py
    ├── script_file2.py
    ├── script_file3.py
    ├── script_file4.py
    └── script_file5.py

2 directories, 10 files

The installation in the result folder now includes the .txt files.

rm -rf result
mkdir result
pip3 install . --target result &> /dev/null
ls result/my_files

data_file1.txt  data_file4.txt  script_file1.py  script_file4.py
data_file2.txt  data_file5.txt  script_file2.py  script_file5.py
data_file3.txt  __pycache__     script_file3.py
Contents