Hatch Fancy PyPI README

25.1.0 · active · verified Thu Apr 09

Hatch Fancy PyPI README is a Hatch plugin that enables dynamic and enhanced README generation for your Python packages. It allows you to combine multiple files, use Jinja templating, and perform other transformations to create a rich PyPI README. The current version is 25.1.0, and it is actively maintained as part of the Hatch project, with frequent updates.

Warnings

breaking The configuration for `hatch-fancy-pypi-readme` underwent a breaking change in version `21.0.0`. Older configurations using `[tool.hatch.build.hooks.fancy-readme]` are no longer supported.
Fix: Migrate your `pyproject.toml` to use the `project.readme` table with `checker = "fancy"` and subsequent configuration under `[tool.hatch.build.targets.sdist.hooks.fancy-pypi-readme]`, as shown in the quickstart example.
gotcha Improper `pyproject.toml` configuration, especially around the `project.readme` table and the `[tool.hatch.build.targets.sdist.hooks.fancy-pypi-readme]` section, is a common source of errors. Ensure syntax is correct and all required fields are present.
Fix: Carefully review the official documentation and examples for correct `pyproject.toml` structure. Pay close attention to the `checker = "fancy"` setting and the nested `tool.hatch` sections.
gotcha Errors in Jinja templates (e.g., syntax errors, referencing non-existent variables) or listing non-existent files in the `files` configuration will cause the build process to fail. Debugging templating issues can sometimes be challenging.
Fix: Thoroughly test your Jinja templates with sample data. Ensure all files referenced in `files` or within the template actually exist at build time. Use simpler templates initially and progressively add complexity.

Install

pip install hatch-fancy-pypi-readme hatch Install

Quickstart

This quickstart demonstrates how to use `hatch-fancy-pypi-readme` to combine `README.md` and `CHANGELOG.md` into a single, templated PyPI README. First, ensure `hatch` is installed. Then, create the specified `pyproject.toml`, `README.md`, and `CHANGELOG.md` files within your project directory. Finally, run `hatch build` to generate your package distributions with the fancy README.

# 1. Create a project directory, e.g., 'my_fancy_package'
# 2. Inside 'my_fancy_package', create these files:

# pyproject.toml
# --------------------------------------------------
# [build-system]
# requires = ["hatchling>=1.18.0", "hatch-fancy-pypi-readme==25.1.0"]
# build-backend = "hatchling.build"
# 
# [project]
# name = "my-fancy-package"
# version = "0.1.0"
# description = "A package with a fancy README"
# authors = [{ name = "Agent", email = "agent@example.com" }]
# readme = { file = "README.md", content-type = "text/markdown", checker = "fancy" }
# 
# [tool.hatch.build.targets.sdist.hooks.fancy-pypi-readme]
# files = ["README.md", "CHANGELOG.md"]
# template = "# {{ project.name }} - v{{ project.version }}\n\n" \
#            "## Main README\n{{ files['README.md'] }}\n\n" \
#            "## Changelog\n{{ files['CHANGELOG.md'] }}"
# --------------------------------------------------

# README.md
# --------------------------------------------------
# This is the primary README content for my package.
# It will be combined with other files by hatch-fancy-pypi-readme.
# --------------------------------------------------

# CHANGELOG.md
# --------------------------------------------------
# ### 0.1.0
# - Initial release with fancy README generation.
# - Added support for combining README and CHANGELOG.
# --------------------------------------------------

# 3. Navigate to the 'my_fancy_package' directory in your terminal.
# 4. Run the build command:
# hatch build

# After building, you will find the generated sdist and wheel files
# in the 'dist/' directory, with the README correctly templated.

view raw JSON →