Gentoo Python Guide

Author:

Michał Górny

License:

Creative Commons Attribution 4.0 International

Contents:

• Preface
• Python interpreters
  • Versions of Python
  • Life cycle of a Python implementation
  • Stability guarantees of Python implementations
  • Alternative Python implementations
  • Support for multiple implementations
  • Implementation support policy
  • Backports
• Choosing between Python eclasses
  • Overview
  • Build time vs runtime use
  • Single-impl vs multi-impl
  • Python-first packages (distutils-r1 eclass)
• Common basics
  • PYTHON_COMPAT
  • PYTHON_DEPS and PYTHON_REQUIRED_USE
  • Python environment
  • Dependencies in Python packages
• python-any-r1 — build-time dependency
  • Basic use for unconditional Python
  • Dependencies
  • Conditional Python use
  • Additional conditional dependencies
  • Multiple sets of conditional dependencies
• python-single-r1 — single-impl packages
  • Basic use for unconditional Python
  • Dependencies
  • Conditional Python use
  • A hybrid: build-time + conditional runtime
  • Multiple USE conditions
  • Manual install
• python-r1 — multi-impl packages
  • Manual install
  • Dependencies
  • Pure Python autotools package
  • Conditional Python use
  • Additional build-time Python use
• distutils-r1 — standard Python build systems
  • The PEP 517 and legacy modes
  • Basic use (PEP 517 mode)
  • Source archives
  • Dependencies
  • python-single-r1 variant
  • PEP 517 build systems
  • setuptools_scm (flit_scm, hatch-vcs, pdm-backend) and snapshots
  • Packages installing extensions (C, Rust…)
  • Packages using Cython
  • Parallel build race conditions
  • Sub-phase functions
  • Passing arguments to setup.py
  • Calling custom setup.py commands
  • Enabling tests
  • Building documentation via Sphinx
  • Packages with optional Python build system usage
  • Packages with Rust extensions (using Cargo)
  • Installing packages without a PEP 517 build backend
• Tests in Python packages
  • Why is running tests important?
  • Using distutils_enable_tests
  • Choosing the correct test runner
  • Import-checking packages with no working tests
  • Undesirable test dependencies
  • Missing test files in PyPI packages
  • ImportErrors for C extensions
  • Checklist for dealing with test failures
  • Skipping problematic tests
  • Tests requiring Internet access
  • Tests aborting (due to assertions)
  • Installing extra dependencies in test environment (PEP 517 mode)
• distutils-r1 legacy concepts
  • Different build system variations
  • In-source vs out-of-source builds
  • Installing the package before testing
• pypi — helper eclass for PyPI archives
  • PyPI URLs
  • Packages with matching name and version
  • Package with a different name
  • Customizing the generated URL
  • Fetching wheels
• Common helper functions
  • Install helpers
  • Fixing shebangs on installed scripts
  • Byte-compiling Python modules
  • Querying the implementation information
• Advanced dependencies
  • Requesting USE flags on the Python interpreter
  • Dependencies conditional to Python version
  • Dependencies on CFFI and greenlet
  • Optional test suite dependencies on Rust packages
• pytest recipes
  • Skipping tests based on markers
  • Skipping tests based on paths/names
  • Avoiding the dependency on pytest-runner
  • Controlling pytest plugins used
  • Using pytest-xdist to run tests in parallel
  • Dealing with flaky tests
  • Using pytest-timeout to prevent deadlocks (hangs)
  • Avoiding dependencies on other pytest plugins
  • TypeError: _make_test_flaky() got an unexpected keyword argument ‘reruns’
  • ImportPathMismatchError
  • Failures due to missing files in temporary directories
  • fixture ‘…’ not found
  • Warnings and pytest.raises()
• Advanced concepts
  • Namespace packages
• Expert python-r1 usage
  • Partially restricting Python implementation
  • Restricting interpreters for python_setup
  • Disjoint build dependencies (any-r1 API)
  • Combining any-r1 API with implementation restrictions
• Integration with build systems written in Python
  • Meson
  • SCons
  • waf
• Porting tips
  • Retroactive changes
  • Experimental Python implementations
  • Python 3.13
  • Python 3.12
  • Python 3.11
  • Python 3.10
  • Python 3.9
  • Python 3.8
  • Replacing the toml package
• Migration guides
  • Migrating from old PYTHON_USEDEP syntax in python-single-r1
  • Migrating from EAPI 7 to EAPI 8
  • Migrating to PEP 517 builds
  • multipart vs. python-multipart packages
• QA checks and warnings
  • Improved QA warning reporting in Portage
  • Compiled bytecode-related warnings
  • Stray top-level files in site-packages
  • Deprecated PEP 517 backends
• Python package maintenance
  • Package name policy
  • Support for Python 2
  • Which implementations to test new packages for?
  • Adding new Python implementations to existing packages
  • Which packages can be (co-)maintained by the Python project?
  • Porting packages to a new EAPI
  • Monitoring new package versions
  • Stabilization recommendations
  • Routine checks on installed Python packages
• Maintenance of Python implementations
  • Notes specific to Python interpreters
  • Adding a new Python implementation
  • Removing a Python implementation
  • Python build system bootstrap

Indices and tables

• Index

• Search Page