python-sdk.dang

"""
Manage Dagger modules that use the Python SDK.
"""
type PythonSdk {
  """
  Starter under templates/<template> for a module generated without source.
  """
  pub template: String! = "default"

  """Write selected Git commits as manifest pins."""
  pub lock: Boolean! = false

  """
  Python version written to a new module's pyproject.toml; empty keeps the template's.
  """
  pub pythonVersion: String! = ""

  """
  Whether a new module builds with uv instead of pip.
  """
  pub useUv: Boolean! = true

  """
  Base container image written to a new module's pyproject.toml; empty keeps the SDK default.
  """
  pub baseImage: String! = ""

  """
  Generate a static entrypoint that carries the module's types, so the engine
  loads them without running the module. Needs an engine that loads manifest
  version 2.
  """
  pub dangEntrypoint: Boolean! = false

  """
  Find the Python client root containing the workspace cwd: the directory of
  the nearest pyproject.toml, relative to the workspace root. A module's
  vendored client library carries its own pyproject.toml, so the Python module
  owning it answers instead; a directory with a module config of its own is a
  module, never a vendored library. Null when there is none.
  """
  pub findClientRoot(ws: Workspace!): String {
    let found = ws.findUp("pyproject.toml")
    if (found == null) {
      null
    } else {
      let scope = normalizePath(found.trimSuffix("pyproject.toml"))
      let vendorParent = if (scope == vendorDirName) {
        "."
      } else if (scope.trimSuffix("/" + vendorDirName) != scope) {
        scope.trimSuffix("/" + vendorDirName)
      } else {
        ""
      }

      if (vendorParent == "" or hasModuleConfig(ws, scope)) {
        scope
      } else if (hasModuleConfig(ws, vendorParent) and scopeHasFile(ws, vendorParent, "pyproject.toml")) {
        vendorParent
      } else {
        scope
      }
    }
  }

  """
  Directory a module's generated client library is vendored into.
  """
  let vendorDirName: String! = "sdk"

  """
  The shared Dang entrypoint every module on the runtime path names, served
  from this repository's entrypoint/ directory. An engine that loads manifest
  version 2 drives the module through it; an older engine ignores the table
  and uses the builtin runtime named by [runtime]. `@v1` selects the greatest
  `entrypoint/v1.*` tag of this repository, then the greatest plain `v1.*` one.
  """
  let sharedEntrypointSource: String! = "dagger.io/sdk/python/entrypoint@v1"

  """
  Whether a module config, dagger-module.toml or the pre-1.0 dagger.json,
  exists at a workspace-root-relative scope.
  """
  let hasModuleConfig(ws: Workspace!, scope: String!): Boolean! {
    scopeHasFile(ws, scope, "dagger-module.toml") or scopeHasFile(ws, scope, "dagger.json")
  }

  let scopeHasFile(ws: Workspace!, scope: String!, filename: String!): Boolean! {
    let path = scopePath(scope, filename)
    ws.directory("/", include: [path]).exists(path)
  }

  let scopePath(scope: String!, filename: String!): String! {
    if (scope == ".") { filename } else { scope + "/" + filename }
  }

  """
  Generate one SDK scope: the module at the workspace cwd, when the scope has
  one. A module without a config file is initialized from the configured
  template. Every module receives a dagger-module.toml from the manifest
  builder module and is then generated. A pre-1.0 dagger.json is migrated
  and removed. The scope's module clients become the module's dependencies,
  so the generated bindings include their types. With dangEntrypoint, the
  module gets an entrypoint manifest and a generated entrypoint instead of a
  runtime.
  Standalone clients, in a scope without a module, are not generated yet.
  """
  pub generateScope(ws: Workspace!, isModule: Boolean!, name: String!, clients: [ModuleSource!]!): Workspace! {
    if (isModule == false) {
      if (clients.length > 0) {
        raise "python-sdk does not generate standalone module clients yet"
      } else {
        ws
      }
    } else {
      let scope = normalizePath(ws.cwd)
      let hadConfig = hasModuleConfig(ws, scope)
      # Resolve local dependency paths from the workspace root.
      let rooted = ws.withWorkdir(".")
      let initialized = if (hadConfig) {
        rooted
      } else {
        rooted.withDirectory("/" + scope, moduleTemplate(name, template, pythonVersion, useUv, baseImage))
      }
      if (dangEntrypoint) {
        checkStaticScope(initialized, scope, hadConfig, clients)
      }
      # The runtime manifest is what every engine serves a schema for; the
      # static path swaps it for the entrypoint manifest as it generates.
      let configured = generateScopeManifest(initialized, scope, name, clients)
      mod(configured, path: scope, findUp: false).generated.withWorkdir(scope)
    }
  }

  """
  Generate dagger-module.toml from the existing manifest and complete client
  set. Preserve fields that the SDK does not own. Remove dagger.json so two
  manifest files cannot contain different state.
  """
  let generateScopeManifest(ws: Workspace!, scope: String!, name: String!, clients: [ModuleSource!]!): Workspace! {
    let root = "/" + scope
    let hasToml = scopeHasFile(ws, scope, "dagger-module.toml")
    let hasJson = scopeHasFile(ws, scope, "dagger.json")
    let base = if (hasToml and isEntrypointManifest(ws.file(root + "/dagger-module.toml").contents)) {
      # A static entrypoint manifest holds nothing the runtime manifest keeps.
      sdkHelpers.moduleManifest.withLegacyPythonRuntime
        .withDangEntrypoint(source: sharedEntrypointSource)
    } else if (hasToml) {
      let manifest = ws.file(root + "/dagger-module.toml")
      let loaded = sdkHelpers.moduleManifest(loadToml: withoutStaleEntrypoint(manifest))
      # A Dang entrypoint already there is the user's: a pinned version, or a fork.
      if (ManifestToml(manifest.contents).entrypointKind == "dang") {
        loaded
      } else {
        loaded.withDangEntrypoint(source: sharedEntrypointSource)
      }
    } else if (hasJson) {
      sdkHelpers.moduleManifest(loadJson: ws.file(root + "/dagger.json"))
        .withDangEntrypoint(source: sharedEntrypointSource)
    } else {
      sdkHelpers.moduleManifest.withLegacyPythonRuntime
        .withDangEntrypoint(source: sharedEntrypointSource)
    }
    clients.reduce(base.withName(name: name).withoutLegacyRuntimeDependencies) { manifest, client =>
      manifest.withLegacyRuntimeDependency(module: client)
    }.generate(ws.withWorkdir(scope), lock: lock, legacyJson: false).withWorkdir(".")
  }

  """
  Drop an entrypoint table an earlier SDK wrote, before the manifest is read.

  That SDK named the runtime module as a module-kind entrypoint. An engine that
  loads manifest version 2 rejects every kind but "dang", and sdk-helpers keeps
  every table it loads with no way to clear one, so the table goes here instead.
  A Dang entrypoint is kept.
  """
  let withoutStaleEntrypoint(manifest: File!): File! {
    let toml = ManifestToml(manifest.contents)
    if (toml.hasEntrypoint == false or toml.entrypointKind == "dang") {
      manifest
    } else {
      toml.withoutEntrypoint
    }
  }

  """
  What a static entrypoint cannot carry, refused before anything is written.
  """
  let checkStaticScope(ws: Workspace!, scope: String!, hadConfig: Boolean!, clients: [ModuleSource!]!): Void {
    if (clients.length > 0) {
      raise "a static entrypoint cannot use other modules yet: an entrypoint manifest has no dependencies; set dangEntrypoint = false"
    }
    if (hadConfig == false and template == "legacy") {
      raise "the legacy template is not available with a static entrypoint"
    }
    if (scopeHasFile(ws, scope, "dagger-module.toml")) {
      let objections = staticObjections(ws.file("/" + scopePath(scope, "dagger-module.toml")).contents)
      if (objections.length > 0) {
        raise "dagger-module.toml has settings a static entrypoint cannot carry (" + objections.join(", ") + "); remove them or set dangEntrypoint = false"
      }
    }
    null
  }

  """
  Manifest keys and tables that an entrypoint manifest has no place for.
  """
  let staticObjections(toml: String!): [String!]! {
    let head = toml.split("\n[").takeFirst(1).join("")
    let keys = ["include", "disableDefaultFunctionCaching"].filter { key =>
      head.containsMatch(Regexp("(?m)^\\s*" + key + "\\s*="))
    }
    # An entrypoint manifest roots a module at its own directory, which is what
    # `source = "."` says; any other source is what it cannot carry.
    let sourceMatch = head.match("(?m)^\\s*source\\s*=\\s*\"([^\"]*)\"")
    let sourceValue = if (sourceMatch == null) { "." } else { sourceMatch.captures[0] ?? "." }
    let source = if (sourceValue == ".") { [] :: [String!]! } else { ["source"] }
    let tables = ["codegen", "clients", "dependencies"].filter { name =>
      toml.containsMatch(Regexp("(?m)^\\s*\\[\\[?" + name + "\\]\\]?"))
    }
    let pythonRuntime = toml.containsMatch("(?m)^\\s*\\[runtime\\]\\s*\\n\\s*source\\s*=\\s*\"python\"")
    let runtime = if (toml.containsMatch("(?m)^\\s*\\[runtime\\]") and pythonRuntime == false) { ["runtime"] } else { [] :: [String!]! }
    keys + source + tables + runtime
  }

  """
  Whether the manifest names an entrypoint generated into the module. The
  shared entrypoint is a Dang entrypoint too, so the kind alone does not tell:
  a static entrypoint is the one whose source is a path inside the module.
  """
  let isEntrypointManifest(toml: String!): Boolean! {
    ManifestToml(toml).isStatic
  }

  let hasEntrypointManifest(ws: Workspace!, scope: String!): Boolean! {
    scopeHasFile(ws, scope, "dagger-module.toml") and isEntrypointManifest(ws.file("/" + scopePath(scope, "dagger-module.toml")).contents)
  }

  """
  Workspace-root-relative roots of the modules registered to this SDK.
  """
  let managedRoots(ws: Workspace!): [String!]! {
    ws.sdk(name: currentModule.name)
      .modules.{{source}}
      .map { module => normalizePath(module.source) }
  }

  let nearestRoot(roots: [String!]!): String {
    roots.reduce(null) { best, root =>
      if (pathDepth(root) > pathDepth(best)) { root } else { best }
    }
  }

  let normalizePath(path: String!): String! {
    let normalized = path.trimPrefix("./").trimPrefix("/").trimSuffix("/")
    if (normalized == "") { "." } else { normalized }
  }

  let pathDepth(path: String): Int! {
    if (path == null) { -1 } else if (path == ".") { 0 } else { path.split("/").length }
  }

  let pathContains(root: String!, path: String!): Boolean! {
    root == "." or path == root or path.trimPrefix(root + "/") != path
  }

  """
  Return the starter templates tracked by this module.

  Templates live under templates/<name> and are materialized into a new module
  before generation. The `template` setting selects one; empty selects the
  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 managed Python SDK module at or above a workspace path.

  When `findUp` is true, `path` may point inside the module; the nearest
  enclosing module wins. When it is false, `path` is taken as the module root
  as given, without asking whether this SDK manages it.
  """
  pub mod(ws: Workspace!, path: String! = ".", findUp: Boolean! = true): Mod! {
    let modPath = if (findUp) {
      managedModuleAtOrAbove(ws, path)
    } else {
      normalizePath(path)
    }

    Mod(
      rootPath: modPath,
      ws: ws,
      dangEntrypoint: dangEntrypoint or hasEntrypointManifest(ws, modPath),
    )
  }

  """
  Root of the nearest managed Python SDK module containing `path`.

  Nothing here parses module config: registration is what makes a module ours.
  """
  let managedModuleAtOrAbove(ws: Workspace!, path: String!): String! {
    let requested = normalizePath(ws.withWorkdir(path).cwd)
    let found = nearestRoot(managedRoots(ws).filter { root => pathContains(root, requested) })

    if (found == null) {
      raise "no managed Python SDK module found containing path: " + path
    } else {
      found
    }
  }

  """
  The files of a new module: the named template rendered for the module name,
  with the pyproject.toml settings applied. An empty template name selects the
  default.
  """
  let moduleTemplate(name: String!, template: String!, pythonVersion: String!, useUv: Boolean!, baseImage: String!): Directory! {
    let selectedTemplate = if (template == "") { "default" } else { template }

    let known = currentModule.source.directory("templates").entries.map { entry => entry.trimSuffix("/") }

    if (known.filter { entry => entry == selectedTemplate }.length == 0) {
      raise "unknown init template: " + template
    } else {
      configuredTemplate(renderedTemplate(name, selectedTemplate), pythonVersion, useUv, baseImage)
    }
  }

  """
  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")
    }
  }
}

"""
A dagger-module.toml, read for its entrypoint table.

Not a TOML parser. A table runs to the next table header, so one pass over the
lines separates the entrypoint table from the rest. A header is recognised with
its trailing comment removed, so a "[" inside a comment or a value never ends
the table; every line is carried over exactly as it was read.
"""
type ManifestToml {
  pub toml: String!

  new(toml: String! = "") {
    self.toml = toml
    self
  }

  pub hasEntrypoint: Boolean! {
    split.entrypoint.isEmpty == false
  }

  """The entrypoint's kind, or empty when the manifest has no entrypoint."""
  pub entrypointKind: String! {
    entrypointValue("kind")
  }

  pub entrypointSource: String! {
    entrypointValue("source")
  }

  """
  Whether the entrypoint is one generated into the module: a Dang entrypoint
  whose source is a path inside the module, read the way the engine reads it.
  """
  pub isStatic: Boolean! {
    entrypointKind == "dang" and isLocalSource(entrypointSource)
  }

  """The manifest with its entrypoint table removed."""
  pub withoutEntrypoint: File! {
    directory.withNewFile(fileName, split.kept.join("\n")).file(fileName)
  }

  let fileName: String! = "dagger-module.toml"

  let split: TomlSplit! {
    toml.split("\n").reduce(TomlSplit()) { state, line =>
      let header = line.replaceMatches("#.*", "").trimSpace
      if (header.hasPrefix("[")) {
        let isEntrypoint = header == "[entrypoint]"
        TomlSplit(
          kept: if (isEntrypoint) { state.kept } else { state.kept + [line] },
          entrypoint: if (isEntrypoint) { state.entrypoint + [line] } else { state.entrypoint },
          inTable: isEntrypoint,
        )
      } else if (state.inTable) {
        TomlSplit(kept: state.kept, entrypoint: state.entrypoint + [line], inTable: true)
      } else {
        TomlSplit(kept: state.kept + [line], entrypoint: state.entrypoint, inTable: false)
      }
    }
  }

  let entrypointValue(key: String!): String! {
    let m = split.entrypoint.join("\n").match(Regexp("(?m)^\\s*" + Regexp.escape(key) + "\\s*=\\s*\"([^\"]*)\""))
    if (m == null) { "" } else { m.captures[0] ?? "" }
  }

  """
  The engine's own rule: a path prefix or a dot-free first segment is local, a
  URL or a host name is not.
  """
  let isLocalSource(source: String!): Boolean! {
    if (source.hasPrefix(".") or source.hasPrefix("/")) {
      true
    } else if (source.contains(":")) {
      false
    } else {
      (source.split("/")[0] ?? "").contains(".") == false
    }
  }
}

"""
Accumulator for splitting a manifest's entrypoint table off the rest.
"""
type TomlSplit {
  pub kept: [String!]!
  pub entrypoint: [String!]!
  pub inTable: Boolean!

  new(kept: [String!]! = [], entrypoint: [String!]! = [], inTable: Boolean! = false) {
    self.kept = kept
    self.entrypoint = entrypoint
    self.inTable = inTable
    self
  }
}