From 118067844cc8bc128df72930a3b952e4380b36b7 Mon Sep 17 00:00:00 2001
From: Guillaume de Rouville <guillaume@dagger.io>
Date: Wed, 22 Jul 2026 14:01:59 -0700
Subject: [PATCH 1/3] feat: add a useful default Python template

`dagger module init python` currently generates an empty object. It is a
valid module, but it does not give users a useful starting point or show how
a workspace becomes a container.

Generate a small working module by default. It keeps the workspace source,
lets users choose the base image, and exposes a container function with the
source mounted at `/src`.

Python needs the public `create` method because Dagger later rebuilds the
object from its fields. Keeping the generated `__init__` available makes that
reconstruction work when another function is called.

The previous blank template remains available as `empty`, while `legacy`
stays unchanged. Name the workspace argument `ws` to avoid clashing with the
CLI's top-level `--workspace` flag.

Signed-off-by: Guillaume de Rouville <guillaume@dagger.io>
---
 python-sdk.dang                               |  9 +++--
 .../{minimal => default}/pyproject.toml.tmpl  |  0
 .../src/{{.ModulePackage}}/__init__.py.tmpl   | 39 +++++++++++++++++++
 templates/empty/pyproject.toml.tmpl           | 12 ++++++
 .../src/{{.ModulePackage}}/__init__.py.tmpl   |  1 +
 5 files changed, 57 insertions(+), 4 deletions(-)
 rename templates/{minimal => default}/pyproject.toml.tmpl (100%)
 create mode 100644 templates/default/src/{{.ModulePackage}}/__init__.py.tmpl
 create mode 100644 templates/empty/pyproject.toml.tmpl
 rename templates/{minimal => empty}/src/{{.ModulePackage}}/__init__.py.tmpl (98%)

diff --git a/python-sdk.dang b/python-sdk.dang
index 6f0ca99..ca81d19 100644
--- a/python-sdk.dang
+++ b/python-sdk.dang
@@ -136,14 +136,15 @@ type PythonSdk {
   new module's `path`. Engine-owned files (dagger-module.toml, workspace config
   updates) are produced by the engine and merged with this changeset.
 
-  Pass `template` to materialize files from templates/<template>. The empty
-  default uses this module's minimal template.
+  Pass `template` to pick a starter under templates/<template>. It defaults to
+  `default` (a small working module). Use `empty` for a bare object class. An
+  explicitly empty template also selects `default` for compatibility.
 
   Pass `pythonVersion`, `useUv`, or `baseImage` to customize the generated
   pyproject.toml. Defaults leave the template untouched: the template's Python
   version is used, uv is enabled, and no base image override is written.
   """
-  pub initModule(ws: Workspace!, name: String!, path: String!, template: String! = "", pythonVersion: String! = "", useUv: Boolean! = true, baseImage: String! = ""): Changeset! {
+  pub initModule(ws: Workspace!, name: String!, path: String!, template: String! = "default", pythonVersion: String! = "", useUv: Boolean! = true, baseImage: String! = ""): Changeset! {
     let rawPath = path.trimPrefix("./").trimPrefix("/")
 
     let modPath = if (rawPath == "" or rawPath == ".") {
@@ -154,7 +155,7 @@ type PythonSdk {
       rawPath.trimSuffix("/")
     }
 
-    let selectedTemplate = if (template == "") { "minimal" } else { template }
+    let selectedTemplate = if (template == "") { "default" } else { template }
 
     if (currentModule.source.exists("templates/" + selectedTemplate) == false) {
       raise "unknown init template: " + template
diff --git a/templates/minimal/pyproject.toml.tmpl b/templates/default/pyproject.toml.tmpl
similarity index 100%
rename from templates/minimal/pyproject.toml.tmpl
rename to templates/default/pyproject.toml.tmpl
diff --git a/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl b/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl
new file mode 100644
index 0000000..b038bb0
--- /dev/null
+++ b/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl
@@ -0,0 +1,39 @@
+import dagger
+from dagger import dag, function, object_type
+
+
+@object_type
+class {{ .ModuleType }}:
+    source: dagger.Directory
+    base_image_address: str
+
+    @classmethod
+    def create(
+        cls,
+        ws: dagger.Workspace,
+        base_image_address: str = "alpine:3.21",
+    ):
+        return cls(
+            source=ws.directory(
+                "/",
+                exclude=[
+                    "**/.dagger",
+                    "**/.git",
+                    "**/.venv",
+                    "**/__pycache__",
+                    "**/node_modules",
+                    "**/dist",
+                ],
+            ),
+            base_image_address=base_image_address,
+        )
+
+    @function
+    def container(self) -> dagger.Container:
+        """A container with the workspace source, ready to build."""
+        return (
+            dag.container()
+            .from_(self.base_image_address)
+            .with_directory("/src", self.source)
+            .with_workdir("/src")
+        )
diff --git a/templates/empty/pyproject.toml.tmpl b/templates/empty/pyproject.toml.tmpl
new file mode 100644
index 0000000..30359be
--- /dev/null
+++ b/templates/empty/pyproject.toml.tmpl
@@ -0,0 +1,12 @@
+[project]
+name = "{{ .ModuleName }}"
+version = "0.1.0"
+requires-python = ">=3.14"
+dependencies = ["dagger-io"]
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+dagger-io = { path = "sdk", editable = true }
diff --git a/templates/minimal/src/{{.ModulePackage}}/__init__.py.tmpl b/templates/empty/src/{{.ModulePackage}}/__init__.py.tmpl
similarity index 98%
rename from templates/minimal/src/{{.ModulePackage}}/__init__.py.tmpl
rename to templates/empty/src/{{.ModulePackage}}/__init__.py.tmpl
index a3814ad..e26f5ef 100644
--- a/templates/minimal/src/{{.ModulePackage}}/__init__.py.tmpl
+++ b/templates/empty/src/{{.ModulePackage}}/__init__.py.tmpl
@@ -1,5 +1,6 @@
 from dagger import object_type
 
+
 @object_type
 class {{ .ModuleType }}:
     pass

From 4f492b4889e5abae8cbcf7f6b3b9291f6e195147 Mon Sep 17 00:00:00 2001
From: Guillaume de Rouville <guillaume@dagger.io>
Date: Wed, 22 Jul 2026 14:21:58 -0700
Subject: [PATCH 2/3] test: cover Python template selection

The init command now has two useful starting points: the working default and
the blank `empty` template. Cover both through `initModule`, including the
existing behavior where an explicitly empty template name selects the
default.

Check the generated source rather than the template helpers so the test sees
what users actually receive. Also call the generated container function. This
catches a Python-specific failure where the module loads correctly but fails
when Dagger rebuilds the object before the next function call.

Keep the expected and unwanted snippets together so reviewers can read the
generated source contract without working through repeated assertions.

Signed-off-by: Guillaume de Rouville <guillaume@dagger.io>
---
 .dagger/modules/e2e/main.dang | 72 ++++++++++++++++++++++++++++++++++-
 1 file changed, 71 insertions(+), 1 deletion(-)

diff --git a/.dagger/modules/e2e/main.dang b/.dagger/modules/e2e/main.dang
index a1932eb..ce0a1b9 100644
--- a/.dagger/modules/e2e/main.dang
+++ b/.dagger/modules/e2e/main.dang
@@ -60,6 +60,33 @@ type E2e {
     assert(value.contains(want) == false, message)
   }
 
+  """
+  Assert that a string contains every expected substring.
+  """
+  let assertContainsAll(value: String!, wants: [String!]!): Void {
+    wants.each { want =>
+      assertContains(value, want, "expected value to contain: " + want)
+    }
+    null
+  }
+
+  """
+  Assert that a string contains none of the unwanted substrings.
+  """
+  let assertContainsNone(value: String!, unwanted: [String!]!): Void {
+    unwanted.each { want =>
+      assertNotContains(value, want, "expected value not to contain: " + want)
+    }
+    null
+  }
+
+  """
+  Return the rendered Python module source from an init changeset.
+  """
+  let initSource(changes: Changeset!, path: String!, package: String!): String! {
+    changes.layer.file(path + "/src/" + package + "/__init__.py").contents
+  }
+
   """
   The helper should expose the generate skip marker used by callers.
   """
@@ -134,13 +161,56 @@ type E2e {
     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 + "/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, "class InitDefault:", "default template did not render the module type")
 
     assertContains(legacyChanges.layer.file(legacyPath + "/src/init_legacy/main.py").contents, "class InitLegacy:", "legacy template did not render the module type")
 
     null
   }
 
+  """
+  The default template should render a working module that reads source from
+  the workspace and returns a ready-to-build container. The empty template
+  should remain available as a bare object class.
+  """
+  pub templateCheck(ws: Workspace!): Void @check {
+    let defaultPath = outputRoot + "/template-default"
+    let emptyPath = outputRoot + "/template-empty"
+
+    let defaultSource = initSource(
+      pythonSdk.initModule(ws, name: "template-default", path: defaultPath),
+      defaultPath,
+      "template_default",
+    )
+    assertContainsAll(defaultSource, [
+      "class TemplateDefault:",
+      "@classmethod\n    def create(",
+      "ws: dagger.Workspace",
+      "base_image_address: str = \"alpine:3.21\"",
+      "return cls(",
+      "def container(self) -> dagger.Container:",
+      ".with_directory(\"/src\", self.source)",
+    ])
+    assertContainsNone(defaultSource, ["def __init__", "{{"])
+
+    let compatibleDefaultSource = initSource(
+      pythonSdk.initModule(ws, name: "template-default", path: defaultPath, template: ""),
+      defaultPath,
+      "template_default",
+    )
+    assert(compatibleDefaultSource == defaultSource, "an explicitly empty template should select the default template")
+
+    let emptySource = initSource(
+      pythonSdk.initModule(ws, name: "template-empty", path: emptyPath, template: "empty"),
+      emptyPath,
+      "template_empty",
+    )
+    assertContainsAll(emptySource, ["class TemplateEmpty:", "    pass"])
+    assertContainsNone(emptySource, ["def container", "{{"])
+
+    null
+  }
+
   """
   Generating an existing module should produce generated files rooted at that
   module without touching unrelated paths.

From 6b06cbca48d5194626e68afdccff5d87b1e817fb Mon Sep 17 00:00:00 2001
From: Guillaume de Rouville <guillaume@dagger.io>
Date: Wed, 22 Jul 2026 17:01:55 -0700
Subject: [PATCH 3/3] chore: update versions used by Python templates

Bring newly generated projects in line with the versions we support today:
Python 3.14, uv_build through the 0.11 line, and Alpine 3.24 for the new
default container.

Keep uv_build's lower bound at 0.8.4 because the engine already includes a
compatible version. This avoids an unnecessary download while still allowing
current releases below 0.12.

Signed-off-by: Guillaume de Rouville <guillaume@dagger.io>
---
 .dagger/modules/e2e/main.dang                             | 2 +-
 templates/default/pyproject.toml.tmpl                     | 2 +-
 templates/default/src/{{.ModulePackage}}/__init__.py.tmpl | 2 +-
 templates/empty/pyproject.toml.tmpl                       | 2 +-
 templates/legacy/pyproject.toml.tmpl                      | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.dagger/modules/e2e/main.dang b/.dagger/modules/e2e/main.dang
index ce0a1b9..b92ce59 100644
--- a/.dagger/modules/e2e/main.dang
+++ b/.dagger/modules/e2e/main.dang
@@ -186,7 +186,7 @@ type E2e {
       "class TemplateDefault:",
       "@classmethod\n    def create(",
       "ws: dagger.Workspace",
-      "base_image_address: str = \"alpine:3.21\"",
+      "base_image_address: str = \"alpine:3.24\"",
       "return cls(",
       "def container(self) -> dagger.Container:",
       ".with_directory(\"/src\", self.source)",
diff --git a/templates/default/pyproject.toml.tmpl b/templates/default/pyproject.toml.tmpl
index 30359be..6a46215 100644
--- a/templates/default/pyproject.toml.tmpl
+++ b/templates/default/pyproject.toml.tmpl
@@ -5,7 +5,7 @@ requires-python = ">=3.14"
 dependencies = ["dagger-io"]
 
 [build-system]
-requires = ["uv_build>=0.8.4,<0.9.0"]
+requires = ["uv_build>=0.8.4,<0.12.0"]
 build-backend = "uv_build"
 
 [tool.uv.sources]
diff --git a/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl b/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl
index b038bb0..adee060 100644
--- a/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl
+++ b/templates/default/src/{{.ModulePackage}}/__init__.py.tmpl
@@ -11,7 +11,7 @@ class {{ .ModuleType }}:
     def create(
         cls,
         ws: dagger.Workspace,
-        base_image_address: str = "alpine:3.21",
+        base_image_address: str = "alpine:3.24",
     ):
         return cls(
             source=ws.directory(
diff --git a/templates/empty/pyproject.toml.tmpl b/templates/empty/pyproject.toml.tmpl
index 30359be..6a46215 100644
--- a/templates/empty/pyproject.toml.tmpl
+++ b/templates/empty/pyproject.toml.tmpl
@@ -5,7 +5,7 @@ requires-python = ">=3.14"
 dependencies = ["dagger-io"]
 
 [build-system]
-requires = ["uv_build>=0.8.4,<0.9.0"]
+requires = ["uv_build>=0.8.4,<0.12.0"]
 build-backend = "uv_build"
 
 [tool.uv.sources]
diff --git a/templates/legacy/pyproject.toml.tmpl b/templates/legacy/pyproject.toml.tmpl
index 30359be..6a46215 100644
--- a/templates/legacy/pyproject.toml.tmpl
+++ b/templates/legacy/pyproject.toml.tmpl
@@ -5,7 +5,7 @@ requires-python = ">=3.14"
 dependencies = ["dagger-io"]
 
 [build-system]
-requires = ["uv_build>=0.8.4,<0.9.0"]
+requires = ["uv_build>=0.8.4,<0.12.0"]
 build-backend = "uv_build"
 
 [tool.uv.sources]