Prepare Python SDK for CLI 1.0 init contract

Mirror the Go SDK's CLI 1.0 init-contract preparation (dagger/go-sdk#2)
for the Python SDK:

- add `targetRuntime` returning "python" so modules initialized through
  this SDK target the built-in Python runtime
- replace `init` with `initModule(ws, name, path, template, pythonVersion,
  useUv, baseImage)` that returns only the Python-owned template files; the
  engine owns dagger.json / dagger-module.toml and workspace config and
  merges this changeset with its own bookkeeping
- remove the SDK-owned `mod deps` / `mod engine` command surfaces, now
  owned by the core CLI (`dagger module deps` / `dagger module engine`)
- mark the `modules` / `generate-all` discovery path as legacy dagger.json
  discovery, obsolete for workspace-managed modules
- update the e2e checks and README to match

The Python build-config surface (`mod config`) stays in this module, as it
is genuinely SDK-specific. `initClient` is intentionally out of scope:
generating a Python client is a code-generator concern, mirroring the Go
SDK which stays module-only.

Signed-off-by: Yves Brissaud <yves@dagger.io>

Author: eunomie

.dagger/modules/e2e/main.dang

@@ -57,16 +57,6 @@ type E2e {
     assert(value.contains(want) == false, message)
   }
 
-  """
-  Assert that a dependency edit modified only dagger.json.
-  """
-  let assertOnlyConfigChanged(changes: Changeset!, path: String!): Void {
-    assert(contains(changes.modifiedPaths, path), "dependency edit did not modify dagger.json")
-    assert(changes.modifiedPaths.length == 1, "dependency edit modified more than dagger.json")
-    assert(changes.addedPaths.length == 0, "dependency edit should not add generated files")
-    assert(changes.removedPaths.length == 0, "dependency edit should not remove generated files")
-  }
-
   """
   The helper should expose the generate skip marker used by callers.
   """
@@ -90,30 +80,27 @@ type E2e {
   }
 
   """
-  Init should seed template files without running codegen. Generated SDK files
-  appear later via mod.generate.
+  initModule should seed SDK-owned template files without running codegen and
+  without writing engine-owned files (dagger.json / dagger-module.toml).
+  Generated SDK files appear later via mod.generate.
   """
   pub initCheck(ws: Workspace!): Void @check {
     let defaultPath = outputRoot + "/init-default"
-    let ignoredPath = outputRoot + "/init-ignore-generated"
     let legacyPath = outputRoot + "/init-legacy"
 
-    let defaultChanges = pythonSdk.init(ws, name: "init-default", path: defaultPath)
-    let ignoredChanges = pythonSdk.init(ws, name: "init-ignore-generated", path: ignoredPath, ignoreGenerated: true)
-    let legacyChanges = pythonSdk.init(ws, name: "init-legacy", path: legacyPath, template: "legacy")
+    let defaultChanges = pythonSdk.initModule(ws, name: "init-default", path: defaultPath)
+    let legacyChanges = pythonSdk.initModule(ws, name: "init-legacy", path: legacyPath, template: "legacy")
 
-    assertAdded(defaultChanges, defaultPath + "/dagger.json")
     assertAdded(defaultChanges, defaultPath + "/pyproject.toml")
+    assert(contains(defaultChanges.addedPaths, defaultPath + "/dagger.json") == false, "initModule should not write the engine-owned dagger.json")
     assert(contains(defaultChanges.addedPaths, defaultPath + "/" + generatedMarkerPath) == false, "init should not produce SDK-generated files")
     assert(defaultChanges.modifiedPaths.length == 0, "init unexpectedly modified existing files")
     assert(defaultChanges.removedPaths.length == 0, "init unexpectedly removed files")
-    assertContains(defaultChanges.layer.file(defaultPath + "/dagger.json").contents, "\"automaticGitignore\": false", "default init should check in generated files")
     assertContains(defaultChanges.layer.file(defaultPath + "/src/init_default/__init__.py").contents, "class InitDefault:", "minimal template did not render the module type")
     assertContains(defaultChanges.layer.file(defaultPath + "/src/init_default/__init__.py").contents, "source: dagger.Directory", "minimal template did not declare a Directory source field")
     assertContains(defaultChanges.layer.file(defaultPath + "/src/init_default/__init__.py").contents, "def __init__(self, ws: dagger.Workspace)", "minimal template did not declare a Workspace constructor")
     assertContains(defaultChanges.layer.file(defaultPath + "/src/init_default/__init__.py").contents, "self.source = ws.directory(\"/\")", "minimal template constructor did not assign ws.directory to source")
 
-    assertContains(ignoredChanges.layer.file(ignoredPath + "/dagger.json").contents, "\"automaticGitignore\": true", "ignoreGenerated init should configure automatic .gitignore output")
     assertContains(legacyChanges.layer.file(legacyPath + "/src/init_legacy/main.py").contents, "class InitLegacy:", "legacy template did not render the module type")
 
     null
@@ -161,66 +148,10 @@ type E2e {
   }
 
   """
-  Engine version helpers should read dagger.json and write normalized versions.
-  """
-  pub engineVersionCheck(ws: Workspace!): Void @check {
-    let engine = pythonSdk.mod(ws, path: lookupModulePath).engine
-    let fixed = engine.require(version: "0.21.0")
-    let latest = engine.requireLatest
-
-    assert(engine.required == "0.20.8", "engine.required should trim a leading v")
-    assertContains(fixed.layer.file(lookupModulePath + "/dagger.json").contents, "\"engineVersion\": \"v0.21.0\"", "engine.require should write a normalized version")
-    assertContains(latest.layer.file(lookupModulePath + "/dagger.json").contents, "\"engineVersion\": \"latest\"", "engine.requireLatest should write latest")
-
-    null
-  }
-
-  """
-  Dependency listing should preserve how users identify dependencies: string
-  entries return their source, named object entries return their name.
-  """
-  pub dependencyListCheck(ws: Workspace!): Void @check {
-    let deps = pythonSdk.mod(ws, path: depsModulePath).deps.list
-
-    assert(contains(deps, "../dep-string"), "string dependency source was not listed")
-    assert(contains(deps, "dep-named"), "named dependency was not listed")
-    assert(contains(deps, "../dep-source-only"), "source-only dependency was not listed by source")
-
-    null
-  }
-
-  """
-  Dependency edits should update only dagger.json. Users run generate
-  separately when they want generated SDK files refreshed.
+  The SDK should report the builtin runtime that modules it authors target.
   """
-  pub dependencyEditCheck(ws: Workspace!): Void @check {
-    let deps = pythonSdk.mod(ws, path: depsModulePath).deps
-
-    let added = deps.add(source: "../dep-new")
-    assertOnlyConfigChanged(added, depsModulePath + "/dagger.json")
-    let addedConfig = added.after.file(depsModulePath + "/dagger.json").contents
-    assertContains(addedConfig, "\"../dep-new\"", "adding an unnamed dependency did not keep its source")
-    assertNotContains(addedConfig, "\"name\": \"dep-new\"", "adding an unnamed dependency should not load the module to discover its name")
-
-    let named = deps.add(source: "../dep-new", name: "dep-alias")
-    assertOnlyConfigChanged(named, depsModulePath + "/dagger.json")
-    let namedConfig = named.after.file(depsModulePath + "/dagger.json").contents
-    assertContains(namedConfig, "\"name\": \"dep-alias\"", "adding a named dependency did not keep the requested name")
-    assertContains(namedConfig, "\"source\": \"../dep-new\"", "adding a named dependency did not keep its relative source")
-
-    let removed = deps.remove(name: "dep-named")
-    assertOnlyConfigChanged(removed, depsModulePath + "/dagger.json")
-    let removedConfig = removed.after.file(depsModulePath + "/dagger.json").contents
-    assertNotContains(removedConfig, "\"name\": \"dep-named\"", "removing a named dependency left it in dagger.json")
-
-    let sourceRemoved = deps.remove(name: "../dep-source-only")
-    assertOnlyConfigChanged(sourceRemoved, depsModulePath + "/dagger.json")
-    let sourceRemovedConfig = sourceRemoved.after.file(depsModulePath + "/dagger.json").contents
-    assertNotContains(sourceRemovedConfig, "\"source\": \"../dep-source-only\"", "removing by source left the dependency in dagger.json")
-    assertContains(sourceRemovedConfig, "\"name\": \"dep-named\"", "removing by source removed a different dependency")
-
-    let updated = deps.update
-    assert(updated.isEmpty, "updating only local dependencies should not edit dagger.json")
+  pub targetRuntimeCheck: Void @check {
+    assert(pythonSdk.targetRuntime == "python", "targetRuntime should be the python builtin runtime")
 
     null
   }
@@ -276,7 +207,7 @@ type E2e {
     let configuredPath = outputRoot + "/init-configured"
     let defaultPath = outputRoot + "/init-config-default"
 
-    let configured = pythonSdk.init(ws, name: "init-configured", path: configuredPath, pythonVersion: "3.13", useUv: false, baseImage: "python:3.13-slim")
+    let configured = pythonSdk.initModule(ws, name: "init-configured", path: configuredPath, pythonVersion: "3.13", useUv: false, baseImage: "python:3.13-slim")
     let pyproj = configuredPath + "/pyproject.toml"
     assertAdded(configured, pyproj)
     assert(configured.modifiedPaths.length == 0, "configured init should not modify existing files")
@@ -286,7 +217,7 @@ type E2e {
     assertContains(configured.layer.file(pyproj).contents, "python:3.13-slim", "init --base-image not written")
     assertContains(configured.layer.file(pyproj).contents, "dagger-io", "init config dropped template data")
 
-    let default = pythonSdk.init(ws, name: "init-config-default", path: defaultPath)
+    let default = pythonSdk.initModule(ws, name: "init-config-default", path: defaultPath)
     let defaultPyproj = defaultPath + "/pyproject.toml"
     assertContains(default.layer.file(defaultPyproj).contents, ">=3.14", "default init should keep the template python version")
     assertNotContains(default.layer.file(defaultPyproj).contents, "use-uv", "default init should not write use-uv")

README.md

@@ -2,9 +2,13 @@
 
 A Dagger module for managing Dagger modules that use the Python SDK.
 
-The Dagger CLI ships without built-in module-management commands like
-`init` or `develop`. Those operations live in SDK-specific modules like this
-one, called through `dagger call`.
+SDK-specific module authoring (scaffolding new modules, language build config,
+codegen) lives in modules like this one. Under the CLI 1.0 init contract the
+engine drives the SDK: this module exposes `initModule` and `targetRuntime`,
+and the engine merges the SDK-owned files with its own workspace bookkeeping.
+Shared, language-agnostic operations — editing a module's dependencies or its
+required engine version — are owned by the core CLI (`dagger module deps`,
+`dagger module engine`) and are no longer part of this module's surface.
 
 Backed by [`github.com/dagger/sdk-sdk/polyfill`](https://github.com/dagger/sdk-sdk/tree/main/polyfill).
 
@@ -23,42 +27,39 @@ before writing anything to your workspace.
 
 ## Create a new module
 
-Create a Python SDK module under the nearest `.dagger/modules/<name>/`:
+With a CLI that supports the 1.0 init contract, the engine dispatches to this
+SDK's `initModule`:
 
 ```sh
-dagger call python-sdk init --name my-module
+dagger module init python my-module
 ```
 
-Pick a different location:
+`initModule` only seeds the SDK-owned template files; the engine writes the
+module config and workspace entries. Run `generate` afterwards to produce the
+generated SDK bindings.
 
-```sh
-dagger call python-sdk init --name my-module --path some/dir/my-module
-```
-
-Pick a starter template (`minimal` is the default; `legacy` gives you a
-container-echo example):
+The SDK-specific args below become typed flags on `dagger module init python`:
 
 ```sh
-dagger call python-sdk init --name my-module --template legacy
+dagger module init python my-module --template legacy
+dagger module init python my-module \
+    --python-version 3.13 \
+    --use-uv=false \
+    --base-image python:3.13-slim
 ```
 
-`init` only seeds template files. Run `mod ... generate` to produce the
-generated SDK.
-
-### Configure a module at creation
+`--template` picks a starter template (`minimal` is the default; `legacy` gives
+you a container-echo example). The three `pyproject.toml` flags are optional; by
+default the template's Python version is used, uv is enabled, and no base image
+override is written.
 
-`init` accepts configuration flags written into the module's `pyproject.toml`:
+You can also call the function directly for testing. `path` is required (the
+engine supplies it in the dispatched path):
 
 ```sh
-dagger call python-sdk init --name my-module \
-    --python-version 3.13 \
-    --use-uv=false \
-    --base-image python:3.13-slim
+dagger call python-sdk init-module --name my-module --path .dagger/modules/my-module
 ```
 
-All three are optional. By default the template's Python version is used, uv is
-enabled, and no base image override is written.
-
 ## Configure an existing module
 
 Read the current configuration. Settings that are not explicitly written to
@@ -101,55 +102,14 @@ For every Python SDK module in the workspace (skipping any with a
 dagger call python-sdk generate-all
 ```
 
-## Manage dependencies
+## Manage dependencies and the engine version
 
-List:
+Editing a module's dependencies or its required engine version is identical
+across SDKs, so the core CLI owns it:
 
 ```sh
-dagger call python-sdk mod --path my-module deps list
-```
-
-Add (run `mod ... generate` after to refresh generated SDK files):
-
-```sh
-dagger call python-sdk mod --path my-module \
-    deps add --source github.com/some/module
-```
-
-Add with a custom local name:
-
-```sh
-dagger call python-sdk mod --path my-module \
-    deps add --source github.com/some/module --name alias
-```
-
-Remove by name or source:
-
-```sh
-dagger call python-sdk mod --path my-module deps remove --name alias
-```
-
-Update one remote dependency, or all of them:
-
-```sh
-dagger call python-sdk mod --path my-module deps update
-dagger call python-sdk mod --path my-module deps update --name some-dep
-```
-
-## Manage the required engine version
-
-```sh
-# Read the version pinned in dagger.json
-dagger call python-sdk mod --path my-module engine required
-
-# Pin to a specific version
-dagger call python-sdk mod --path my-module engine require --version 0.20.8
-
-# Pin to the engine version you're currently running
-dagger call python-sdk mod --path my-module engine require-current
-
-# Pin to "latest"
-dagger call python-sdk mod --path my-module engine require-latest
+dagger module deps add github.com/some/module
+dagger module engine require-latest
 ```
 
 ## Discover modules in a workspace
@@ -159,6 +119,12 @@ dagger call python-sdk mod --path my-module engine require-latest
 dagger call python-sdk modules path
 ```
 
+> [!NOTE]
+> `modules` and `generate-all` discover modules by scanning legacy
+> `dagger.json` files for `sdk.source == "python"`. This is obsolete for
+> workspace-managed modules, where the engine owns the
+> `modules.<sdk>.as-sdk.modules` source of truth.
+
 See [`python-sdk.dang`](./python-sdk.dang) for the full type surface.
 
 ## Skipping generation