python-sdk.dang

"""
Manage Dagger modules that use the Python SDK.
"""
type PythonSdk {
  """
  Marker filename that skips generate when found at or above a Python SDK module root.
  """
  pub skipGenerateFilename: String! = ".dagger-python-sdk-skip-generate"

  """
  Return every Dagger module whose sdk.source is "python".
  """
  pub modules(ws: Workspace!): [Mod!]! {
    ws
      .directory("/", include: ["**/dagger.json"])
      .search(
        pattern: "\"sdk\"\\s*:\\s*\\{[^}]*\"source\"\\s*:\\s*\"python\"",
        globs: ["**/dagger.json"],
        filesOnly: true,
        multiline: true,
        dotall: true,
      )
      .{filePath}
      .map { configPath =>
        mod(
          ws,
          if (configPath.filePath == "dagger.json") { "." } else { configPath.filePath.trimSuffix("/dagger.json") },
          findUp: false,
        )
      }
  }

  """
  Return init templates tracked by this module.

  Templates live under templates/<name> and are materialized into the new
  module before generation. Passing an empty template to init uses the module
  default.
  """
  pub templates: [Template!]! {
    if (currentModule.source.exists("templates")) {
      let root = currentModule.source.directory("templates")
      root.entries.map { name =>
        Template(
          name: name.trimSuffix("/"),
          source: root.directory(name),
        )
      }
    } else {
      directory.entries.map { name =>
        Template(
          name: name,
          source: directory,
        )
      }
    }
  }

  """
  Return the Python SDK module at or above a workspace path.

  When `findUp` is true, `path` may point inside the module.
  """
  pub mod(ws: Workspace!, path: String! = ".", findUp: Boolean! = true): Mod! {
    let modPath = if (findUp) {
      let foundConfigPath = ws.findUp("dagger.json", path)
      if (foundConfigPath == null) {
        raise "no Dagger module found containing path: " + path
      } else {
        let configPath = foundConfigPath.trimPrefix("/")
        if (
          ws
            .directory("/", include: [configPath])
            .file(configPath)
            .search(
              pattern: "\"sdk\"\\s*:\\s*\\{[^}]*\"source\"\\s*:\\s*\"python\"",
              multiline: true,
              dotall: true,
              limit: 1,
            )
            .{id}
            .length == 0
        ) {
          raise "Dagger module does not use the Python SDK: " + path
        } else if (configPath == "dagger.json") {
          "."
        } else {
          configPath.trimSuffix("/dagger.json")
        }
      }
    } else {
      path.trimPrefix("/")
    }

    Mod(
      path: modPath,
      ws: ws,
      skipGenerateFilename: skipGenerateFilename,
    )
  }

  """
  Create a new Python SDK Dagger module and return the files to write.

  By default, the new module is created under the nearest `.dagger` directory
  visible from the current workspace path:

    <nearest .dagger>/modules/<name>

  Pass `path` to choose a different module location. The target path must not
  already contain a Dagger module.

  Pass `template` to materialize files from templates/<template>. The empty
  default uses this module's minimal template.

  By default, future generated SDK files are checked into version control. Pass
  `ignoreGenerated` to configure generation to add generated SDK paths to
  .gitignore instead.

  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 init(ws: Workspace!, name: String!, path: String! = "", template: String! = "", ignoreGenerated: Boolean! = false, pythonVersion: String! = "", useUv: Boolean! = true, baseImage: String! = ""): Changeset! {
    let rawPath = if (path == "") {
      let daggerDir = ws.findUp(".dagger", ".")
      if (daggerDir == null) {
        ".dagger/modules/" + name
      } else {
        daggerDir.trimPrefix("/") + "/modules/" + name
      }
    } else {
      path.trimPrefix("./").trimPrefix("/")
    }

    let modPath = if (rawPath == "" or rawPath == ".") {
      "."
    } else if (rawPath == ".." or rawPath.trimPrefix("../") != rawPath) {
      raise "path escapes workspace: " + rawPath
    } else {
      rawPath.trimSuffix("/")
    }

    let configPath = if (modPath == ".") { "dagger.json" } else { modPath + "/dagger.json" }
    let selectedTemplate = if (template == "") { "minimal" } else { template }

    if (ws.directory("/", include: [configPath]).exists(configPath)) {
      raise "module already exists: " + modPath
    } else if (currentModule.source.exists("templates/" + selectedTemplate) == false) {
      raise "unknown init template: " + template
    } else {
      let config = "{\n  \"name\": " + toJSON(name) + ",\n  \"engineVersion\": \"latest\",\n  \"sdk\": {\n    \"source\": \"python\"\n  },\n  \"codegen\": {\n    \"automaticGitignore\": " + toJSON(ignoreGenerated) + "\n  }\n}\n"
      let templateSource = configuredTemplate(renderedTemplate(name, selectedTemplate), pythonVersion, useUv, baseImage)

      polyfill.workspace(ws).fork
        .withDirectory(modPath, templateSource)
        .withNewFile(configPath, config)
        .changes
    }
  }

  """
  Render a Python template with the requested module name.
  """
  let renderedTemplate(name: String!, templateName: String!): Directory! {
    container
      .from("golang:1.25-alpine")
      .withoutEntrypoint
      .withMountedCache("/go/pkg/mod", cacheVolume("go-mod"))
      .withMountedCache("/root/.cache/go-build", cacheVolume("go-build"))
      .withDirectory("/helper", currentModule.source.directory("helpers/render-template"))
      .withDirectory("/template", currentModule.source.directory("templates/" + templateName))
      .withWorkdir("/helper")
      .withExec(["go", "build", "-o", "/usr/local/bin/render-template", "."])
      .withExec(["render-template", name, "/template", "/rendered"])
      .directory("/rendered")
  }

  """
  Apply non-default configuration flags to a rendered template's pyproject.toml.

  When all flags are at their defaults, the source is returned unchanged (no
  helper run, no reformatting). When any flag is non-default, the helper
  re-marshals pyproject.toml, normalizing formatting while preserving all data.
  """
  let configuredTemplate(source: Directory!, pythonVersion: String!, useUv: Boolean!, baseImage: String!): Directory! {
    if (pythonVersion == "" and useUv and baseImage == "") {
      source
    } else {
      let pyproj = "/rendered/pyproject.toml"
      let built = container
        .from("golang:1.25-alpine")
        .withoutEntrypoint
        .withMountedCache("/go/pkg/mod", cacheVolume("go-mod"))
        .withMountedCache("/root/.cache/go-build", cacheVolume("go-build"))
        .withDirectory("/helper", currentModule.source.directory("helpers/pyproject"))
        .withWorkdir("/helper")
        .withExec(["go", "build", "-o", "/usr/local/bin/pyproject", "."])
        .withDirectory("/rendered", source)
      let withPy = if (pythonVersion == "") { built } else { built.withExec(["pyproject", "set-python-version", pyproj, pythonVersion]) }
      let withUv = if (useUv) { withPy } else { withPy.withExec(["pyproject", "set-use-uv", pyproj, "false"]) }
      let withImg = if (baseImage == "") { withUv } else { withUv.withExec(["pyproject", "set-base-image", pyproj, baseImage]) }
      withImg.directory("/rendered")
    }
  }

  """
  Generate all discovered Python SDK modules.
  Modules with the generate skip marker are skipped.
  """
  pub generateAll(ws: Workspace!): Changeset! @generate {
    let pws = polyfill.workspace(ws)

    modules(ws)
      .filter { mod => mod.skipGenerate == false }
      .reduce(pws.fork) { fork, mod =>
        fork.merge(pws.moduleSource(mod.path).generate)
      }
      .changes
  }
}