Add `--build-backend` option to `usethis init` by Copilot · Pull Request #1469 · usethis-python/usethis-python

Copilot · 2026-03-22T19:06:47Z

The usethis init command hardcoded hatch as the build backend with no way for users to choose an alternative like uv_build.

Adds a --build-backend CLI option supporting hatch (default) and uv as build backends.

$ usethis init --build-backend uv

Changes

BuildBackendEnum (src/usethis/_types/build_backend.py) — new enum with hatch and uv values
UsethisConfig — added build_backend field (default: hatch) with save/restore in set() context manager
opinionated_uv_init() / ensure_pyproject_toml_via_uv() — read usethis_config.build_backend instead of hardcoding "hatch"
ensure_pyproject_toml() for backend=none — uses a _BUILD_SYSTEM_CONFIG mapping to generate correct [build-system] for any backend; hatch-specific [tool.hatch.build] config now conditional on build_backend is hatch
CLI — --build-backend option wired through init() → usethis_config.set(build_backend=...)
Docs — docs/cli/reference.md updated with possible values
Tests — added TestBuildSystemConfig::test_keys_match_enum to verify _BUILD_SYSTEM_CONFIG keys stay in sync with BuildBackendEnum members
next_breaking_version() (src/usethis/_fallback.py) — generic semver helper extracted from next_breaking_uv_version(); next_breaking_uv_version() now delegates to it
FALLBACK_HATCHLING_VERSION (src/usethis/_fallback.py) — new constant set to 1.29.0
_BUILD_SYSTEM_CONFIG — version bounds now computed dynamically using FALLBACK_UV_VERSION / FALLBACK_HATCHLING_VERSION with next_breaking_version() instead of hard-coded strings
Tests — added TestFallbackHatchlingVersion (up-to-dateness) and TestNextBreakingVersion (unit tests for generic helper)

Original prompt

This section details on the original issue you should resolve

<issue_title>Support --build-backend in usethis init</issue_title>
<issue_description>When initializing a project with a subprocess call to uv, I'm not sure yet whether the new uv_build backend is a sensible default option (versus the currently hard-coded hatch

When it comes to the default, I think there might be some disagreements about whether to use hatch or uv. In any case, this is a major decision, and it would be good to give the user some freedom.

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Support --build-backend in usethis init #847

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Add a new --build-backend CLI option that allows users to choose which build backend to use when initializing a project. Supported values match those of uv init --build-backend: hatch (default), uv, flit, pdm, setuptools, maturin, scikit, and poetry. The build backend is stored in usethis_config and used by both the uv backend (passed through to uv init --build-backend) and the none backend (generates appropriate [build-system] config in pyproject.toml). Closes #347 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/3d692c70-3b16-43c5-bd5a-8fdc2463c5f9

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/3d692c70-3b16-43c5-bd5a-8fdc2463c5f9

src/usethis/_types/build_backend.py

src/usethis/_init.py

…ehensiveness test Reduce BuildBackendEnum to only hatch and uv for simpler maintenance. Remove tests for flit/setuptools/poetry/etc backends. Add TestBuildSystemConfig::test_keys_match_enum to verify _BUILD_SYSTEM_CONFIG keys stay in sync with BuildBackendEnum members. Update docs/cli/reference.md to only list hatch and uv. Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/69842fd3-e51b-4d58-9bd1-fd5136923fd9

nathanjmcdougall · 2026-03-24T04:05:25Z

src/usethis/_init.py

+from usethis._types.build_backend import BuildBackendEnum
+
+_BUILD_SYSTEM_CONFIG: dict[BuildBackendEnum, tuple[list[str], str]] = {
+    BuildBackendEnum.hatch: (["hatchling"], "hatchling.build"),


I think I want to use the fallback versions here. We will need some logic for getting the next breaking uv release, next breaking hatchling release, etc.

@copilot please add use the FALLBACK_UV_VERSION incl. next_breaking_uv_version rather than hard-coding here.

Likewise for hatch please add a FALLBACK_HATCHLING_VERSION and set it to 1.29.0 and write a next_breaking_hatchling_version and put it in the same module as next_breaking_uv_version. It should probably share the same implementation as next_breaking_uv_version so make a next_breaking_version helper.

Make sure to add appropriate tests

Done in 520b090. Added FALLBACK_HATCHLING_VERSION = "1.29.0" and a generic next_breaking_version() helper in _fallback.py. next_breaking_uv_version() now delegates to it. _BUILD_SYSTEM_CONFIG uses FALLBACK_UV_VERSION/FALLBACK_HATCHLING_VERSION with next_breaking_version() for dynamic bounds. Tests added for both (TestFallbackHatchlingVersion, TestNextBreakingVersion).

codecov · 2026-03-25T00:29:39Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

…ystem config - Add FALLBACK_HATCHLING_VERSION = "1.29.0" to _fallback.py - Extract next_breaking_version() generic helper into _fallback.py - Refactor next_breaking_uv_version() to delegate to next_breaking_version() - Update _BUILD_SYSTEM_CONFIG to use FALLBACK_UV_VERSION, FALLBACK_HATCHLING_VERSION and next_breaking_version() instead of hard-coded version bounds - Add TestFallbackHatchlingVersion and TestNextBreakingVersion tests Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/0ab118f5-5448-457b-a6aa-6740f6b46a5d

codspeed-hq · 2026-03-25T00:30:21Z

Merging this PR will not alter performance

✅ 2 untouched benchmarks

_{Comparing copilot/support-build-backend-usethis-init (520b090) with main (955929a)}

Initial plan

29b8d71

Copilot AI assigned Copilot and nathanjmcdougall Mar 22, 2026

Copilot started work on behalf of nathanjmcdougall March 22, 2026 19:14 View session

Copilot AI and others added 2 commits March 22, 2026 19:24

style: apply formatting fixes from static checks

cb34f5f

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/3d692c70-3b16-43c5-bd5a-8fdc2463c5f9

Copilot AI changed the title ~~[WIP] Support --build-backend in usethis init~~ Add --build-backend option to usethis init Mar 22, 2026

Copilot AI requested a review from nathanjmcdougall March 22, 2026 19:28

Copilot finished work on behalf of nathanjmcdougall March 22, 2026 19:28

nathanjmcdougall requested changes Mar 24, 2026

View reviewed changes

src/usethis/_types/build_backend.py Show resolved Hide resolved

src/usethis/_init.py Show resolved Hide resolved

Copilot started work on behalf of nathanjmcdougall March 24, 2026 03:58 View session

nathanjmcdougall mentioned this pull request Mar 24, 2026

Configure agent skills to encourage appropriate style when working with enums #1479

Closed

Copilot AI requested a review from nathanjmcdougall March 24, 2026 04:02

Copilot finished work on behalf of nathanjmcdougall March 24, 2026 04:02

nathanjmcdougall reviewed Mar 24, 2026

View reviewed changes

nathanjmcdougall mentioned this pull request Mar 24, 2026

Move all hard-coded version constants into a central module #1480

Closed

Copilot AI mentioned this pull request Mar 24, 2026

Move all hard-coded version constants into a central _fallback module #1481

Merged

nathanjmcdougall mentioned this pull request Mar 24, 2026

Create a function to take a uv version and find the next breaking version #1482

Closed

This was referenced Mar 24, 2026

Add next_breaking_uv_version function #1483

Merged

Add usethis-python-enum agent skill and dict comprehensiveness test #1492

Merged

Merge branch 'main' into copilot/support-build-backend-usethis-init

d1f6ce6

nathanjmcdougall temporarily deployed to codecov March 25, 2026 00:22 — with GitHub Actions Inactive

Copilot started work on behalf of nathanjmcdougall March 25, 2026 00:25 View session

Copilot finished work on behalf of nathanjmcdougall March 25, 2026 00:34

Copilot AI temporarily deployed to codecov March 25, 2026 00:51 Inactive

nathanjmcdougall approved these changes Mar 25, 2026

View reviewed changes

nathanjmcdougall marked this pull request as ready for review March 25, 2026 00:54

nathanjmcdougall merged commit ca2f097 into main Mar 25, 2026
20 checks passed

nathanjmcdougall deleted the copilot/support-build-backend-usethis-init branch March 25, 2026 01:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `--build-backend` option to `usethis init`#1469

Add `--build-backend` option to `usethis init`#1469
nathanjmcdougall merged 6 commits intomainfrom
copilot/support-build-backend-usethis-init

Copilot AI commented Mar 22, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

nathanjmcdougall Mar 24, 2026

Uh oh!

nathanjmcdougall Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

codecov bot commented Mar 25, 2026

Uh oh!

codspeed-hq bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Copilot AI commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Comments on the Issue (you are @copilot in this section)

Uh oh!

Uh oh!

Uh oh!

nathanjmcdougall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

nathanjmcdougall Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 25, 2026

Codecov Report

Uh oh!

codspeed-hq bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Mar 22, 2026 •

edited

Loading

codspeed-hq bot commented Mar 25, 2026 •

edited

Loading