Downstream packaging

This page is for distribution packagers building extra-platforms from source, either a PyPI sdist or a Git tag. To install it on your own system, use uv pip install extra-platforms or your distribution’s package.

Building

The wheel is built with uv_build, declared as the [build-system] backend. Distributions that do not yet package uv-build can fall back to setuptools: extra-platforms is a pure-Python, single-package project, so setuptools.build_meta builds it with no extra configuration (setuptools’ own defaults exclude tests/ and docs/ from package discovery).

Dependencies

This is a graph of the Python package’s dependencies. The package itself has no runtime dependency: boxes hold the directly-declared dependencies of each extra and development group, drawn as hexagons; transitive dependencies render outside the boxes as ovals:

        flowchart LR
    extra_platforms[["`extra-platforms`"]]

    pygments(["`pygments`"])
    jinja2(["`jinja2`"])
    beautifulsoup4(["`beautifulsoup4`"])
    docutils(["`docutils`"])
    markdown_it_py(["`markdown-it-py`"])
    accessible_pygments(["`accessible-pygments`"])
    click_0(["`click`"])
    cloup(["`cloup`"])
    colorama(["`colorama`"])
    exceptiongroup(["`exceptiongroup`"])
    mdit_py_plugins(["`mdit-py-plugins`"])
    packaging(["`packaging`"])
    pluggy(["`pluggy`"])
    pyyaml(["`pyyaml`"])
    sphinx_basic_ng(["`sphinx-basic-ng`"])
    tabulate(["`tabulate`"])
    typing_extensions(["`typing-extensions`"])
    wcmatch(["`wcmatch`"])
    wcwidth(["`wcwidth`"])
    alabaster(["`alabaster`"])
    babel(["`babel`"])
    boltons(["`boltons`"])
    bracex(["`bracex`"])
    certifi(["`certifi`"])
    charset_normalizer(["`charset-normalizer`"])
    deepmerge(["`deepmerge`"])
    execnet(["`execnet`"])
    idna(["`idna`"])
    imagesize(["`imagesize`"])
    iniconfig(["`iniconfig`"])
    markupsafe(["`markupsafe`"])
    mdurl(["`mdurl`"])
    psutil(["`psutil`"])
    roman_numerals(["`roman-numerals`"])
    snowballstemmer(["`snowballstemmer`"])
    soupsieve(["`soupsieve`"])
    sphinxcontrib_applehelp(["`sphinxcontrib-applehelp`"])
    sphinxcontrib_devhelp(["`sphinxcontrib-devhelp`"])
    sphinxcontrib_htmlhelp(["`sphinxcontrib-htmlhelp`"])
    sphinxcontrib_jsmath(["`sphinxcontrib-jsmath`"])
    sphinxcontrib_qthelp(["`sphinxcontrib-qthelp`"])
    sphinxcontrib_serializinghtml(["`sphinxcontrib-serializinghtml`"])
    urllib3(["`urllib3`"])

    subgraph ext_pytest [--extra pytest]
        ext_pytest_pytest{{"`pytest >=8.2.1`"}}
    end

    subgraph grp_docs [--group docs]
        sphinx{{"`sphinx >=9.1`"}}
        click_extra{{"`click-extra >=8.7`"}}
        myst_parser{{"`myst-parser >=5.1`"}}
        furo{{"`furo >=2025.9.25`"}}
        sphinxcontrib_mermaid{{"`sphinxcontrib-mermaid >=1.2.3`"}}
        sphinx_autodoc_typehints{{"`sphinx-autodoc-typehints >=2.4`"}}
        sphinx_copybutton{{"`sphinx-copybutton >=0.5.2`"}}
        sphinx_design{{"`sphinx-design >=0.6`"}}
        sphinxext_opengraph{{"`sphinxext-opengraph >=0.13`"}}
        grp_docs_pytest{{"`pytest >=8.2.1`"}}
    end

    subgraph grp_test [--group test]
        pytest{{"`pytest`"}}
        requests{{"`requests >=2.34`"}}
        pytest_cov{{"`pytest-cov >=7`"}}
        pytest_xdist{{"`pytest-xdist >=3.7`"}}
        coverage{{"`coverage >=7.11`"}}
        tomli{{"`tomli >=2.3`"}}
        pytest_github_actions_annotate_failures{{"`pytest-github-actions-annotate-failures >=0.3`"}}
        pytest_randomly{{"`pytest-randomly >=4`"}}
    end

    sphinx --> requests
    sphinx --> pygments
    sphinx --> jinja2
    sphinx --> docutils
    sphinx --> colorama
    sphinx --> packaging
    sphinx --> alabaster
    sphinx --> babel
    sphinx --> imagesize
    sphinx --> roman_numerals
    sphinx --> snowballstemmer
    sphinx --> sphinxcontrib_applehelp
    sphinx --> sphinxcontrib_devhelp
    sphinx --> sphinxcontrib_htmlhelp
    sphinx --> sphinxcontrib_jsmath
    sphinx --> sphinxcontrib_qthelp
    sphinx --> sphinxcontrib_serializinghtml
    click_extra --> sphinx
    click_extra --> extra_platforms
    click_extra --> pygments
    click_extra --> docutils
    click_extra --> click_0
    click_extra --> cloup
    click_extra --> tabulate
    click_extra --> wcmatch
    click_extra --> wcwidth
    click_extra --> boltons
    click_extra --> deepmerge
    pytest --> pygments
    pytest --> tomli
    pytest --> colorama
    pytest --> exceptiongroup
    pytest --> packaging
    pytest --> pluggy
    pytest --> iniconfig
    myst_parser --> sphinx
    myst_parser --> jinja2
    myst_parser --> docutils
    myst_parser --> markdown_it_py
    myst_parser --> mdit_py_plugins
    myst_parser --> pyyaml
    furo --> sphinx
    furo --> pygments
    furo --> beautifulsoup4
    furo --> accessible_pygments
    furo --> sphinx_basic_ng
    requests --> certifi
    requests --> charset_normalizer
    requests --> idna
    requests --> urllib3
    pytest_cov --> pytest
    pytest_cov --> coverage
    pytest_cov --> pluggy
    pytest_xdist --> pytest
    pytest_xdist --> execnet
    pytest_xdist --> psutil
    sphinxcontrib_mermaid --> sphinx
    sphinxcontrib_mermaid --> jinja2
    sphinxcontrib_mermaid --> pyyaml
    coverage --> tomli
    pytest_github_actions_annotate_failures --> pytest
    pytest_randomly --> pytest
    sphinx_autodoc_typehints --> sphinx
    sphinx_copybutton --> sphinx
    sphinx_design --> sphinx
    sphinxext_opengraph --> sphinx
    jinja2 --> markupsafe
    beautifulsoup4 --> typing_extensions
    beautifulsoup4 --> soupsieve
    markdown_it_py --> mdurl
    accessible_pygments --> pygments
    cloup --> click_0
    exceptiongroup --> typing_extensions
    mdit_py_plugins --> markdown_it_py
    sphinx_basic_ng --> sphinx
    tabulate --> wcwidth
    wcmatch --> bracex
    extra_platforms -.-> ext_pytest
    extra_platforms -.-> grp_docs
    extra_platforms -.-> grp_test
    ext_pytest_pytest -.- pytest
    grp_docs_pytest -.- pytest

    click accessible_pygments "https://pypi.org/project/accessible-pygments/" _blank
    click alabaster "https://pypi.org/project/alabaster/" _blank
    click babel "https://pypi.org/project/babel/" _blank
    click beautifulsoup4 "https://pypi.org/project/beautifulsoup4/" _blank
    click boltons "https://pypi.org/project/boltons/" _blank
    click bracex "https://pypi.org/project/bracex/" _blank
    click certifi "https://pypi.org/project/certifi/" _blank
    click charset_normalizer "https://pypi.org/project/charset-normalizer/" _blank
    click click_0 "https://pypi.org/project/click/" _blank
    click click_extra "https://pypi.org/project/click-extra/" _blank
    click cloup "https://pypi.org/project/cloup/" _blank
    click colorama "https://pypi.org/project/colorama/" _blank
    click coverage "https://pypi.org/project/coverage/" _blank
    click deepmerge "https://pypi.org/project/deepmerge/" _blank
    click docutils "https://pypi.org/project/docutils/" _blank
    click exceptiongroup "https://pypi.org/project/exceptiongroup/" _blank
    click execnet "https://pypi.org/project/execnet/" _blank
    click extra_platforms "https://pypi.org/project/extra-platforms/" _blank
    click furo "https://pypi.org/project/furo/" _blank
    click idna "https://pypi.org/project/idna/" _blank
    click imagesize "https://pypi.org/project/imagesize/" _blank
    click iniconfig "https://pypi.org/project/iniconfig/" _blank
    click jinja2 "https://pypi.org/project/jinja2/" _blank
    click markdown_it_py "https://pypi.org/project/markdown-it-py/" _blank
    click markupsafe "https://pypi.org/project/markupsafe/" _blank
    click mdit_py_plugins "https://pypi.org/project/mdit-py-plugins/" _blank
    click mdurl "https://pypi.org/project/mdurl/" _blank
    click myst_parser "https://pypi.org/project/myst-parser/" _blank
    click packaging "https://pypi.org/project/packaging/" _blank
    click pluggy "https://pypi.org/project/pluggy/" _blank
    click psutil "https://pypi.org/project/psutil/" _blank
    click pygments "https://pypi.org/project/pygments/" _blank
    click pytest "https://pypi.org/project/pytest/" _blank
    click pytest_cov "https://pypi.org/project/pytest-cov/" _blank
    click pytest_github_actions_annotate_failures "https://pypi.org/project/pytest-github-actions-annotate-failures/" _blank
    click pytest_randomly "https://pypi.org/project/pytest-randomly/" _blank
    click pytest_xdist "https://pypi.org/project/pytest-xdist/" _blank
    click pyyaml "https://pypi.org/project/pyyaml/" _blank
    click requests "https://pypi.org/project/requests/" _blank
    click roman_numerals "https://pypi.org/project/roman-numerals/" _blank
    click snowballstemmer "https://pypi.org/project/snowballstemmer/" _blank
    click soupsieve "https://pypi.org/project/soupsieve/" _blank
    click sphinx "https://pypi.org/project/sphinx/" _blank
    click sphinx_autodoc_typehints "https://pypi.org/project/sphinx-autodoc-typehints/" _blank
    click sphinx_basic_ng "https://pypi.org/project/sphinx-basic-ng/" _blank
    click sphinx_copybutton "https://pypi.org/project/sphinx-copybutton/" _blank
    click sphinx_design "https://pypi.org/project/sphinx-design/" _blank
    click sphinxcontrib_applehelp "https://pypi.org/project/sphinxcontrib-applehelp/" _blank
    click sphinxcontrib_devhelp "https://pypi.org/project/sphinxcontrib-devhelp/" _blank
    click sphinxcontrib_htmlhelp "https://pypi.org/project/sphinxcontrib-htmlhelp/" _blank
    click sphinxcontrib_jsmath "https://pypi.org/project/sphinxcontrib-jsmath/" _blank
    click sphinxcontrib_mermaid "https://pypi.org/project/sphinxcontrib-mermaid/" _blank
    click sphinxcontrib_qthelp "https://pypi.org/project/sphinxcontrib-qthelp/" _blank
    click sphinxcontrib_serializinghtml "https://pypi.org/project/sphinxcontrib-serializinghtml/" _blank
    click sphinxext_opengraph "https://pypi.org/project/sphinxext-opengraph/" _blank
    click tabulate "https://pypi.org/project/tabulate/" _blank
    click tomli "https://pypi.org/project/tomli/" _blank
    click typing_extensions "https://pypi.org/project/typing-extensions/" _blank
    click urllib3 "https://pypi.org/project/urllib3/" _blank
    click wcmatch "https://pypi.org/project/wcmatch/" _blank
    click wcwidth "https://pypi.org/project/wcwidth/" _blank
    click ext_pytest_pytest "https://pypi.org/project/pytest/" _blank
    click grp_docs_pytest "https://pypi.org/project/pytest/" _blank

    style extra_platforms stroke-width:3px
    style click_extra stroke-width:3px
    style coverage stroke-width:3px
    style furo stroke-width:3px
    style myst_parser stroke-width:3px
    style pytest stroke-width:3px
    style pytest_cov stroke-width:3px
    style pytest_github_actions_annotate_failures stroke-width:3px
    style pytest_randomly stroke-width:3px
    style pytest_xdist stroke-width:3px
    style requests stroke-width:3px
    style sphinx stroke-width:3px
    style sphinx_autodoc_typehints stroke-width:3px
    style sphinx_copybutton stroke-width:3px
    style sphinx_design stroke-width:3px
    style sphinxcontrib_mermaid stroke-width:3px
    style sphinxext_opengraph stroke-width:3px
    style tomli stroke-width:3px
    style ext_pytest_pytest stroke-width:3px,stroke-dasharray:5 5
    style grp_docs_pytest stroke-width:3px,stroke-dasharray:5 5

    style ext_pytest fill:#7B1FA220,stroke:#BA68C8
    style grp_docs fill:#546E7A20,stroke:#90A4AE
    style grp_test fill:#546E7A20,stroke:#90A4AE

    

Test suite

Since extra-platforms > 13.3.1, the PyPI sdist ships tests/ and docs/, so the suite runs straight from the sdist. Earlier releases shipped no tests; those builds must start from a Git tag tarball instead.

A plain pytest run is friendly to a hermetic build sandbox:

• No coverage or xdist plugins are required. Coverage (--cov) and parallelism (--numprocesses, --dist) are passed by the project’s own CI workflow, not baked into addopts, so a from-source build needs neither pytest-cov nor pytest-xdist just to start pytest.

• Network tests are marked. Exclude them with -m "not network": the build sandbox has no outbound network.

• The wall-clock budget is marked. test_import_time asserts a cold import of the package stays under 2000 ms. No budget holds on every machine: an emulated or slow architecture fails it with no code regression. Alpine’s loongarch64 builder measured 2176 ms. Exclude it with -m "not benchmark".

• Environment-detection tests self-skip in hermetic builds. test_platform_detection and test_current_funcs read a real runtime environment (OS-release files, a shell, a terminal, a CI system) that a build sandbox does not provide, so they carry @skip_hermetic_build. That decorator fires whenever HOME=/homeless-shelter: the non-existent home directory Nix pioneered and GNU Guix inherited to seal a build off from the host.

• The Sphinx cross-reference test needs uv. tests/test_sphinx_crossrefs.py shells out to uv run sphinx-build, so it skips automatically when uv is not on PATH.

• The readme mindmap test needs click-extra. test_readme_mindmap_matches_its_generator imports extra_platforms._docs, which needs the docs-only click-extra package, so it skips automatically when click-extra is not installed.

The recommended invocation for a hermetic builder is therefore just:

$ pytest -m "not network and not benchmark"

No per-module ignore list is needed, and the selection stays correct as tests are added.

Test helpers for downstream projects

The extra_platforms.pytest module (installed with the [pytest] extra) exposes utilities that other packages’ test suites reuse:

• @skip_<trait> / @unless_<trait> decorators for every detected platform, architecture, shell, terminal, CI system and agent, including @skip_hermetic_build for tests that cannot run in a HOME=/homeless-shelter build sandbox.

• write_fake_executable(path, *, stdout="", stderr="", returncode=0) writes a portable fake command under a Python shebang (not #!/bin/sh), so a stand-in CLI a test drives through a real subprocess still execs in a sandbox that ships no /bin/sh.