hatch: "ValueError: At least one file selection option must be defined" error with hatchling-v1.19.0

Did hatchling-v1.19.0 introduce breaking changes? My project is suddenly failing to build with this error:

# pip install -U '.[dev]'
Processing project_dir
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... error
  error: subprocess-exited-with-error

  × Preparing metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [30 lines of output]
      Traceback (most recent call last):
        File "/usr/local/lib/python3.11/dist-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
          main()
        File "/usr/local/lib/python3.11/dist-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/usr/local/lib/python3.11/dist-packages/pip/_vendor/pyproject_hooks/_in_process/_in_process.py", line 152, in prepare_metadata_for_build_wheel
          whl_basename = backend.build_wheel(metadata_directory, config_settings)
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/build.py", line 58, in build_wheel
          return os.path.basename(next(builder.build(directory=wheel_directory, versions=['standard'])))
                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/plugin/interface.py", line 155, in build
          artifact = version_api[version](directory, **build_data)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/wheel.py", line 405, in build_standard
          for included_file in self.recurse_included_files():
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/plugin/interface.py", line 176, in recurse_included_files
          yield from self.recurse_selected_project_files()
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/plugin/interface.py", line 180, in recurse_selected_project_files
          if self.config.only_include:
             ^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/config.py", line 774, in only_include
          only_include = only_include_config.get('only-include', self.default_only_include()) or self.packages
                                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/wheel.py", line 231, in default_only_include
          self.set_default_file_selection()
        File "/tmp/pip-build-env-n8gm4qgc/overlay/local/lib/python3.11/dist-packages/hatchling/builders/wheel.py", line 209, in set_default_file_selection
          raise ValueError(message)
      ValueError: At least one file selection option must be defined, see: https://hatch.pypa.io/latest/config/build/
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

I tried the following workaround to revert the version to hatchling-v1.18.0, which fixed the error:

[build-system]
requires = ["hatchling<=1.18.0"]  
build-backend = "hatchling.build"

About this issue

Original URL
State: closed
Created 7 months ago
Reactions: 13
Comments: 25 (5 by maintainers)

Commits related to this issue

Pin hatchling to 1.18 We eventually need to update build settings to adjust to https://github.com/pypa/hatch/issues/1113. — committed to microsoft/qsharp by swernli 7 months ago
Fix hatchling build by adding required sections (#909) This adds the newly required sections to the hatchling build and making sure the right files get included in the wheel. See https://github.com/... — committed to microsoft/qsharp by swernli 7 months ago
tests: fix breaking change in hatch python package Hatch now throws an error if files are not selected are not supplied to wheel. This commit includes all python files to satisfy the new condition. ... — committed to golioth/golioth-firmware-sdk by szczys 7 months ago
tests: fix breaking change in hatch python package Hatch now throws an error if files are not selected are not supplied to wheel. This commit includes all python files to satisfy the new condition. ... — committed to golioth/golioth-firmware-sdk by szczys 7 months ago
Update build configuration for hatch v1.8.0 Issue discussed here: https://github.com/pypa/hatch/issues/1113 Also fixes the contents of builds! — committed to alan-turing-institute/nexus-allowlist by JimMadge 7 months ago
pin hatchling version because of https://github.com/pypa/hatch/issues/1113 with no better workaround apparent — committed to twosixlabs/armory-library by mwartell 7 months ago
Bump various test dependencies (#454) And fix editable installs, which have apparently been broken for us since the backwards-incompatible change to hatchling discussed in https://github.com/pypa/h... — committed to PyCQA/flake8-pyi by AlexWaygood 6 months ago
Fix package installation error due to hatchling-v1.19.0 See https://github.com/pypa/hatch/issues/1113 — committed to nusolar/SC7s by SinclaM 6 months ago
Workaround hatchling backwards incompatibility issue The root cause is documented here: https://github.com/pypa/hatch/issues/1113 — committed to tleyden/DALM by tleyden 5 months ago
Workaround hatchling backwards incompatibility issue (#86) The root cause is documented here: https://github.com/pypa/hatch/issues/1113 — committed to arcee-ai/DALM by tleyden 5 months ago
Fix hatch configuration. https://github.com/pypa/hatch/issues/1113 — committed to kklein/anki-csv by kklein 5 months ago

Most upvoted comments

Real life example of the new error 🙂 https://github.com/python/docs-community/actions/runs/7177951476/job/19545271892?pr=93#step:4:171

ofek on Dec 12, 2023

Yes certainly! The old behavior is:

[tool.hatch.build.targets.wheel]
include = ["*.py"]
exclude = ["test*"]

I’m embarrassed that I thought that was a good fallback. I kinda just copied what everyone else did for the fallback but in hindsight it should have always been an error to protect the user.

The new recommendation is simply to define any inclusion options you want. The most common will be packages, for example:

[tool.hatch.build.targets.wheel]
packages = ["src/foo"]

Of course, in the majority of cases configuration is unnecessary because the project name would fuzzy match the directory name.

ofek on Dec 11, 2023

Ah right, so we actually need this without a hyphen to get wheels containing source and not just metadata:

[tool.hatch.build.targets.wheel]
packages = ["sphinxlint"]

Thanks, this now makes it create wheels identical to those with Hatchling 1.18.

hugovk on Dec 11, 2023

I’m so sorry all of these errors are happening but it indicates to me that the users who asked for this were indeed correct and that people have been shipping wheels improperly in a subset of cases. In your case, the project name:

https://github.com/sphinx-contrib/sphinx-lint/blob/74db402328abca2bb1f1a72950b28ca1fee0d53c/pyproject.toml#L9

does not match the directory name (no hyphen) so as a fallback it tries every Python file that does not look like a test.

ofek on Dec 11, 2023

Yes, this is mentioned in the changelog: https://github.com/pypa/hatch/releases/tag/hatchling-v1.19.0.

An error will now be raised for the wheel target if no file selection options are defined

File selection options are documented here: https://hatch.pypa.io/latest/config/build/#file-selection

I’m wondering what exact rules apply, though. urllib3 does not seem to be affected as it defines include in [tool.hatch.build.targets.sdist] while rally-tracks is affected while defining exclude in [tool.hatch.build.targets.sdist], which looks like a file selection option. Is include needed in that case?

pquentin on Dec 11, 2023

I do understand that viewpoint and I went back and forth on whether or not to ship a new major version. I decided not to based on two factors:

I searched for uses of Hatchling on GitHub and it was <1% that actually pinned or had a version cap so this would not have helped very many people.
This is also a bug fix. What you don’t see in this issue is the dozens of other people that I had to help and also I’ve seen when searching for issues that experienced confusion about why their builds aren’t behaving as expected or even users complaining to the maintainers that the already-shipped distribution is incorrect.

I do however understand that this sucks, and for that I am genuinely sorry.

ofek on Dec 12, 2023

This should really be called out in the documentation under the build config, specifically as a change.

This was a breaking change, and should have been versioned as such.

jorng on Dec 12, 2023

Adding this fixes it:

[tool.hatch.build.targets.wheel]
packages = ["sphinx-lint"]

hugovk on Dec 11, 2023

This is specifically for the wheel target. Previously if projects were building wheels successfully then you were hitting the fall back and basically including every Python file found that doesn’t look like a test file. That I think is undesirable which is why there is now an error.

I will keep this open and improve that message to indicate that issue is specific to wheel config.

ofek on Dec 11, 2023