Add env lock command to generate PEP compliant lock files. by cjames23 · Pull Request #2216 · pypa/hatch

cjames23 · 2026-03-26T03:14:05Z

This PR replaces #2174 which had been closed due to having to delete my fork to get back to a clean state for creating a release.

The latest changes made ensure dependency-groups and extras are passed through for lockfile generation as well.

Closes #716 #749 #2176

Includes AI generated content.

flying-sheep · 2026-03-30T07:22:44Z

Awesome! I think the only thing missing is some tests of the actual lockfile, unless I’m missing something. E.g. that envs.some-env.dependencies end up in it and that that f14a893 works as expected.

gabrielsimoes · 2026-03-30T08:37:24Z

@flying-sheep @cjames23 firstly, thank you for your work here.

Are there plans to support generate_lockfile as a method in EnvironmentInterface so that plugins can implement custom behavior (e.g. populate [tool] with custom metadata)?

If this is not in the plans, would you be open to a contribution here? (once this PR merges of course) I can open another issue if this is best tracked separately.

cjames23 · 2026-03-30T22:24:28Z

Awesome! I think the only thing missing is some tests of the actual lockfile, unless I’m missing something. E.g. that envs.some-env.dependencies end up in it and that that f14a893 works as expected.

Nope not missing anything. I am working on those tests right now :) I was just getting the PR back open for us to continue discussing and iterating over it.

ofek · 2026-03-31T05:08:02Z

Are there plans to support generate_lockfile as a method in EnvironmentInterface so that plugins can implement custom behavior (e.g. populate [tool] with custom metadata)?

Perhaps useful for @cjames23 to know, there are other ways to go about implementing pluggable lock file support. I proposed a potential design in #355. The read/write methods would no longer be required though because I landed on a much better (imo) abstraction with the FileSystemContext as returned by an environment's EnvironmentInterface.fs_context method.

The idea was that if an environment interface exposed filesystem synchronization primitives then dependency lockers could merely use that and be its own type of plugin. I thought that it would be nice to have them decoupled, to a certain extent. Lockers would also call other environment methods that are part of the public API but I view that as way cleaner and easier to implement than a locker having to subclass an environment interface just to change a bit of logic.

This was years ago when I was in peak Hatch design mode so my gut instinct tells me that paradigm is directionally correct. However, I would prefer providing value to users sooner rather than later so it's totally your call! Whatever you do is fine by me; just let me know when to review 🙂

… UV/pip implementations, a shared lock coordinator (generate / in_sync / apply_lock), and new hatch dep lock, hatch dep sync, and hatch lock commands alongside existing hatch env lock.

ofek

Thanks! Feel free to merge after addressing the docs issues.

ofek · 2026-04-10T04:55:40Z

docs/how-to/environment/lockfiles.md

@@ -0,0 +1,150 @@
+# How to use lockfiles


This is a tutorial.

ofek · 2026-04-10T04:59:10Z

docs/plugins/environment/reference.md

+
+## Dependency lockers
+
+**Dependency lockers** are implemented: register classes with `hatch_register_locker` (see [Dependency locker plugins](../locker.md)). They stay **decoupled** from environment plugins—no subclassing [`EnvironmentInterface`](#hatch.env.plugin.interface.EnvironmentInterface) just to change locking—and call the environment’s **public API** (for example [`command_context`](#hatch.env.plugin.interface.EnvironmentInterface.command_context) and [`platform`](../utilities.md)).


The AI heavily over indexed on the comment I made and the associated discussion. Let's remove the second sentence so the docs overall make more sense here.

ofek · 2026-04-10T05:03:20Z

docs/plugins/locker.md

+## Interface
+
+Implement [`LockerInterface`](https://github.com/pypa/hatch/blob/master/src/hatch/env/lockers/interface.py) with:
+
+- `PLUGIN_NAME: str` — selector (`uv`, `pip`, or your plugin name).
+- `supports(environment) -> bool`
+- `generate(environment, dependencies: list[str], output_path, *, upgrade=..., layered=..., lock_extras=..., lock_groups=..., upgrade_packages=...)`
+- `in_sync(environment, dependencies: list[str], output_path, *, same flags as generate) -> bool`
+- `apply_lock(environment, lock_path)`
+- Optional override: `install_matches_lock(environment, lock_path) -> bool` for `dependencies_in_sync` when `locked` (default `True`; UV uses `uv pip sync --dry-run`).


This section I think is entirely out of place and doesn't match the flow of the other plugin pages. We should remove this I think.

Also, we shouldn't link to source code directly with URLs.

ofek · 2026-04-10T05:07:37Z

docs/plugins/locker.md

+## Conceptual mapping
+
+| Idea | Hatch |
+| ---- | ----- |
+| `generate(dependencies: list[str])` → resolve → persist | `generate(environment, dependencies, output_path, *, …)` — orchestrator supplies merged PEP 508 lines plus layered flags (`lock_extras`, `lock_groups`, `upgrade`, …). |
+| `in_sync(dependencies) -> bool` | `in_sync(environment, dependencies, output_path, *, …) -> bool` |
+| `write_file` / `read_file` on the environment | Lockfiles normally live on the project root: read/write `output_path` ([`Path`](../plugins/utilities.md)). For remote or isolated storage, use [`fs_context`](../plugins/environment/reference.md#hatch.env.plugin.interface.EnvironmentInterface.fs_context) to stage paths and `sync_local` / `sync_env` before or after resolver commands. |
+| `run_shell_command` under `command_context` | Run resolver/install commands inside `with environment.command_context():` using `environment.platform.check_command` / `run_command` (same pattern as built-in lockers). |
+| Apply resolved graph to the environment | `apply_lock(environment, lock_path)` — e.g. `uv pip sync` for the UV locker. |


This also doesn't really flow but I'm kinda at a loss because either AI assists and reduces the quality of the documentation or we just aren't able to land features due to time constraints we have in real life.

Note to self that we need to add AI instructions to the repo for better alignment.

ofek · 2026-04-10T05:13:05Z

src/hatch/env/lockers/interface.py

+        upgrade: bool = False,
+        upgrade_packages: tuple[str, ...] = (),
+        layered: bool = False,
+        lock_extras: tuple[str, ...] = (),
+        lock_groups: tuple[str, ...] = (),


I'm fine with merging but do you think we should hold off on adding so many options until we get feedback on the workflow?

ofek · 2026-04-10T05:17:34Z

src/hatch/env/lock.py

+    )
+
+
+verify_lockfile = lockfile_in_sync  # design-doc name for :func:`lockfile_in_sync`


What's the comment?

ofek · 2026-04-10T05:20:27Z

tests/conftest.py

+
+    stub_pylock = "lock-version = 1\n"
+
+    def fake_subprocess_run(cmd, *_args, **_kwargs) -> subprocess.CompletedProcess:


I feel like there must be a less invasive approach for this subset of tests.

let me think on this one a bit more. This was the first thing that came to mind.

cjames23 added 7 commits February 6, 2026 15:17

Add env lock command to generate PEP compliant lock files.

16d4727

Fix formatting issues

d13708e

Move to per environment config of lockfiles

0dc6524

Move to export-all, adjust docs, dedupe based on lock-filename

4de406a

Change to usefixture for helpers for lock tests

6398044

Ensure all dependencies are included in lock

f14a893

Merge branch 'master' into env-lock-feature

f731958

This was referenced Mar 26, 2026

Add env lock command to generate PEP compliant lock files. #2174

Closed

Add support for pylock.toml (PEP 751) #2176

Open

cjames23 added 2 commits March 29, 2026 15:27

Fix list transformation

c1529e0

Fix formatting

77bda0e

cjames23 mentioned this pull request Mar 30, 2026

Feature request: Support dependency hashing #716

Closed

cjames23 added 2 commits March 30, 2026 17:14

Add regression tests that confirm functionality

bddcd77

Merge branch 'master' into env-lock-feature

cebd303

cjames23 added 7 commits March 31, 2026 18:57

dd pluggable dependency lockers (hatch_register_locker) with built-in…

40bc0a4

… UV/pip implementations, a shared lock coordinator (generate / in_sync / apply_lock), and new hatch dep lock, hatch dep sync, and hatch lock commands alongside existing hatch env lock.

Fix formatting and type issues

11953e9

Remove links to github discussion

f7241ec

Fix link

a4124ad

Merge branch 'master' into env-lock-feature

3f0b01c

Address issue with pip locker and apply_lock

9a4bf49

Fix formatting

dfa0adb

ofek approved these changes Apr 10, 2026

View reviewed changes


		## Dependency lockers

		Dependency lockers are implemented: register classes with `hatch_register_locker` (see [Dependency locker plugins](../locker.md)). They stay decoupled from environment plugins—no subclassing [`EnvironmentInterface`](#hatch.env.plugin.interface.EnvironmentInterface) just to change locking—and call the environment’s public API (for example [`command_context`](#hatch.env.plugin.interface.EnvironmentInterface.command_context) and [`platform`](../utilities.md)).

		)


		verify_lockfile = lockfile_in_sync # design-doc name for :func:`lockfile_in_sync`


		stub_pylock = "lock-version = 1\n"

		def fake_subprocess_run(cmd, _args, *_kwargs) -> subprocess.CompletedProcess:

Uh oh!

Conversation

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

Uh oh!

Uh oh!

flying-sheep commented Mar 30, 2026

Uh oh!

gabrielsimoes commented Mar 30, 2026

Uh oh!

cjames23 commented Mar 30, 2026

Uh oh!

ofek commented Mar 31, 2026

Uh oh!

ofek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cjames23 commented Mar 26, 2026 •

edited

Loading