Client

Automatically generated client from Dagger API.

class dagger.BuildArg(name: str, value: str)

Bases: Input

Key value object that represents a build argument.

name: str
value: str
class dagger.CacheSharingMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Sharing mode of the cache volume.

LOCKED = 'LOCKED'
PRIVATE = 'PRIVATE'
SHARED = 'SHARED'
class dagger.CacheVolume(ctx: Context)

Bases: Type

A directory whose contents persist across runs.

async id() → CacheVolumeID[source]

A unique identifier for this CacheVolume.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The CacheVolumeID scalar type represents an identifier for an object of type CacheVolume.

Return type:

CacheVolumeID

Raises:
class dagger.CacheVolumeID

Bases: Scalar

The CacheVolumeID scalar type represents an identifier for an object of type CacheVolume.

class dagger.Client(ctx: Context | None = None)

Bases: Root

The root of the DAG.

blob(digest: str, size: int, media_type: str, uncompressed: str) → Directory[source]

Retrieves a content-addressed blob.

Parameters:

  • digest – Digest of the blob

  • size – Size of the blob

  • media_type – Media type of the blob

  • uncompressed – Digest of the uncompressed blob

cache_volume(key: str) → CacheVolume[source]

Constructs a cache volume for a given cache key.

Parameters:

key – A string identifier to target this cache volume (e.g., “modules- cache”).

async check_version_compatibility(version: str) → bool[source]

Checks if the current Dagger Engine is compatible with an SDK’s required version.

Parameters:

version – Version required by the SDK.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:
container(*, id: ContainerID | None = None, platform: Platform | None = None) → Container[source]

Creates a scratch container.

Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder’s host.

Parameters:

  • id – DEPRECATED: Use loadContainerFromID instead.

  • platform – Platform to initialize the container with.

current_function_call() → FunctionCall[source]

The FunctionCall context that the SDK caller is currently executing in.

If the caller is not currently executing in a function, this will return an error.

current_module() → Module[source]

The module currently being served in the session, if any.

async current_type_defs() → list[TypeDef][source]

The TypeDef representations of the objects currently being served in the session.

async default_platform() → Platform[source]

The default platform of the engine.

Returns:

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

Return type:

Platform

Raises:
directory(*, id: DirectoryID | None = None) → Directory[source]

Creates an empty directory.

Parameters:

id – DEPRECATED: Use loadDirectoryFromID isntead.

file(id: FileID) → File[source]

Use load_file_from_id() instead.

function(name: str, return_type: TypeDef) → Function[source]

Creates a function.

Parameters:

  • name – Name of the function, in its original format from the implementation language.

  • return_type – Return type of the function.

generated_code(code: Directory) → GeneratedCode[source]

Create a code generation result, given a directory containing the generated code.

git(url: str, *, keep_git_dir: bool | None = False, experimental_service_host: Service | None = None, ssh_known_hosts: str | None = '', ssh_auth_socket: Socket | None = None) → GitRepository[source]

Queries a Git repository.

Parameters:

  • url – URL of the git repository. Can be formatted as https://{host}/{owner}/{repo}, git@{host}:{owner}/{repo}. Suffix “.git” is optional.

  • keep_git_dir – Set to true to keep .git directory.

  • experimental_service_host – A service which must be started before the repo is fetched.

  • ssh_known_hosts – Set SSH known hosts

  • ssh_auth_socket – Set SSH auth socket

host() → Host[source]

Queries the host environment.

http(url: str, *, experimental_service_host: Service | None = None) → File[source]

Returns a file containing an http remote url content.

Parameters:

  • url – HTTP url to get the content from (e.g., “https://docs.dagger.io”).

  • experimental_service_host – A service which must be started before the URL is fetched.

load_cache_volume_from_id(id: CacheVolumeID) → CacheVolume[source]

Load a CacheVolume from its ID.

load_container_from_id(id: ContainerID) → Container[source]

Load a Container from its ID.

load_directory_from_id(id: DirectoryID) → Directory[source]

Load a Directory from its ID.

load_env_variable_from_id(id: EnvVariableID) → EnvVariable[source]

Load a EnvVariable from its ID.

load_field_type_def_from_id(id: FieldTypeDefID) → FieldTypeDef[source]

Load a FieldTypeDef from its ID.

load_file_from_id(id: FileID) → File[source]

Load a File from its ID.

load_function_arg_from_id(id: FunctionArgID) → FunctionArg[source]

Load a FunctionArg from its ID.

load_function_call_arg_value_from_id(id: FunctionCallArgValueID) → FunctionCallArgValue[source]

Load a FunctionCallArgValue from its ID.

load_function_call_from_id(id: FunctionCallID) → FunctionCall[source]

Load a FunctionCall from its ID.

load_function_from_id(id: FunctionID) → Function[source]

Load a Function from its ID.

load_generated_code_from_id(id: GeneratedCodeID) → GeneratedCode[source]

Load a GeneratedCode from its ID.

load_git_ref_from_id(id: GitRefID) → GitRef[source]

Load a GitRef from its ID.

load_git_repository_from_id(id: GitRepositoryID) → GitRepository[source]

Load a GitRepository from its ID.

load_host_from_id(id: HostID) → Host[source]

Load a Host from its ID.

load_interface_type_def_from_id(id: InterfaceTypeDefID) → InterfaceTypeDef[source]

Load a InterfaceTypeDef from its ID.

load_label_from_id(id: LabelID) → Label[source]

Load a Label from its ID.

load_list_type_def_from_id(id: ListTypeDefID) → ListTypeDef[source]

Load a ListTypeDef from its ID.

load_module_config_from_id(id: ModuleConfigID) → ModuleConfig[source]

Load a ModuleConfig from its ID.

load_module_from_id(id: ModuleID) → Module[source]

Load a Module from its ID.

load_object_type_def_from_id(id: ObjectTypeDefID) → ObjectTypeDef[source]

Load a ObjectTypeDef from its ID.

load_port_from_id(id: PortID) → Port[source]

Load a Port from its ID.

load_secret_from_id(id: SecretID) → Secret[source]

Load a Secret from its ID.

load_service_from_id(id: ServiceID) → Service[source]

Load a Service from its ID.

load_socket_from_id(id: SocketID) → Socket[source]

Load a Socket from its ID.

load_type_def_from_id(id: TypeDefID) → TypeDef[source]

Load a TypeDef from its ID.

module() → Module[source]

Create a new module.

module_config(source_directory: Directory, *, subpath: str | None = '') → ModuleConfig[source]

Load the static configuration for a module from the given source directory and optional subpath.

pipeline(name: str, *, description: str | None = '', labels: Sequence[PipelineLabel] | None = None) → Client[source]

Creates a named sub-pipeline.

Parameters:

  • name – Name of the sub-pipeline.

  • description – Description of the sub-pipeline.

  • labels – Labels to apply to the sub-pipeline.

secret(name: str) → Secret[source]

Reference a secret by name.

set_secret(name: str, plaintext: str) → Secret[source]

Sets a secret given a user defined name to its plaintext and returns the secret.

The plaintext value is limited to a size of 128000 bytes.

Parameters:

  • name – The user defined name for this secret

  • plaintext – The plaintext of the secret

socket(id: SocketID) → Socket[source]

Loads a socket by its ID.

Deprecated

Use load_socket_from_id() instead.

type_def() → TypeDef[source]

Create a new TypeDef.

with_(cb: Callable[[Client], Client]) → Client[source]

Call the provided callable with current Client.

This is useful for reusability and readability by not breaking the calling chain.

class dagger.Container(ctx: Context)

Bases: Type

An OCI-compatible container, also known as a Docker container.

as_service() → Service[source]

Turn the container into a Service.

Be sure to set any exposed ports before this conversion.

as_tarball(*, platform_variants: Sequence[Container] | None = [], forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = 'OCIMediaTypes') → File[source]

Returns a File representing the container serialized to a tarball.

Parameters:

  • platform_variants – Identifiers for other platform specific containers. Used for multi-platform images.

  • forced_compression – Force each layer of the image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

  • media_types – Use the specified media types for the image’s layers. Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

build(context: Directory, *, dockerfile: str | None = 'Dockerfile', target: str | None = '', build_args: Sequence[BuildArg] | None = [], secrets: Sequence[Secret] | None = []) → Container[source]

Initializes this container from a Dockerfile build.

Parameters:

  • context – Directory context used by the Dockerfile.

  • dockerfile – Path to the Dockerfile to use.

  • target – Target build stage to build.

  • build_args – Additional build arguments.

  • secrets – Secrets to pass to the build. They will be mounted at /run/secrets/[secret-name] in the build container They can be accessed in the Dockerfile using the “secret” mount type and mount path /run/secrets/[secret-name], e.g. RUN –mount=type=secret,id=my-secret curl http://example.com?token=$(cat /run/secrets/my-secret)

async default_args() → list[str][source]

Retrieves default arguments for future commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
directory(path: str) → Directory[source]

Retrieves a directory at the given path.

Mounts are included.

Parameters:

path – The path of the directory to retrieve (e.g., “./src”).

async entrypoint() → list[str][source]

Retrieves entrypoint to be prepended to the arguments of all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async env_variable(name: str) → str | None[source]

Retrieves the value of the specified environment variable.

Parameters:

name – The name of the environment variable to retrieve (e.g., “PATH”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:
async env_variables() → list[EnvVariable][source]

Retrieves the list of environment variables passed to commands.

experimental_with_all_gp_us() → Container[source]

EXPERIMENTAL API! Subject to change/removal at any time.

Configures all available GPUs on the host to be accessible to this container.

This currently works for Nvidia devices only.

experimental_with_gpu(devices: Sequence[str]) → Container[source]

EXPERIMENTAL API! Subject to change/removal at any time.

Configures the provided list of devices to be accesible to this container.

This currently works for Nvidia devices only.

Parameters:

devices – List of devices to be accessible to this container.

async export(path: str, *, platform_variants: Sequence[Container] | None = [], forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = 'OCIMediaTypes') → bool[source]

Writes the container as an OCI tarball to the destination file path on the host.

Return true on success.

It can also export platform variants.

Parameters:

  • path – Host’s destination path (e.g., “./tarball”). Path can be relative to the engine’s workdir or absolute.

  • platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

  • forced_compression – Force each layer of the exported image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

  • media_types – Use the specified media types for the exported image’s layers. Defaults to OCI, which is largely compatible with most recent container runtimes, but Docker may be needed for older runtimes without OCI support.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:
async exposed_ports() → list[Port][source]

Retrieves the list of exposed ports.

This includes ports already exposed by the image, even if not explicitly added with dagger.

file(path: str) → File[source]

Retrieves a file at the given path.

Mounts are included.

Parameters:

path – The path of the file to retrieve (e.g., “./README.md”).

from_(address: str) → Container[source]

Initializes this container from a pulled base image.

Parameters:

address – Image’s address from its registry. Formatted as [host]/[user]/[repo]:[tag] (e.g., “docker.io/dagger/dagger:main”).

async id() → ContainerID[source]

A unique identifier for this Container.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ContainerID scalar type represents an identifier for an object of type Container.

Return type:

ContainerID

Raises:
async image_ref() → str[source]

The unique image reference which can only be retrieved immediately after the ‘Container.From’ call.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
import_(source: File, *, tag: str | None = '') → Container[source]

Reads the container from an OCI tarball.

Parameters:

  • source – File to read the container from.

  • tag – Identifies the tag to import from the archive, if the archive bundles multiple tags.

async label(name: str) → str | None[source]

Retrieves the value of the specified label.

Parameters:

name – The name of the label (e.g., “org.opencontainers.artifact.created”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:
async labels() → list[Label][source]

Retrieves the list of labels passed to container.

async mounts() → list[str][source]

Retrieves the list of paths where a directory is mounted.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
pipeline(name: str, *, description: str | None = '', labels: Sequence[PipelineLabel] | None = []) → Container[source]

Creates a named sub-pipeline.

Parameters:

  • name – Name of the sub-pipeline.

  • description – Description of the sub-pipeline.

  • labels – Labels to apply to the sub-pipeline.

async platform() → Platform[source]

The platform this container executes and publishes as.

Returns:

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

Return type:

Platform

Raises:
async publish(address: str, *, platform_variants: Sequence[Container] | None = [], forced_compression: ImageLayerCompression | None = None, media_types: ImageMediaTypes | None = 'OCIMediaTypes') → str[source]

Publishes this container as a new image to the specified address.

Publish returns a fully qualified ref.

It can also publish platform variants.

Parameters:

  • address – Registry’s address to publish the image to. Formatted as [host]/[user]/[repo]:[tag] (e.g. “docker.io/dagger/dagger:main”).

  • platform_variants – Identifiers for other platform specific containers. Used for multi-platform image.

  • forced_compression – Force each layer of the published image to use the specified compression algorithm. If this is unset, then if a layer already has a compressed blob in the engine’s cache, that will be used (this can result in a mix of compression algorithms for different layers). If this is unset and a layer has no compressed blob in the engine’s cache, then it will be compressed using Gzip.

  • media_types – Use the specified media types for the published image’s layers. Defaults to OCI, which is largely compatible with most recent registries, but Docker may be needed for older registries without OCI support.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
rootfs() → Directory[source]

Retrieves this container’s root filesystem. Mounts are not included.

async shell_endpoint() → str[source]

Return a websocket endpoint that, if connected to, will start the container with a TTY streamed over the websocket.

Primarily intended for internal use with the dagger CLI.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async stderr() → str[source]

The error stream of the last executed command.

Will execute default command if none is set, or error if there’s no default.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async stdout() → str[source]

The output stream of the last executed command.

Will execute default command if none is set, or error if there’s no default.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async sync() → Container[source]

Forces evaluation of the pipeline in the engine.

It doesn’t run the default command if no exec has been set.

Raises:
async user() → str[source]

Retrieves the user to be set for all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
with_(cb: Callable[[Container], Container]) → Container[source]

Call the provided callable with current Container.

This is useful for reusability and readability by not breaking the calling chain.

with_default_args(args: Sequence[str]) → Container[source]

Configures default arguments for future commands.

Parameters:

args – Arguments to prepend to future executions (e.g., [“-v”, “–no- cache”]).

with_directory(path: str, directory: Directory, *, exclude: Sequence[str] | None = [], include: Sequence[str] | None = [], owner: str | None = '') → Container[source]

Retrieves this container plus a directory written at the given path.

Parameters:

  • path – Location of the written directory (e.g., “/tmp/directory”).

  • directory – Identifier of the directory to write

  • exclude – Patterns to exclude in the written directory (e.g. [“node_modules/**”, “.gitignore”, “.git/”]).

  • include – Patterns to include in the written directory (e.g. [”*.go”, “go.mod”, “go.sum”]).

  • owner – A user:group to set for the directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_entrypoint(args: Sequence[str], *, keep_default_args: bool | None = False) → Container[source]

Retrieves this container but with a different command entrypoint.

Parameters:

  • args – Entrypoint to use for future executions (e.g., [“go”, “run”]).

  • keep_default_args – Don’t remove the default arguments when setting the entrypoint.

with_env_variable(name: str, value: str, *, expand: bool | None = False) → Container[source]

Retrieves this container plus the given environment variable.

Parameters:

  • name – The name of the environment variable (e.g., “HOST”).

  • value – The value of the environment variable. (e.g., “localhost”).

  • expand – Replace ${VAR} or $VAR in the value according to the current environment variables defined in the container (e.g., “/opt/bin:$PATH”).

with_exec(args: Sequence[str], *, skip_entrypoint: bool | None = False, stdin: str | None = '', redirect_stdout: str | None = '', redirect_stderr: str | None = '', experimental_privileged_nesting: bool | None = False, insecure_root_capabilities: bool | None = False) → Container[source]

Retrieves this container after executing the specified command inside it.

Parameters:

  • args – Command to run instead of the container’s default command (e.g., [“run”, “main.go”]). If empty, the container’s default command is used.

  • skip_entrypoint – If the container has an entrypoint, ignore it for args rather than using it to wrap them.

  • stdin – Content to write to the command’s standard input before closing (e.g., “Hello world”).

  • redirect_stdout – Redirect the command’s standard output to a file in the container (e.g., “/tmp/stdout”).

  • redirect_stderr – Redirect the command’s standard error to a file in the container (e.g., “/tmp/stderr”).

  • experimental_privileged_nesting – Provides dagger access to the executed command. Do not use this option unless you trust the command being executed; the command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.

  • insecure_root_capabilities – Execute the command with all root capabilities. This is similar to running a command with “sudo” or executing “docker run” with the ” –privileged” flag. Containerization does not provide any security guarantees when using this option. It should only be used when absolutely necessary and only with trusted commands.

with_exposed_port(port: int, *, protocol: NetworkProtocol | None = 'TCP', description: str | None = None) → Container[source]

Expose a network port.

Exposed ports serve two purposes:

  • For health checks and introspection, when running services

  • For setting the EXPOSE OCI field when publishing the container

Parameters:

  • port – Port number to expose

  • protocol – Transport layer network protocol

  • description – Optional port description

with_file(path: str, source: File, *, permissions: int | None = None, owner: str | None = '') → Container[source]

Retrieves this container plus the contents of the given file copied to the given path.

Parameters:

  • path – Location of the copied file (e.g., “/tmp/file.txt”).

  • source – Identifier of the file to copy.

  • permissions – Permission given to the copied file (e.g., 0600).

  • owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_focus() → Container[source]

Indicate that subsequent operations should be featured more prominently in the UI.

with_label(name: str, value: str) → Container[source]

Retrieves this container plus the given label.

Parameters:

  • name – The name of the label (e.g., “org.opencontainers.artifact.created”).

  • value – The value of the label (e.g., “2023-01-01T00:00:00Z”).

with_mounted_cache(path: str, cache: CacheVolume, *, source: Directory | None = None, sharing: CacheSharingMode | None = 'SHARED', owner: str | None = '') → Container[source]

Retrieves this container plus a cache volume mounted at the given path.

Parameters:

  • path – Location of the cache directory (e.g., “/cache/node_modules”).

  • cache – Identifier of the cache volume to mount.

  • source – Identifier of the directory to use as the cache volume’s root.

  • sharing – Sharing mode of the cache volume.

  • owner – A user:group to set for the mounted cache directory. Note that this changes the ownership of the specified mount along with the initial filesystem provided by source (if any). It does not have any effect if/when the cache has already been created. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_directory(path: str, source: Directory, *, owner: str | None = '') → Container[source]

Retrieves this container plus a directory mounted at the given path.

Parameters:

  • path – Location of the mounted directory (e.g., “/mnt/directory”).

  • source – Identifier of the mounted directory.

  • owner – A user:group to set for the mounted directory and its contents. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_file(path: str, source: File, *, owner: str | None = '') → Container[source]

Retrieves this container plus a file mounted at the given path.

Parameters:

  • path – Location of the mounted file (e.g., “/tmp/file.txt”).

  • source – Identifier of the mounted file.

  • owner – A user or user:group to set for the mounted file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_mounted_secret(path: str, source: Secret, *, owner: str | None = '', mode: int | None = 256) → Container[source]

Retrieves this container plus a secret mounted into a file at the given path.

Parameters:

  • path – Location of the secret file (e.g., “/tmp/secret.txt”).

  • source – Identifier of the secret to mount.

  • owner – A user:group to set for the mounted secret. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

  • mode – Permission given to the mounted secret (e.g., 0600). This option requires an owner to be set to be active.

with_mounted_temp(path: str) → Container[source]

Retrieves this container plus a temporary directory mounted at the given path.

Parameters:

path – Location of the temporary directory (e.g., “/tmp/temp_dir”).

with_new_file(path: str, *, contents: str | None = '', permissions: int | None = 420, owner: str | None = '') → Container[source]

Retrieves this container plus a new file written at the given path.

Parameters:

  • path – Location of the written file (e.g., “/tmp/file.txt”).

  • contents – Content of the file to write (e.g., “Hello world!”).

  • permissions – Permission given to the written file (e.g., 0600).

  • owner – A user:group to set for the file. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_registry_auth(address: str, username: str, secret: Secret) → Container[source]

Retrieves this container with a registry authentication for a given address.

Parameters:

  • address – Registry’s address to bind the authentication to. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

  • username – The username of the registry’s account (e.g., “Dagger”).

  • secret – The API key, password or token to authenticate to this registry.

with_rootfs(directory: Directory) → Container[source]

Retrieves the container with the given directory mounted to /.

Parameters:

directory – Directory to mount.

with_secret_variable(name: str, secret: Secret) → Container[source]

Retrieves this container plus an env variable containing the given secret.

Parameters:

  • name – The name of the secret variable (e.g., “API_SECRET”).

  • secret – The identifier of the secret value.

with_service_binding(alias: str, service: Service) → Container[source]

Establish a runtime dependency on a service.

The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.

The service will be reachable from the container via the provided hostname alias.

The service dependency will also convey to any files or directories produced by the container.

Parameters:

  • alias – A name that can be used to reach the service from the container

  • service – Identifier of the service container

with_unix_socket(path: str, source: Socket, *, owner: str | None = '') → Container[source]

Retrieves this container plus a socket forwarded to the given Unix socket path.

Parameters:

  • path – Location of the forwarded Unix socket (e.g., “/tmp/socket”).

  • source – Identifier of the socket to forward.

  • owner – A user:group to set for the mounted socket. The user and group can either be an ID (1000:1000) or a name (foo:bar). If the group is omitted, it defaults to the same as the user.

with_user(name: str) → Container[source]

Retrieves this container with a different command user.

Parameters:

name – The user to set (e.g., “root”).

with_workdir(path: str) → Container[source]

Retrieves this container with a different working directory.

Parameters:

path – The path to set as the working directory (e.g., “/app”).

without_default_args() → Container[source]

Retrieves this container with unset default arguments for future commands.

without_entrypoint(*, keep_default_args: bool | None = False) → Container[source]

Retrieves this container with an unset command entrypoint.

Parameters:

keep_default_args – Don’t remove the default arguments when unsetting the entrypoint.

without_env_variable(name: str) → Container[source]

Retrieves this container minus the given environment variable.

Parameters:

name – The name of the environment variable (e.g., “HOST”).

without_exposed_port(port: int, *, protocol: NetworkProtocol | None = 'TCP') → Container[source]

Unexpose a previously exposed port.

Parameters:

  • port – Port number to unexpose

  • protocol – Port protocol to unexpose

without_focus() → Container[source]

Indicate that subsequent operations should not be featured more prominently in the UI.

This is the initial state of all containers.

without_label(name: str) → Container[source]

Retrieves this container minus the given environment label.

Parameters:

name – The name of the label to remove (e.g., “org.opencontainers.artifact.created”).

without_mount(path: str) → Container[source]

Retrieves this container after unmounting everything at the given path.

Parameters:

path – Location of the cache directory (e.g., “/cache/node_modules”).

without_registry_auth(address: str) → Container[source]

Retrieves this container without the registry authentication of a given address.

Parameters:

address – Registry’s address to remove the authentication from. Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).

without_unix_socket(path: str) → Container[source]

Retrieves this container with a previously added Unix socket removed.

Parameters:

path – Location of the socket to remove (e.g., “/tmp/socket”).

without_user() → Container[source]

Retrieves this container with an unset command user.

Should default to root.

without_workdir() → Container[source]

Retrieves this container with an unset working directory.

Should default to “/”.

async workdir() → str[source]

Retrieves the working directory for all commands.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.ContainerID

Bases: Scalar

The ContainerID scalar type represents an identifier for an object of type Container.

class dagger.Directory(ctx: Context)

Bases: Type

A directory.

as_module(*, source_subpath: str | None = '') → Module[source]

Load the directory as a Dagger module

Parameters:

source_subpath – An optional subpath of the directory which contains the module’s source code. This is needed when the module code is in a subdirectory but requires parent directories to be loaded in order to execute. For example, the module source code may need a go.mod, project.toml, package.json, etc. file from a parent directory. If not set, the module source code is loaded from the root of the directory.

diff(other: Directory) → Directory[source]

Gets the difference between this directory and an another directory.

Parameters:

other – Identifier of the directory to compare.

directory(path: str) → Directory[source]

Retrieves a directory at the given path.

Parameters:

path – Location of the directory to retrieve (e.g., “/src”).

docker_build(*, platform: Platform | None = None, dockerfile: str | None = 'Dockerfile', target: str | None = '', build_args: Sequence[BuildArg] | None = [], secrets: Sequence[Secret] | None = []) → Container[source]

Builds a new Docker container from this directory.

Parameters:

  • platform – The platform to build.

  • dockerfile – Path to the Dockerfile to use (e.g., “frontend.Dockerfile”).

  • target – Target build stage to build.

  • build_args – Build arguments to use in the build.

  • secrets – Secrets to pass to the build. They will be mounted at /run/secrets/[secret-name].

async entries(*, path: str | None = None) → list[str][source]

Returns a list of files and directories at the given path.

Parameters:

path – Location of the directory to look at (e.g., “/src”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async export(path: str) → bool[source]

Writes the contents of the directory to a path on the host.

Parameters:

path – Location of the copied directory (e.g., “logs/”).

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:
file(path: str) → File[source]

Retrieves a file at the given path.

Parameters:

path – Location of the file to retrieve (e.g., “README.md”).

async glob(pattern: str) → list[str][source]

Returns a list of files and directories that matche the given pattern.

Parameters:

pattern – Pattern to match (e.g., “*.md”).

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async id() → DirectoryID[source]

A unique identifier for this Directory.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The DirectoryID scalar type represents an identifier for an object of type Directory.

Return type:

DirectoryID

Raises:
pipeline(name: str, *, description: str | None = '', labels: Sequence[PipelineLabel] | None = []) → Directory[source]

Creates a named sub-pipeline.

Parameters:

  • name – Name of the sub-pipeline.

  • description – Description of the sub-pipeline.

  • labels – Labels to apply to the sub-pipeline.

async sync() → Directory[source]

Force evaluation in the engine.

Raises:
with_(cb: Callable[[Directory], Directory]) → Directory[source]

Call the provided callable with current Directory.

This is useful for reusability and readability by not breaking the calling chain.

with_directory(path: str, directory: Directory, *, exclude: Sequence[str] | None = [], include: Sequence[str] | None = []) → Directory[source]

Retrieves this directory plus a directory written at the given path.

Parameters:

  • path – Location of the written directory (e.g., “/src/”).

  • directory – Identifier of the directory to copy.

  • exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

  • include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

with_file(path: str, source: File, *, permissions: int | None = None) → Directory[source]

Retrieves this directory plus the contents of the given file copied to the given path.

Parameters:

  • path – Location of the copied file (e.g., “/file.txt”).

  • source – Identifier of the file to copy.

  • permissions – Permission given to the copied file (e.g., 0600).

with_new_directory(path: str, *, permissions: int | None = 420) → Directory[source]

Retrieves this directory plus a new directory created at the given path.

Parameters:

  • path – Location of the directory created (e.g., “/logs”).

  • permissions – Permission granted to the created directory (e.g., 0777).

with_new_file(path: str, contents: str, *, permissions: int | None = 420) → Directory[source]

Retrieves this directory plus a new file written at the given path.

Parameters:

  • path – Location of the written file (e.g., “/file.txt”).

  • contents – Content of the written file (e.g., “Hello world!”).

  • permissions – Permission given to the copied file (e.g., 0600).

with_timestamps(timestamp: int) → Directory[source]

Retrieves this directory with all file/dir timestamps set to the given time.

Parameters:

timestamp – Timestamp to set dir/files in. Formatted in seconds following Unix epoch (e.g., 1672531199).

without_directory(path: str) → Directory[source]

Retrieves this directory with the directory at the given path removed.

Parameters:

path – Location of the directory to remove (e.g., “.github/”).

without_file(path: str) → Directory[source]

Retrieves this directory with the file at the given path removed.

Parameters:

path – Location of the file to remove (e.g., “/file.txt”).

class dagger.DirectoryID

Bases: Scalar

The DirectoryID scalar type represents an identifier for an object of type Directory.

class dagger.EnvVariable(ctx: Context)

Bases: Type

An environment variable name and value.

async id() → EnvVariableID[source]

A unique identifier for this EnvVariable.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The EnvVariableID scalar type represents an identifier for an object of type EnvVariable.

Return type:

EnvVariableID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async value() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.EnvVariableID

Bases: Scalar

The EnvVariableID scalar type represents an identifier for an object of type EnvVariable.

class dagger.FieldTypeDef(ctx: Context)

Bases: Type

A definition of a field on a custom object defined in a Module. A field on an object has a static value, as opposed to a function on an object whose value is computed by invoking code (and can accept arguments).

async description() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async id() → FieldTypeDefID[source]

A unique identifier for this FieldTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The FieldTypeDefID scalar type represents an identifier for an object of type FieldTypeDef.

Return type:

FieldTypeDefID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
type_def() → TypeDef[source]
class dagger.FieldTypeDefID

Bases: Scalar

The FieldTypeDefID scalar type represents an identifier for an object of type FieldTypeDef.

class dagger.File(ctx: Context)

Bases: Type

A file.

async contents() → str[source]

Retrieves the contents of the file.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async export(path: str, *, allow_parent_dir_path: bool | None = False) → bool[source]

Writes the file to a file path on the host.

Parameters:

  • path – Location of the written directory (e.g., “output.txt”).

  • allow_parent_dir_path – If allowParentDirPath is true, the path argument can be a directory path, in which case the file will be created in that directory.

Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:
async id() → FileID[source]

A unique identifier for this File.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The FileID scalar type represents an identifier for an object of type File.

Return type:

FileID

Raises:
async name() → str[source]

Retrieves the name of the file.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async size() → int[source]

Retrieves the size of the file, in bytes.

Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:
async sync() → File[source]

Force evaluation in the engine.

Raises:
with_(cb: Callable[[File], File]) → File[source]

Call the provided callable with current File.

This is useful for reusability and readability by not breaking the calling chain.

with_timestamps(timestamp: int) → File[source]

Retrieves this file with its created/modified timestamps set to the given time.

Parameters:

timestamp – Timestamp to set dir/files in. Formatted in seconds following Unix epoch (e.g., 1672531199).

class dagger.FileID

Bases: Scalar

The FileID scalar type represents an identifier for an object of type File.

class dagger.Function(ctx: Context)

Bases: Type

Function represents a resolver provided by a Module. A function always evaluates against a parent object and is given a set of named arguments.

async args() → list[FunctionArg][source]
async description() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async id() → FunctionID[source]

A unique identifier for this Function.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The FunctionID scalar type represents an identifier for an object of type Function.

Return type:

FunctionID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
return_type() → TypeDef[source]
with_(cb: Callable[[Function], Function]) → Function[source]

Call the provided callable with current Function.

This is useful for reusability and readability by not breaking the calling chain.

with_arg(name: str, type_def: TypeDef, *, description: str | None = '', default_value: JSON | None = None) → Function[source]

Returns the function with the provided argument

Parameters:

  • name – The name of the argument

  • type_def – The type of the argument

  • description – A doc string for the argument, if any

  • default_value – A default value to use for this argument if not explicitly set by the caller, if any

with_description(description: str) → Function[source]

Returns the function with the given doc string.

Parameters:

description – The doc string to set.

class dagger.FunctionArg(ctx: Context)

Bases: Type

An argument accepted by a function. This is a specification for an argument at function definition time, not an argument passed at function call time.

async default_value() → JSON[source]
Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:
async description() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async id() → FunctionArgID[source]

A unique identifier for this FunctionArg.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The FunctionArgID scalar type represents an identifier for an object of type FunctionArg.

Return type:

FunctionArgID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
type_def() → TypeDef[source]
class dagger.FunctionArgID

Bases: Scalar

The FunctionArgID scalar type represents an identifier for an object of type FunctionArg.

class dagger.FunctionCall(ctx: Context)

Bases: Type

An active function call.

async id() → FunctionCallID[source]

A unique identifier for this FunctionCall.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The FunctionCallID scalar type represents an identifier for an object of type FunctionCall.

Return type:

FunctionCallID

Raises:
async input_args() → list[FunctionCallArgValue][source]
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async parent() → JSON[source]
Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:
async parent_name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async return_value(value: JSON) → Void | None[source]

Set the return value of the function call to the provided value.

Parameters:

value – JSON serialization of the return value.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:
class dagger.FunctionCallArgValue(ctx: Context)

Bases: Type

A value passed as a named argument to a function call.

async id() → FunctionCallArgValueID[source]

A unique identifier for this FunctionCallArgValue.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The FunctionCallArgValueID scalar type represents an identifier for an object of type FunctionCallArgValue.

Return type:

FunctionCallArgValueID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async value() → JSON[source]
Returns:

An arbitrary JSON-encoded value.

Return type:

JSON

Raises:
class dagger.FunctionCallArgValueID

Bases: Scalar

The FunctionCallArgValueID scalar type represents an identifier for an object of type FunctionCallArgValue.

class dagger.FunctionCallID

Bases: Scalar

The FunctionCallID scalar type represents an identifier for an object of type FunctionCall.

class dagger.FunctionID

Bases: Scalar

The FunctionID scalar type represents an identifier for an object of type Function.

class dagger.GeneratedCode(ctx: Context)

Bases: Type

The result of running an SDK’s codegen.

code() → Directory[source]
async id() → GeneratedCodeID[source]

A unique identifier for this GeneratedCode.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The GeneratedCodeID scalar type represents an identifier for an object of type GeneratedCode.

Return type:

GeneratedCodeID

Raises:
async vcs_generated_paths() → list[str][source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async vcs_ignored_paths() → list[str][source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
with_(cb: Callable[[GeneratedCode], GeneratedCode]) → GeneratedCode[source]

Call the provided callable with current GeneratedCode.

This is useful for reusability and readability by not breaking the calling chain.

with_vcs_generated_paths(paths: Sequence[str]) → GeneratedCode[source]

Set the list of paths to mark generated in version control.

with_vcs_ignored_paths(paths: Sequence[str]) → GeneratedCode[source]

Set the list of paths to ignore in version control.

class dagger.GeneratedCodeID

Bases: Scalar

The GeneratedCodeID scalar type represents an identifier for an object of type GeneratedCode.

class dagger.GitRef(ctx: Context)

Bases: Type

A git ref (tag, branch, or commit).

async commit() → str[source]

The resolved commit id at this ref.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async id() → GitRefID[source]

A unique identifier for this GitRef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The GitRefID scalar type represents an identifier for an object of type GitRef.

Return type:

GitRefID

Raises:
tree(*, ssh_known_hosts: str | None = None, ssh_auth_socket: Socket | None = None) → Directory[source]

The filesystem tree at this ref.

Parameters:

  • ssh_known_hosts – DEPRECATED: This option should be passed to git instead.

  • ssh_auth_socket – DEPRECATED: This option should be passed to git instead.

class dagger.GitRefID

Bases: Scalar

The GitRefID scalar type represents an identifier for an object of type GitRef.

class dagger.GitRepository(ctx: Context)

Bases: Type

A git repository.

branch(name: str) → GitRef[source]

Returns details of a branch.

Parameters:

name – Branch’s name (e.g., “main”).

commit(id: str) → GitRef[source]

Returns details of a commit.

Parameters:

id – Identifier of the commit (e.g., “b6315d8f2810962c601af73f86831f6866ea798b”).

async id() → GitRepositoryID[source]

A unique identifier for this GitRepository.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The GitRepositoryID scalar type represents an identifier for an object of type GitRepository.

Return type:

GitRepositoryID

Raises:
tag(name: str) → GitRef[source]

Returns details of a tag.

Parameters:

name – Tag’s name (e.g., “v0.3.9”).

class dagger.GitRepositoryID

Bases: Scalar

The GitRepositoryID scalar type represents an identifier for an object of type GitRepository.

class dagger.Host(ctx: Context)

Bases: Type

Information about the host environment.

directory(path: str, *, exclude: Sequence[str] | None = [], include: Sequence[str] | None = []) → Directory[source]

Accesses a directory on the host.

Parameters:

  • path – Location of the directory to access (e.g., “.”).

  • exclude – Exclude artifacts that match the given pattern (e.g., [“node_modules/”, “.git*”]).

  • include – Include only artifacts that match the given pattern (e.g., [“app/”, “package.*”]).

file(path: str) → File[source]

Accesses a file on the host.

Parameters:

path – Location of the file to retrieve (e.g., “README.md”).

async id() → HostID[source]

A unique identifier for this Host.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The HostID scalar type represents an identifier for an object of type Host.

Return type:

HostID

Raises:
service(ports: Sequence[PortForward], *, host: str | None = 'localhost') → Service[source]

Creates a service that forwards traffic to a specified address via the host.

Parameters:

  • ports – Ports to expose via the service, forwarding through the host network. If a port’s frontend is unspecified or 0, it defaults to the same as the backend port. An empty set of ports is not valid; an error will be returned.

  • host – Upstream host to forward traffic to.

set_secret_file(name: str, path: str) → Secret[source]

Sets a secret given a user-defined name and the file path on the host, and returns the secret.

The file is limited to a size of 512000 bytes.

Parameters:

  • name – The user defined name for this secret.

  • path – Location of the file to set as a secret.

tunnel(service: Service, *, ports: Sequence[PortForward] | None = [], native: bool | None = False) → Service[source]

Creates a tunnel that forwards traffic from the host to a service.

Parameters:

  • service – Service to send traffic from the tunnel.

  • ports – Configure explicit port forwarding rules for the tunnel. If a port’s frontend is unspecified or 0, a random port will be chosen by the host. If no ports are given, all of the service’s ports are forwarded. If native is true, each port maps to the same port on the host. If native is false, each port maps to a random port chosen by the host. If ports are given and native is true, the ports are additive.

  • native – Map each service port to the same port on the host, as if the service were running natively. Note: enabling may result in port conflicts.

unix_socket(path: str) → Socket[source]

Accesses a Unix socket on the host.

Parameters:

path – Location of the Unix socket (e.g., “/var/run/docker.sock”).

class dagger.HostID

Bases: Scalar

The HostID scalar type represents an identifier for an object of type Host.

class dagger.ImageLayerCompression(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Compression algorithm to use for image layers.

EStarGZ = 'EStarGZ'
Gzip = 'Gzip'
Uncompressed = 'Uncompressed'
Zstd = 'Zstd'
class dagger.ImageMediaTypes(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Mediatypes to use in published or exported image metadata.

DockerMediaTypes = 'DockerMediaTypes'
OCIMediaTypes = 'OCIMediaTypes'
class dagger.InterfaceTypeDef(ctx: Context)

Bases: Type

A definition of a custom interface defined in a Module.

async description() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async functions() → list[Function][source]
async id() → InterfaceTypeDefID[source]

A unique identifier for this InterfaceTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The InterfaceTypeDefID scalar type represents an identifier for an object of type InterfaceTypeDef.

Return type:

InterfaceTypeDefID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async source_module_name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.InterfaceTypeDefID

Bases: Scalar

The InterfaceTypeDefID scalar type represents an identifier for an object of type InterfaceTypeDef.

class dagger.JSON

Bases: Scalar

An arbitrary JSON-encoded value.

class dagger.Label(ctx: Context)

Bases: Type

A simple key value object that represents a label.

async id() → LabelID[source]

A unique identifier for this Label.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The LabelID scalar type represents an identifier for an object of type Label.

Return type:

LabelID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async value() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.LabelID

Bases: Scalar

The LabelID scalar type represents an identifier for an object of type Label.

class dagger.ListTypeDef(ctx: Context)

Bases: Type

A definition of a list type in a Module.

element_type_def() → TypeDef[source]
async id() → ListTypeDefID[source]

A unique identifier for this ListTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ListTypeDefID scalar type represents an identifier for an object of type ListTypeDef.

Return type:

ListTypeDefID

Raises:
class dagger.ListTypeDefID

Bases: Scalar

The ListTypeDefID scalar type represents an identifier for an object of type ListTypeDef.

class dagger.Module(ctx: Context)

Bases: Type

A Dagger module.

async dependencies() → list[Module][source]
async dependency_config() → list[str][source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async description() → str | None[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:
generated_code() → GeneratedCode[source]
async id() → ModuleID[source]

A unique identifier for this Module.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ModuleID scalar type represents an identifier for an object of type Module.

Return type:

ModuleID

Raises:
initialize() → Module[source]

Retrieves the module with the objects loaded via its SDK.

async interfaces() → list[TypeDef][source]
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async objects() → list[TypeDef][source]
async sdk() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async serve() → Void | None[source]

Serve a module’s API in the current session.

Note: this can only be called once per session. In the future, it could return a stream or service to remove the side effect.

Returns:

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.

Return type:

Void | None

Raises:
source_directory() → Directory[source]
async source_directory_subpath() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
with_(cb: Callable[[Module], Module]) → Module[source]

Call the provided callable with current Module.

This is useful for reusability and readability by not breaking the calling chain.

with_interface(iface: TypeDef) → Module[source]

This module plus the given Interface type and associated functions

with_object(object: TypeDef) → Module[source]

This module plus the given Object type and associated functions.

with_source(directory: Directory, *, subpath: str | None = '') → Module[source]

Retrieves the module with basic configuration loaded, ready for initialization.

Parameters:

  • directory – The directory containing the module’s source code.

  • subpath – An optional subpath of the directory which contains the module’s source code. This is needed when the module code is in a subdirectory but requires parent directories to be loaded in order to execute. For example, the module source code may need a go.mod, project.toml, package.json, etc. file from a parent directory. If not set, the module source code is loaded from the root of the directory.

class dagger.ModuleConfig(ctx: Context)

Bases: Type

Static configuration for a module (e.g. parsed contents of dagger.json)

async dependencies() → list[str][source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async exclude() → list[str][source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async id() → ModuleConfigID[source]

A unique identifier for this ModuleConfig.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ModuleConfigID scalar type represents an identifier for an object of type ModuleConfig.

Return type:

ModuleConfigID

Raises:
async include() → list[str][source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

list[str]

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async root() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async sdk() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.ModuleConfigID

Bases: Scalar

The ModuleConfigID scalar type represents an identifier for an object of type ModuleConfig.

class dagger.ModuleID

Bases: Scalar

The ModuleID scalar type represents an identifier for an object of type Module.

class dagger.NetworkProtocol(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Transport layer network protocol associated to a port.

TCP = 'TCP'
UDP = 'UDP'
class dagger.ObjectTypeDef(ctx: Context)

Bases: Type

A definition of a custom object defined in a Module.

constructor() → Function[source]
async description() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async fields() → list[FieldTypeDef][source]
async functions() → list[Function][source]
async id() → ObjectTypeDefID[source]

A unique identifier for this ObjectTypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ObjectTypeDefID scalar type represents an identifier for an object of type ObjectTypeDef.

Return type:

ObjectTypeDefID

Raises:
async name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async source_module_name() → str[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.ObjectTypeDefID

Bases: Scalar

The ObjectTypeDefID scalar type represents an identifier for an object of type ObjectTypeDef.

class dagger.PipelineLabel(name: str, value: str)

Bases: Input

Key value object that represents a pipeline label.

name: str
value: str
class dagger.Platform

Bases: Scalar

The platform config OS and architecture in a Container. The format is [os]/[platform]/[version] (e.g., “darwin/arm64/v7”, “windows/amd64”, “linux/arm64”).

class dagger.Port(ctx: Context)

Bases: Type

A port exposed by a container.

async description() → str | None[source]
Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str | None

Raises:
async id() → PortID[source]

A unique identifier for this Port.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The PortID scalar type represents an identifier for an object of type Port.

Return type:

PortID

Raises:
async port() → int[source]
Returns:

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Return type:

int

Raises:
async protocol() → NetworkProtocol[source]
Returns:

Transport layer network protocol associated to a port.

Return type:

NetworkProtocol

Raises:
class dagger.PortForward(backend: int, frontend: int | None = None, protocol: NetworkProtocol | None = 'TCP')

Bases: Input

Port forwarding rules for tunneling network traffic.

backend: int
frontend: int | None
protocol: NetworkProtocol | None
class dagger.PortID

Bases: Scalar

The PortID scalar type represents an identifier for an object of type Port.

class dagger.Secret(ctx: Context)

Bases: Type

A reference to a secret value, which can be handled more safely than the value itself.

async id() → SecretID[source]

A unique identifier for this Secret.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The SecretID scalar type represents an identifier for an object of type Secret.

Return type:

SecretID

Raises:
async plaintext() → str[source]

The value of this secret.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
class dagger.SecretID

Bases: Scalar

The SecretID scalar type represents an identifier for an object of type Secret.

class dagger.Service(ctx: Context)

Bases: Type

A content-addressed service providing TCP connectivity.

async endpoint(*, port: int | None = None, scheme: str | None = '') → str[source]

Retrieves an endpoint that clients can use to reach this container.

If no port is specified, the first exposed port is used. If none exist an error is returned.

If a scheme is specified, a URL is returned. Otherwise, a host:port pair is returned.

Parameters:

  • port – The exposed port number for the endpoint

  • scheme – Return a URL with the given scheme, eg. http for http://

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async hostname() → str[source]

Retrieves a hostname which can be used by clients to reach this container.

Returns:

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Return type:

str

Raises:
async id() → ServiceID[source]

A unique identifier for this Service.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The ServiceID scalar type represents an identifier for an object of type Service.

Return type:

ServiceID

Raises:
async ports() → list[Port][source]

Retrieves the list of ports provided by the service.

async start() → Service[source]

Start the service and wait for its health checks to succeed.

Services bound to a Container do not need to be manually started.

Raises:
async stop() → Service[source]

Stop the service.

Raises:
class dagger.ServiceID

Bases: Scalar

The ServiceID scalar type represents an identifier for an object of type Service.

class dagger.Socket(ctx: Context)

Bases: Type

A Unix or TCP/IP socket that can be mounted into a container.

async id() → SocketID[source]

A unique identifier for this Socket.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The SocketID scalar type represents an identifier for an object of type Socket.

Return type:

SocketID

Raises:
class dagger.SocketID

Bases: Scalar

The SocketID scalar type represents an identifier for an object of type Socket.

class dagger.TypeDef(ctx: Context)

Bases: Type

A definition of a parameter or return type in a Module.

as_interface() → InterfaceTypeDef[source]
as_list() → ListTypeDef[source]
as_object() → ObjectTypeDef[source]
async id() → TypeDefID[source]

A unique identifier for this TypeDef.

Note

This is lazily evaluated, no operation is actually run.

Returns:

The TypeDefID scalar type represents an identifier for an object of type TypeDef.

Return type:

TypeDefID

Raises:
async kind() → TypeDefKind[source]
Returns:

Distinguishes the different kinds of TypeDefs.

Return type:

TypeDefKind

Raises:
async optional() → bool[source]
Returns:

The Boolean scalar type represents true or false.

Return type:

bool

Raises:
with_(cb: Callable[[TypeDef], TypeDef]) → TypeDef[source]

Call the provided callable with current TypeDef.

This is useful for reusability and readability by not breaking the calling chain.

with_constructor(function: Function) → TypeDef[source]

Adds a function for constructing a new instance of an Object TypeDef, failing if the type is not an object.

with_field(name: str, type_def: TypeDef, *, description: str | None = '') → TypeDef[source]

Adds a static field for an Object TypeDef, failing if the type is not an object.

Parameters:

  • name – The name of the field in the object

  • type_def – The type of the field

  • description – A doc string for the field, if any

with_function(function: Function) → TypeDef[source]

Adds a function for an Object or Interface TypeDef, failing if the type is not one of those kinds.

with_interface(name: str, *, description: str | None = '') → TypeDef[source]

Returns a TypeDef of kind Interface with the provided name.

with_kind(kind: TypeDefKind) → TypeDef[source]

Sets the kind of the type.

with_list_of(element_type: TypeDef) → TypeDef[source]

Returns a TypeDef of kind List with the provided type for its elements.

with_object(name: str, *, description: str | None = '') → TypeDef[source]

Returns a TypeDef of kind Object with the provided name.

Note that an object’s fields and functions may be omitted if the intent is only to refer to an object. This is how functions are able to return their own object, or any other circular reference.

with_optional(optional: bool) → TypeDef[source]

Sets whether this type can be set to null.

class dagger.TypeDefID

Bases: Scalar

The TypeDefID scalar type represents an identifier for an object of type TypeDef.

class dagger.TypeDefKind(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Distinguishes the different kinds of TypeDefs.

BOOLEAN_KIND = 'BOOLEAN_KIND'
INTEGER_KIND = 'INTEGER_KIND'
INTERFACE_KIND = 'INTERFACE_KIND'
LIST_KIND = 'LIST_KIND'
OBJECT_KIND = 'OBJECT_KIND'
STRING_KIND = 'STRING_KIND'
VOID_KIND = 'VOID_KIND'
class dagger.Void

Bases: Scalar

The absence of a value. A Null Void is used as a placeholder for resolvers that do not return anything.