pip

- 440 words - 3 minutes

Basic commands

Run all commands from the project folder, where pyproject.toml and setup.cfg exist.

  • Install in the user site-packages directory:

      pip install --user .
    

    Source files are copied into ~/.local/lib/python<ver>/site-packages/, the user site-packages folder in GNU/Linux, check on other operating systems [1] .

  • Install in development mode [2] in the user site-packages directory:

      pip install --prefix ~/.local -e .
    

    Creates path configuration file easy-install.pth containing the path to the source folder. This adds the source folder to the import search path [3] . Legacy project.egg-link is also created with identical content.

  • Uninstall:

      pip uninstall project
    

    Removes the source files or the path configuration file from the user or system site-packages directories.

  • Build wheel:

      pip wheel .
    

    File <project>-<version>-py3-none-any.whl is created [4] .

  • Install wheel [5] :

      pip install project-1.0-py3-none-any.whl
    

Project structure

Recommended files [6] :

project/
└── pyproject.toml
└── setup.cfg
└── LICENSE.txt
└── README.md
└── src/
    └── package/
        ├── __init__.py
        └── module.py

pyproject.toml

Define the build tools for PEP508 [7] :

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

setup.cfg

Basic template file [8] :

[metadata]
name = project
version = 0.1
author = FirstName LastName
author_email = john@example.com
description = Description about project
long_description = file: README.md
long_description_content_type = text/markdown
classifiers =
    Programming Language :: Python :: 3
    License :: OSI Approved :: LicenseName
    Operating System :: OS Independent

[options]
package_dir =
    = src
packages = find:
scripts = bin/tool.py
python_requires = >=3.6

[options.packages.find]
where = src

To include license files in the distribution file [9] :

[metadata]
license_files =
   LICENSE.txt
   3rdparty/*.txt

Prevent typo-squatting

Use pip-tools to read requirements.in and create requirements.txt with hashes [10] .

Create a virtual environment with pip-tools

python3 -m venv .env
.env/bin/pip install pip-tools==6.4.0

Create a lock file

echo 'icloudpd==1.7.2' >> requirements.in
.env/bin/pip-tools compile --generate-hashes

Use the lock file

.env/bin/pip install -r requirements.txt

Prevent dependency confusion

Disallow using Pypi when installing from a local repository.

.env/bin/pip install <my package> --index-url <url>

Do not use the --extra-index-url option.

References

  1. Command Line Interface in site - Site-specific configuration hook
  2. develop - Deploy the project source in “Development Mode” in setuptools documentation > Command Reference
  3. See definition of path configuration files in the seventh paragraph in site — Site-specific configuration hook
  4. Building Wheels in User Guide in the wheel documentation
  5. Installing Wheels in User Guide in the wheel documentation
  6. A simple project in An Overview of Packaging for Python > Tutorials > Packaging Python Projects
  7. PEP508 Specifying Minimum Build System
  8. Configuring metadata in An Overview of Packaging for Python > Tutorials > Packaging Python Projects
  9. Including license files in the generated wheel file
  10. How to secure your Python software supply chain by Benoît Goujon, October 28th, 2021