Tutorial: Validating a Real Project¶

This tutorial walks through adding pytest-pep723 to a project that uses PEP 723 inline script metadata with a uv-based dispatcher. You will set up the plugin, configure it for your project, run it to find a real bug, and fix it.

Prerequisites¶

A Python project with PEP 723 scripts (files containing # /// script blocks)
uv and pytest installed
Basic familiarity with pyproject.toml

Step 1: Install the plugin¶

uv add --group dev pytest-pep723

Verify it loaded:

pytest --co -p pep723

You should see plugins: pep723-... in the output header.

Step 2: Identify your PEP 723 scripts¶

PEP 723 scripts contain an inline metadata block like:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "click",
#   "numpy",
#   "matplotlib",
# ]
# ///

Find them in your project:

grep -rl "# /// script" src/

Step 3: Configure the plugin¶

Add configuration to your pyproject.toml:

[tool.pytest.ini_options]
pep723_paths =
    src/mypkg

# Your own package -- it is importable but not a PyPI dep
pep723_ignore_imports =
    mypkg

# Conda-only deps that cannot be in PEP 723 blocks
#   (they are imported conditionally at runtime)
# pep723_ignore_imports =
#     ira_mod
#     tblite

# If your project uses packages where import != pip name
# pep723_extra_mappings =
#     gi=pygobject

Step 4: Run the check¶

pytest --pep723-check -v

Example output when everything passes:

tests/... PASSED
src/mypkg/tools/plot_data.py::pep723_deps PASSED
src/mypkg/tools/analyze.py::pep723_deps PASSED

3 passed in 0.05s

Step 5: Finding a real gap¶

Suppose you recently added import readcon to a script but forgot to update the inline deps. The plugin catches this:

FAILED src/mypkg/tools/plot_neb.py::pep723_deps
  PEP 723 script plot_neb.py has imports not covered by inline dependencies:
    Missing: readcon
    File: src/mypkg/tools/plot_neb.py

  Fix: add the missing package(s) to the # /// script dependencies block.

Step 6: Fix and verify¶

Edit the script’s inline metadata:

# /// script
# dependencies = [
#   "click",
#   "numpy",
#   "readcon>=0.7.0",  # <-- added
# ]
# ///

Re-run:

pytest --pep723-check -v

All green.

Step 7: Add to CI¶

Add --pep723-check to your CI test command. Example GitHub Actions:

- name: Check PEP 723 deps
  run: uv run pytest --pep723-check -m pep723

This runs only the PEP 723 checks (fast, no heavy deps needed).

Summary¶

You have:

Installed pytest-pep723
Configured scan paths and ignore lists
Run it to find a missing dependency
Fixed the gap
Added it to CI

The plugin now guards against the class of bugs where a developer adds an import to a PEP 723 script but forgets to declare it in the inline metadata block.