Polylith, hatchling, and exclude directives

[vEpiphyte]

I'm working on a monorepo migration with polylith ( and really liking it! ) and am focusing on packaging, with the goal of moving what was previously CI scripts and tools into hatching build hooks; so that developers can build wheels / images locally with as few hoops as possible. This will also make some of the CI processes cleaner as well.

One of these steps involves building in-line documentation for services ( which is a RST to markdown conversion process ).
These build artifacts are all included in VCS ignore files; and I have the project configured to include build artifacts from this process and excluding the original source; but when I build wheels I still get the original source files included in the wheel.

Is there a good pattern for using polylith with hatchling & excluding files from a brick? Or should I consider rewriting this entirely as a hatchling hook for finer control over these assets?

.gitignore snippet:

# package build artifacts
bases/example/*/assets/docs/_build/*.md
bases/example/*/assets/docs/_build/*.rst
bases/example/*/assets/docs/specialfile.rst

pyproject.toml file:

[build-system]
requires = [
    "hatchling",
    "hatch-polylith-bricks",
    "hatch-build-scripts",
    # Additional project specific libraries for building
    "somebuildhelper",
]
build-backend = "hatchling.build"

[project]
name = "example-project"
version = "0.1.0"
description = "example-project"
authors = [
  { name = 'vepiphyte'},
]

requires-python = ">=3.13"

classifiers = [
    "Private :: Do Not Upload",
    "Programming Language :: Python :: 3.13",
]
dependencies = [
    ...
]

[tool.hatch.build.targets.wheel]
packages = [
    "example.project"
]
artifacts = [
    "*/example/project/assets/docs/_build/*.md"
]
exclude = [
    "example/*/assets/docs/*.rst",
    "example/*/assets/docs/*.rst",
    "bases/example/*/assets/docs/_build/*.rst",
    "bases/example/*/assets/docs/_build/*.rst",
]

[tool.hatch.build.hooks.polylith-bricks]

[tool.polylith.bricks]
"../../bases/example/project" = "example/project"

[[tool.hatch.build.hooks.build-scripts.scripts]]
commands = [
    "PYTHONPATH='../../bases:../../components' python -m somebuildhelper.tools.buildpkg ../../bases/example/project/assets/somefile.yaml"
]

[DavidVujic]

Hi @vEpiphyte! I think that I have missed out on this scenario. The Polylith Hatch hook uses the force-include feature of Hatch, and maybe that overrides the exclude directive that you have configured.

I'll have a look on how to solve this (it shouldn't be too difficult). Thank you for sharing this and I'm happy that you like Polylith!

[DavidVujic]

Short update: I am working on a solution for this use case. It seems that the Hatch force_include feature that Polylith uses is overriding any exclude configurations.

I am developing a solution to this, by modifying the Polylith hatch hook and the way bricks are copied during packaging. Current work here: https://github.com/DavidVujic/python-polylith/pull/341/files

I will test this out, and will notify when there's a new release out!

[DavidVujic]

Another update 😄

There's a new version out of the hatch hook that will use the exclude patterns.
I have tried it successfully using hatch build and excluding a file in a similar way as your example. I would appreciate some help with testing this out, please let me know how it works 🙏

I will continue with adding support for it in uv (using the hatchling build backend) that for some reason won't pick up the patterns.

EDIT:
uv works too, when building a wheel only (using --wheel). Probably using the result from the built sdist when building both.

[vEpiphyte]

Hi David!

I just tested the latest release ( https://pypi.org/project/hatch-polylith-bricks/1.5.1/ ) and it did work!

I had to set the excludes like the following:

[tool.hatch.build.targets.wheel]
exclude = [
    "bases/example/*/assets/docs/*.rst",
    "bases/example/*/assets/docs/_build/*.rst",
]

Noting the bases or components path needs to be included would be useful if this gets documented down the road :)

[DavidVujic]

That's great! Yes, you need the full path, but I think you could replace "bases/" with a "*/". Maybe explicit is better, though.

It should also be possible to also write something shorter, like:

exclude = ["*/_build/*.rst"]

[DavidVujic]

Or, if you want to get rid of all ".rst" files in the subfolders of assets:

exclude = ["*/assets/**/*.rst"]

[vEpiphyte]

That smaller pattern works as well :)