Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 38 ยท Projects and Practice

Project: Package Health Checker

Build a package health checker that validates pyproject.toml metadata, version, requirements, classifiers and project layout, then wire it into pre-commit and CI as a release gate.

The last two projects built a package and a resolver. This one builds a release gate: a script that reads a project's pyproject.toml and file list and reports every problem it can find before you publish. It is the kind of tool teams write after the first embarrassing release: a missing license, a version that disagrees with the tag, a classifier that does not exist, an upper-bound pin that blocks every user.

You will use only the standard library plus packaging and trove-classifiers, the real list of valid PyPI classifiers. The checker runs here in the page; on your machine it becomes a command you call from pre-commit and CI.

What to check

Think about what hurts users or maintainers most, and split the checks by severity:

Severity Examples
Error (block the release) Missing name or version; invalid version; invalid requires-python; unparsable dependency; unknown classifier; missing license; entry point that is not module:function
Warning (discuss) Dependency with an upper bound such as <2; exact pin in a library; no readme; no project.urls; no py.typed for a typed package
Info Number of dependencies; supported Python range; presence of tests

Errors make the script exit with status 1; warnings are printed but do not fail CI unless you pass --strict.

The checker

Python Check a project's metadata

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the second report as a to-do list. Each message names the field and says what is wrong, which is what makes a checker pleasant to use.

Extending the checker

Ideas that fit the same structure:

  1. Tag check. Take the Git tag (v0.1.0) as an argument and fail if it differs from project.version (the release lesson showed the logic).
  2. Wheel contents. Open dist/*.whl with zipfile and check that py.typed, data files and the license are really inside. Fail if tests/ or .env slipped in.
  3. Lock freshness. Compare declared dependencies against the lock file and fail if they disagree.
  4. Python support matrix. Cross-check requires-python, classifiers and the CI matrix so they all claim the same versions.
  5. Banned patterns. Warn on direct URL dependencies (pkg @ git+https://...), which PyPI rejects in uploaded packages.
  6. Output formats. Emit JSON, or GitHub Actions annotations (::error file=pyproject.toml::message) so problems appear on the pull request.

Turn it into a tool

A check script becomes much more useful when it is a command in your tool belt:

TOML
[project.scripts]
pkg-health = "pkghealth.cli:main"
YAML
# .pre-commit-config.yaml
  - repo: local
    hooks:
      - id: pkg-health
        name: package health
        entry: pkg-health pyproject.toml
        language: system
        files: ^pyproject\.toml$
        pass_filenames: false
YAML
# in the CI workflow
      - run: uv run pkg-health --strict

In practice, several existing tools cover parts of this ground: twine check validates the long description, check-wheel-contents inspects wheel layout, validate-pyproject validates pyproject.toml against the official schema, and pyroma rates metadata quality. Knowing how to write your own check lets you enforce your team's rules on top of them.

Make checks cheap and specific. A release gate that takes ten seconds and prints one clear line per problem gets run; a slow one that dumps a long report gets skipped.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is an unknown classifier an error rather than a warning?

    PyPI validates classifiers against its list, so an unknown one makes the upload fail. Catching it earlier saves a failed release.
  2. 2. Which of these is best treated as a warning?

    Upper bounds are sometimes justified, so they deserve review but should not block a release. The others make the package unbuildable or unpublishable.
  3. 3. What should a checker's exit status be when it finds errors?

    Tools in pipelines communicate through exit codes; non-zero means failure.
  4. 4. What does tomllib.loads() raise for invalid TOML?

    Parsing errors raise TOMLDecodeError, which a checker can catch and report as a clear message.

Summary

  • A release gate reads metadata and files and reports errors, warnings and info; errors fail the run.
  • tomllib, packaging and trove-classifiers give you real parsing and validation without writing grammars.
  • Good messages name the field and the fix.
  • Run the checker in pre-commit and CI, and extend it with tag, wheel-content and lock-freshness checks.

Next: Practice: Packaging Problems and Fixes