# Code generated by dagger. DO NOT EDIT.
import warnings
from collections.abc import Callable
from dataclasses import dataclass
from typing import Protocol, runtime_checkable
from typing_extensions import Self
from dagger.client._core import Arg
from dagger.client._guards import typecheck
from dagger.client.base import Enum, Input, Root, Scalar, Type
class AddressID(Scalar):
"""A unique identifier for an object."""
class BindingID(Scalar):
"""A unique identifier for an object."""
class CacheVolumeID(Scalar):
"""A unique identifier for an object."""
class ChangesetID(Scalar):
"""A unique identifier for an object."""
class CheckGroupID(Scalar):
"""A unique identifier for an object."""
class CheckID(Scalar):
"""A unique identifier for an object."""
class ClientFilesyncMirrorID(Scalar):
"""A unique identifier for an object."""
class CloudID(Scalar):
"""A unique identifier for an object."""
class ContainerID(Scalar):
"""A unique identifier for an object."""
class CurrentModuleID(Scalar):
"""A unique identifier for an object."""
class DiffStatID(Scalar):
"""A unique identifier for an object."""
class DirectoryID(Scalar):
"""A unique identifier for an object."""
class EngineCacheEntryID(Scalar):
"""A unique identifier for an object."""
class EngineCacheEntrySetID(Scalar):
"""A unique identifier for an object."""
class EngineCacheID(Scalar):
"""A unique identifier for an object."""
class EngineID(Scalar):
"""A unique identifier for an object."""
class EnumTypeDefID(Scalar):
"""A unique identifier for an object."""
class EnumValueTypeDefID(Scalar):
"""A unique identifier for an object."""
class EnvFileID(Scalar):
"""A unique identifier for an object."""
class EnvID(Scalar):
"""A unique identifier for an object."""
class EnvVariableID(Scalar):
"""A unique identifier for an object."""
class ErrorID(Scalar):
"""A unique identifier for an object."""
class ErrorValueID(Scalar):
"""A unique identifier for an object."""
class ExportableID(Scalar):
"""A unique identifier for an object."""
class FieldTypeDefID(Scalar):
"""A unique identifier for an object."""
class FileID(Scalar):
"""A unique identifier for an object."""
class FunctionArgID(Scalar):
"""A unique identifier for an object."""
class FunctionCallArgValueID(Scalar):
"""A unique identifier for an object."""
class FunctionCallID(Scalar):
"""A unique identifier for an object."""
class FunctionID(Scalar):
"""A unique identifier for an object."""
class GeneratedCodeID(Scalar):
"""A unique identifier for an object."""
class GeneratorGroupID(Scalar):
"""A unique identifier for an object."""
class GeneratorID(Scalar):
"""A unique identifier for an object."""
class GitRefID(Scalar):
"""A unique identifier for an object."""
class GitRepositoryID(Scalar):
"""A unique identifier for an object."""
class HTTPStateID(Scalar):
"""A unique identifier for an object."""
class HealthcheckConfigID(Scalar):
"""A unique identifier for an object."""
class HostID(Scalar):
"""A unique identifier for an object."""
class InputTypeDefID(Scalar):
"""A unique identifier for an object."""
class InterfaceTypeDefID(Scalar):
"""A unique identifier for an object."""
class JSON(Scalar):
"""An arbitrary JSON-encoded value."""
class JSONValueID(Scalar):
"""A unique identifier for an object."""
class LLMID(Scalar):
"""A unique identifier for an object."""
class LLMTokenUsageID(Scalar):
"""A unique identifier for an object."""
class LabelID(Scalar):
"""A unique identifier for an object."""
class ListTypeDefID(Scalar):
"""A unique identifier for an object."""
class ModuleConfigClientID(Scalar):
"""A unique identifier for an object."""
class ModuleID(Scalar):
"""A unique identifier for an object."""
class ModuleSourceID(Scalar):
"""A unique identifier for an object."""
class ObjectTypeDefID(Scalar):
"""A unique identifier for an object."""
class Platform(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 PortID(Scalar):
"""A unique identifier for an object."""
class RemoteGitMirrorID(Scalar):
"""A unique identifier for an object."""
class SDKConfigID(Scalar):
"""A unique identifier for an object."""
class ScalarTypeDefID(Scalar):
"""A unique identifier for an object."""
class SearchResultID(Scalar):
"""A unique identifier for an object."""
class SearchSubmatchID(Scalar):
"""A unique identifier for an object."""
class SecretID(Scalar):
"""A unique identifier for an object."""
class ServiceID(Scalar):
"""A unique identifier for an object."""
class SocketID(Scalar):
"""A unique identifier for an object."""
class SourceMapID(Scalar):
"""A unique identifier for an object."""
class StatID(Scalar):
"""A unique identifier for an object."""
class SyncerID(Scalar):
"""A unique identifier for an object."""
class TerminalID(Scalar):
"""A unique identifier for an object."""
class TypeDefID(Scalar):
"""A unique identifier for an object."""
class UpGroupID(Scalar):
"""A unique identifier for an object."""
class UpID(Scalar):
"""A unique identifier for an object."""
class Void(Scalar):
"""The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything."""
class WorkspaceID(Scalar):
"""A unique identifier for an object."""
class CacheSharingMode(Enum):
"""Sharing mode of the cache volume."""
LOCKED = "LOCKED"
"""Shares the cache volume amongst many build pipelines, but will serialize the writes"""
PRIVATE = "PRIVATE"
"""Keeps a cache volume for a single build pipeline"""
SHARED = "SHARED"
"""Shares the cache volume amongst many build pipelines"""
class ChangesetMergeConflict(Enum):
"""Strategy to use when merging changesets with conflicting
changes."""
FAIL = "FAIL"
"""Attempt the merge and fail if git merge fails due to conflicts"""
FAIL_EARLY = "FAIL_EARLY"
"""Fail before attempting merge if file-level conflicts are detected"""
LEAVE_CONFLICT_MARKERS = "LEAVE_CONFLICT_MARKERS"
"""Let git create conflict markers in files. For modify/delete conflicts, keeps the modified version. Fails on binary conflicts."""
PREFER_OURS = "PREFER_OURS"
"""The conflict is resolved by applying the version of the calling changeset"""
PREFER_THEIRS = "PREFER_THEIRS"
"""The conflict is resolved by applying the version of the other changeset"""
class ChangesetsMergeConflict(Enum):
"""Strategy to use when merging multiple changesets with git octopus
merge."""
FAIL = "FAIL"
"""Attempt the octopus merge and fail if git merge fails due to conflicts"""
FAIL_EARLY = "FAIL_EARLY"
"""Fail before attempting merge if file-level conflicts are detected between any changesets"""
class DiffStatKind(Enum):
"""The type of change for a diff stat entry."""
ADDED = "ADDED"
"""A file or directory was added."""
MODIFIED = "MODIFIED"
"""A file was modified."""
REMOVED = "REMOVED"
"""A file or directory was removed."""
RENAMED = "RENAMED"
"""A file was renamed."""
class ExistsType(Enum):
"""File type."""
DIRECTORY_TYPE = "DIRECTORY_TYPE"
"""Tests path is a directory"""
REGULAR_TYPE = "REGULAR_TYPE"
"""Tests path is a regular file"""
SYMLINK_TYPE = "SYMLINK_TYPE"
"""Tests path is a symlink"""
class FileType(Enum):
"""File type."""
DIRECTORY = "DIRECTORY"
"""directory file type"""
DIRECTORY_TYPE = "DIRECTORY"
"""directory file type"""
REGULAR = "REGULAR"
"""regular file type"""
REGULAR_TYPE = "REGULAR"
"""regular file type"""
SYMLINK = "SYMLINK"
"""symlink file type"""
SYMLINK_TYPE = "SYMLINK"
"""symlink file type"""
UNKNOWN = "UNKNOWN"
"""unknown file type"""
class FunctionCachePolicy(Enum):
"""The behavior configured for function result caching."""
Default = "Default"
Never = "Never"
PerSession = "PerSession"
class ImageLayerCompression(Enum):
"""Compression algorithm to use for image layers."""
EStarGZ = "EStarGZ"
ESTARGZ = "EStarGZ"
Gzip = "Gzip"
GZIP = "Gzip"
Uncompressed = "Uncompressed"
UNCOMPRESSED = "Uncompressed"
Zstd = "Zstd"
ZSTD = "Zstd"
class ImageMediaTypes(Enum):
"""Mediatypes to use in published or exported image metadata."""
DockerMediaTypes = "DockerMediaTypes"
DOCKER = "DockerMediaTypes"
OCIMediaTypes = "OCIMediaTypes"
OCI = "OCIMediaTypes"
class ModuleSourceExperimentalFeature(Enum):
"""Experimental features of a module"""
SELF_CALLS = "SELF_CALLS"
"""Self calls"""
class ModuleSourceKind(Enum):
"""The kind of module source."""
DIR_SOURCE = "DIR_SOURCE"
DIR = "DIR_SOURCE"
GIT_SOURCE = "GIT_SOURCE"
GIT = "GIT_SOURCE"
LOCAL_SOURCE = "LOCAL_SOURCE"
LOCAL = "LOCAL_SOURCE"
class NetworkProtocol(Enum):
"""Transport layer network protocol associated to a port."""
TCP = "TCP"
UDP = "UDP"
class ReturnType(Enum):
"""Expected return type of an execution"""
ANY = "ANY"
"""Any execution (exit codes 0-127 and 192-255)"""
FAILURE = "FAILURE"
"""A failed execution (exit codes 1-127 and 192-255)"""
SUCCESS = "SUCCESS"
"""A successful execution (exit code 0)"""
class TypeDefKind(Enum):
"""Distinguishes the different kinds of TypeDefs."""
BOOLEAN_KIND = "BOOLEAN_KIND"
"""A boolean value."""
BOOLEAN = "BOOLEAN_KIND"
"""A boolean value."""
ENUM_KIND = "ENUM_KIND"
"""A GraphQL enum type and its values
Always paired with an EnumTypeDef.
"""
ENUM = "ENUM_KIND"
"""A GraphQL enum type and its values
Always paired with an EnumTypeDef.
"""
FLOAT_KIND = "FLOAT_KIND"
"""A float value."""
FLOAT = "FLOAT_KIND"
"""A float value."""
INPUT_KIND = "INPUT_KIND"
"""A graphql input type, used only when representing the core API via TypeDefs."""
INPUT = "INPUT_KIND"
"""A graphql input type, used only when representing the core API via TypeDefs."""
INTEGER_KIND = "INTEGER_KIND"
"""An integer value."""
INTEGER = "INTEGER_KIND"
"""An integer value."""
INTERFACE_KIND = "INTERFACE_KIND"
"""Always paired with an InterfaceTypeDef.
A named type of functions that can be matched+implemented by other objects+interfaces.
"""
INTERFACE = "INTERFACE_KIND"
"""Always paired with an InterfaceTypeDef.
A named type of functions that can be matched+implemented by other objects+interfaces.
"""
LIST_KIND = "LIST_KIND"
"""Always paired with a ListTypeDef.
A list of values all having the same type.
"""
LIST = "LIST_KIND"
"""Always paired with a ListTypeDef.
A list of values all having the same type.
"""
OBJECT_KIND = "OBJECT_KIND"
"""Always paired with an ObjectTypeDef.
A named type defined in the GraphQL schema, with fields and functions.
"""
OBJECT = "OBJECT_KIND"
"""Always paired with an ObjectTypeDef.
A named type defined in the GraphQL schema, with fields and functions.
"""
SCALAR_KIND = "SCALAR_KIND"
"""A scalar value of any basic kind."""
SCALAR = "SCALAR_KIND"
"""A scalar value of any basic kind."""
STRING_KIND = "STRING_KIND"
"""A string value."""
STRING = "STRING_KIND"
"""A string value."""
VOID_KIND = "VOID_KIND"
"""A special kind used to signify that no value is returned.
This is used for functions that have no return value. The outer TypeDef specifying this Kind is always Optional, as the Void is never actually represented.
"""
VOID = "VOID_KIND"
"""A special kind used to signify that no value is returned.
This is used for functions that have no return value. The outer TypeDef specifying this Kind is always Optional, as the Void is never actually represented.
"""
@typecheck
@dataclass(slots=True)
class BuildArg(Input):
"""Key value object that represents a build argument."""
name: str
"""The build argument name."""
value: str
"""The build argument value."""
@typecheck
@dataclass(slots=True)
class PipelineLabel(Input):
"""Key value object that represents a pipeline label."""
name: str
"""Label name."""
value: str
"""Label value."""
@typecheck
@dataclass(slots=True)
class PortForward(Input):
"""Port forwarding rules for tunneling network traffic."""
backend: int
"""Destination port for traffic."""
frontend: int | None = None
"""Port to expose to clients. If unspecified, a default will be chosen."""
protocol: NetworkProtocol | None = NetworkProtocol.TCP
"""Transport layer protocol to use for traffic."""
@runtime_checkable
class Exportable(Protocol):
"""An object that can be exported to the host. Calling export writes
the object to a path on the host filesystem and returns the path that
was written."""
[docs]
async def export(self, path: str) -> str: ...
@typecheck
class _ExportableClient(Type):
"""Concrete client for Exportable interface."""
@classmethod
def _graphql_name(cls) -> str:
return "Exportable"
async def export(self, path: str) -> str:
"""Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("export", _args)
return await _ctx.execute(str)
async def id(self) -> str:
"""Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@runtime_checkable
class Node(Protocol):
"""An object with a globally unique ID."""
@typecheck
class _NodeClient(Type):
"""Concrete client for Node interface."""
@classmethod
def _graphql_name(cls) -> str:
return "Node"
async def id(self) -> str:
"""Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@runtime_checkable
class Syncer(Protocol):
"""An object that can be force-evaluated. Calling sync ensures that
the object's entire dependency DAG has been evaluated, returning the
object's ID once complete."""
[docs]
async def sync(self) -> Self: ...
@typecheck
class _SyncerClient(Type):
"""Concrete client for Syncer interface."""
@classmethod
def _graphql_name(cls) -> str:
return "Syncer"
async def id(self) -> str:
"""Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
async def sync(self) -> Self:
"""Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
@typecheck
class Address(Type):
"""A standardized address to load containers, directories, secrets,
and other object types. Address format depends on the type, and is
validated at type selection."""
[docs]
def container(self) -> "Container":
"""Load a container from the address."""
_args: list[Arg] = []
_ctx = self._select("container", _args)
return Container(_ctx)
[docs]
def directory(
self,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
no_cache: bool | None = False,
) -> "Directory":
"""Load a directory from the address."""
_args = [
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
Arg("noCache", no_cache, False),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
def file(
self,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
no_cache: bool | None = False,
) -> "File":
"""Load a file from the address."""
_args = [
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
Arg("noCache", no_cache, False),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs]
def git_ref(self) -> "GitRef":
"""Load a git ref (branch, tag or commit) from the address."""
_args: list[Arg] = []
_ctx = self._select("gitRef", _args)
return GitRef(_ctx)
[docs]
def git_repository(self) -> "GitRepository":
"""Load a git repository from the address."""
_args: list[Arg] = []
_ctx = self._select("gitRepository", _args)
return GitRepository(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this Address.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def secret(self) -> "Secret":
"""Load a secret from the address."""
_args: list[Arg] = []
_ctx = self._select("secret", _args)
return Secret(_ctx)
[docs]
def service(self) -> "Service":
"""Load a service from the address."""
_args: list[Arg] = []
_ctx = self._select("service", _args)
return Service(_ctx)
[docs]
def socket(self) -> "Socket":
"""Load a local socket from the address."""
_args: list[Arg] = []
_ctx = self._select("socket", _args)
return Socket(_ctx)
[docs]
async def value(self) -> str:
"""The address value
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
@typecheck
class Binding(Type):
[docs]
def as_address(self) -> Address:
"""Retrieve the binding value, as type Address"""
_args: list[Arg] = []
_ctx = self._select("asAddress", _args)
return Address(_ctx)
[docs]
def as_cache_volume(self) -> "CacheVolume":
"""Retrieve the binding value, as type CacheVolume"""
_args: list[Arg] = []
_ctx = self._select("asCacheVolume", _args)
return CacheVolume(_ctx)
[docs]
def as_changeset(self) -> "Changeset":
"""Retrieve the binding value, as type Changeset"""
_args: list[Arg] = []
_ctx = self._select("asChangeset", _args)
return Changeset(_ctx)
[docs]
def as_check(self) -> "Check":
"""Retrieve the binding value, as type Check"""
_args: list[Arg] = []
_ctx = self._select("asCheck", _args)
return Check(_ctx)
[docs]
def as_check_group(self) -> "CheckGroup":
"""Retrieve the binding value, as type CheckGroup"""
_args: list[Arg] = []
_ctx = self._select("asCheckGroup", _args)
return CheckGroup(_ctx)
[docs]
def as_cloud(self) -> "Cloud":
"""Retrieve the binding value, as type Cloud"""
_args: list[Arg] = []
_ctx = self._select("asCloud", _args)
return Cloud(_ctx)
[docs]
def as_container(self) -> "Container":
"""Retrieve the binding value, as type Container"""
_args: list[Arg] = []
_ctx = self._select("asContainer", _args)
return Container(_ctx)
[docs]
def as_diff_stat(self) -> "DiffStat":
"""Retrieve the binding value, as type DiffStat"""
_args: list[Arg] = []
_ctx = self._select("asDiffStat", _args)
return DiffStat(_ctx)
[docs]
def as_directory(self) -> "Directory":
"""Retrieve the binding value, as type Directory"""
_args: list[Arg] = []
_ctx = self._select("asDirectory", _args)
return Directory(_ctx)
[docs]
def as_env(self) -> "Env":
"""Retrieve the binding value, as type Env"""
_args: list[Arg] = []
_ctx = self._select("asEnv", _args)
return Env(_ctx)
[docs]
def as_env_file(self) -> "EnvFile":
"""Retrieve the binding value, as type EnvFile"""
_args: list[Arg] = []
_ctx = self._select("asEnvFile", _args)
return EnvFile(_ctx)
[docs]
def as_file(self) -> "File":
"""Retrieve the binding value, as type File"""
_args: list[Arg] = []
_ctx = self._select("asFile", _args)
return File(_ctx)
[docs]
def as_generator(self) -> "Generator":
"""Retrieve the binding value, as type Generator"""
_args: list[Arg] = []
_ctx = self._select("asGenerator", _args)
return Generator(_ctx)
[docs]
def as_generator_group(self) -> "GeneratorGroup":
"""Retrieve the binding value, as type GeneratorGroup"""
_args: list[Arg] = []
_ctx = self._select("asGeneratorGroup", _args)
return GeneratorGroup(_ctx)
[docs]
def as_git_ref(self) -> "GitRef":
"""Retrieve the binding value, as type GitRef"""
_args: list[Arg] = []
_ctx = self._select("asGitRef", _args)
return GitRef(_ctx)
[docs]
def as_git_repository(self) -> "GitRepository":
"""Retrieve the binding value, as type GitRepository"""
_args: list[Arg] = []
_ctx = self._select("asGitRepository", _args)
return GitRepository(_ctx)
[docs]
def as_http_state(self) -> "HTTPState":
"""Retrieve the binding value, as type HTTPState"""
_args: list[Arg] = []
_ctx = self._select("asHTTPState", _args)
return HTTPState(_ctx)
[docs]
def as_json_value(self) -> "JSONValue":
"""Retrieve the binding value, as type JSONValue"""
_args: list[Arg] = []
_ctx = self._select("asJSONValue", _args)
return JSONValue(_ctx)
[docs]
def as_module(self) -> "Module":
"""Retrieve the binding value, as type Module"""
_args: list[Arg] = []
_ctx = self._select("asModule", _args)
return Module(_ctx)
[docs]
def as_module_config_client(self) -> "ModuleConfigClient":
"""Retrieve the binding value, as type ModuleConfigClient"""
_args: list[Arg] = []
_ctx = self._select("asModuleConfigClient", _args)
return ModuleConfigClient(_ctx)
[docs]
def as_module_source(self) -> "ModuleSource":
"""Retrieve the binding value, as type ModuleSource"""
_args: list[Arg] = []
_ctx = self._select("asModuleSource", _args)
return ModuleSource(_ctx)
[docs]
def as_search_result(self) -> "SearchResult":
"""Retrieve the binding value, as type SearchResult"""
_args: list[Arg] = []
_ctx = self._select("asSearchResult", _args)
return SearchResult(_ctx)
[docs]
def as_search_submatch(self) -> "SearchSubmatch":
"""Retrieve the binding value, as type SearchSubmatch"""
_args: list[Arg] = []
_ctx = self._select("asSearchSubmatch", _args)
return SearchSubmatch(_ctx)
[docs]
def as_secret(self) -> "Secret":
"""Retrieve the binding value, as type Secret"""
_args: list[Arg] = []
_ctx = self._select("asSecret", _args)
return Secret(_ctx)
[docs]
def as_service(self) -> "Service":
"""Retrieve the binding value, as type Service"""
_args: list[Arg] = []
_ctx = self._select("asService", _args)
return Service(_ctx)
[docs]
def as_socket(self) -> "Socket":
"""Retrieve the binding value, as type Socket"""
_args: list[Arg] = []
_ctx = self._select("asSocket", _args)
return Socket(_ctx)
[docs]
def as_stat(self) -> "Stat":
"""Retrieve the binding value, as type Stat"""
_args: list[Arg] = []
_ctx = self._select("asStat", _args)
return Stat(_ctx)
[docs]
async def as_string(self) -> str | None:
"""Returns the binding's string value
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("asString", _args)
return await _ctx.execute(str | None)
[docs]
def as_up(self) -> "Up":
"""Retrieve the binding value, as type Up"""
_args: list[Arg] = []
_ctx = self._select("asUp", _args)
return Up(_ctx)
[docs]
def as_up_group(self) -> "UpGroup":
"""Retrieve the binding value, as type UpGroup"""
_args: list[Arg] = []
_ctx = self._select("asUpGroup", _args)
return UpGroup(_ctx)
[docs]
def as_workspace(self) -> "Workspace":
"""Retrieve the binding value, as type Workspace"""
_args: list[Arg] = []
_ctx = self._select("asWorkspace", _args)
return Workspace(_ctx)
[docs]
async def digest(self) -> str:
"""Returns the digest of the binding value
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("digest", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this Binding.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def is_null(self) -> bool:
"""Returns true if the binding is null
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("isNull", _args)
return await _ctx.execute(bool)
[docs]
async def name(self) -> str:
"""Returns the binding name
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def type_name(self) -> str:
"""Returns the binding type
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("typeName", _args)
return await _ctx.execute(str)
@typecheck
class CacheVolume(Type):
"""A directory whose contents persist across runs."""
[docs]
async def id(self) -> str:
"""A unique identifier for this CacheVolume.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class Changeset(Type):
"""A comparison between two directories representing changes that can
be applied."""
[docs]
async def added_paths(self) -> list[str]:
"""Files and directories that were added in the newer directory.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("addedPaths", _args)
return await _ctx.execute(list[str])
[docs]
def after(self) -> "Directory":
"""The newer/upper snapshot."""
_args: list[Arg] = []
_ctx = self._select("after", _args)
return Directory(_ctx)
[docs]
def as_patch(self) -> "File":
"""Return a Git-compatible patch of the changes"""
_args: list[Arg] = []
_ctx = self._select("asPatch", _args)
return File(_ctx)
[docs]
def before(self) -> "Directory":
"""The older/lower snapshot to compare against."""
_args: list[Arg] = []
_ctx = self._select("before", _args)
return Directory(_ctx)
[docs]
async def diff_stats(self) -> list["DiffStat"]:
"""Structured per-path diff statistics (kind and line counts) for this
changeset.
"""
_args: list[Arg] = []
_ctx = self._select("diffStats", _args)
return await _ctx.execute_object_list(DiffStat)
[docs]
async def export(self, path: str) -> str:
"""Applies the diff represented by this changeset to a path on the host.
Parameters
----------
path:
Location of the copied directory (e.g., "logs/").
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("export", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this Changeset.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def is_empty(self) -> bool:
"""Returns true if the changeset is empty (i.e. there are no changes).
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("isEmpty", _args)
return await _ctx.execute(bool)
[docs]
def layer(self) -> "Directory":
"""Return a snapshot containing only the created and modified files"""
_args: list[Arg] = []
_ctx = self._select("layer", _args)
return Directory(_ctx)
[docs]
async def modified_paths(self) -> list[str]:
"""Files and directories that existed before and were updated in the
newer directory.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("modifiedPaths", _args)
return await _ctx.execute(list[str])
[docs]
async def removed_paths(self) -> list[str]:
"""Files and directories that were removed. Directories are indicated by
a trailing slash, and their child paths are not included.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("removedPaths", _args)
return await _ctx.execute(list[str])
[docs]
async def sync(self) -> Self:
"""Force evaluation in the engine.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def with_changeset(
self,
changes: Self,
*,
on_conflict: ChangesetMergeConflict | None = ChangesetMergeConflict.FAIL,
) -> Self:
"""Add changes to an existing changeset
By default the operation will fail in case of conflicts, for instance
a file modified in both changesets. The behavior can be adjusted using
onConflict argument
Parameters
----------
changes:
Changes to merge into the actual changeset
on_conflict:
What to do on a merge conflict
"""
_args = [
Arg("changes", changes),
Arg("onConflict", on_conflict, ChangesetMergeConflict.FAIL),
]
_ctx = self._select("withChangeset", _args)
return Changeset(_ctx)
[docs]
def with_changesets(
self,
changes: list["Changeset"],
*,
on_conflict: ChangesetsMergeConflict | None = ChangesetsMergeConflict.FAIL,
) -> Self:
"""Add changes from multiple changesets using git octopus merge strategy
This is more efficient than chaining multiple withChangeset calls when
merging many changesets.
Only FAIL and FAIL_EARLY conflict strategies are supported (octopus
merge cannot use -X ours/theirs).
Parameters
----------
changes:
List of changesets to merge into the actual changeset
on_conflict:
What to do on a merge conflict
"""
_args = [
Arg("changes", changes),
Arg("onConflict", on_conflict, ChangesetsMergeConflict.FAIL),
]
_ctx = self._select("withChangesets", _args)
return Changeset(_ctx)
[docs]
def with_(self, cb: Callable[["Changeset"], "Changeset"]) -> "Changeset":
"""Call the provided callable with current Changeset.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Check(Type):
[docs]
async def check_type(self) -> str:
"""The type of check: 'check' for annotated checks, 'generate' for
generate-as-checks
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("checkType", _args)
return await _ctx.execute(str)
[docs]
async def completed(self) -> bool:
"""Whether the check completed
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("completed", _args)
return await _ctx.execute(bool)
[docs]
async def description(self) -> str:
"""The description of the check
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
def error(self) -> "Error":
"""If the check failed, this is the error"""
_args: list[Arg] = []
_ctx = self._select("error", _args)
return Error(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this Check.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""Return the fully qualified name of the check
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def original_module(self) -> "Module":
"""The original module in which the check has been defined"""
_args: list[Arg] = []
_ctx = self._select("originalModule", _args)
return Module(_ctx)
[docs]
async def passed(self) -> bool:
"""Whether the check passed
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("passed", _args)
return await _ctx.execute(bool)
[docs]
async def path(self) -> list[str]:
"""The path of the check within its module
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("path", _args)
return await _ctx.execute(list[str])
[docs]
async def result_emoji(self) -> str:
"""An emoji representing the result of the check
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("resultEmoji", _args)
return await _ctx.execute(str)
[docs]
def run(self) -> Self:
"""Execute the check"""
_args: list[Arg] = []
_ctx = self._select("run", _args)
return Check(_ctx)
[docs]
def with_(self, cb: Callable[["Check"], "Check"]) -> "Check":
"""Call the provided callable with current Check.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class CheckGroup(Type):
[docs]
async def id(self) -> str:
"""A unique identifier for this CheckGroup.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def list_(self) -> list[Check]:
"""Return a list of individual checks and their details"""
_args: list[Arg] = []
_ctx = self._select("list", _args)
return await _ctx.execute_object_list(Check)
[docs]
def report(self) -> "File":
"""Generate a markdown report"""
_args: list[Arg] = []
_ctx = self._select("report", _args)
return File(_ctx)
[docs]
def run(self, *, fail_fast: bool | None = None) -> Self:
"""Execute all selected checks
Parameters
----------
fail_fast:
If true, stop running checks as soon as any check fails.
"""
_args = [
Arg("failFast", fail_fast, None),
]
_ctx = self._select("run", _args)
return CheckGroup(_ctx)
[docs]
def with_(self, cb: Callable[["CheckGroup"], "CheckGroup"]) -> "CheckGroup":
"""Call the provided callable with current CheckGroup.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class ClientFilesyncMirror(Type):
"""An internal persistent filesync mirror."""
[docs]
async def id(self) -> str:
"""A unique identifier for this ClientFilesyncMirror.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class Cloud(Type):
"""Dagger Cloud configuration and state"""
[docs]
async def id(self) -> str:
"""A unique identifier for this Cloud.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def trace_url(self) -> str:
"""The trace URL for the current session
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("traceURL", _args)
return await _ctx.execute(str)
@typecheck
class Container(Type):
"""An OCI-compatible container, also known as a Docker container."""
[docs]
def as_service(
self,
*,
args: list[str] | None = None,
use_entrypoint: bool | None = False,
experimental_privileged_nesting: bool | None = False,
insecure_root_capabilities: bool | None = False,
expand: bool | None = False,
no_init: bool | None = False,
) -> "Service":
"""Turn the container into a Service.
Be sure to set any exposed ports before this conversion.
Parameters
----------
args:
Command to run instead of the container's default command (e.g.,
["go", "run", "main.go"]).
If empty, the container's default command is used.
use_entrypoint:
If the container has an entrypoint, prepend it to the args.
experimental_privileged_nesting:
Provides Dagger access to the executed command.
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.
expand:
Replace "${VAR}" or "$VAR" in the args according to the current
environment variables defined in the container (e.g. "/$VAR/foo").
no_init:
If set, skip the automatic init process injected into containers
by default.
This should only be used if the user requires that their exec
process be the pid 1 process in the container. Otherwise it may
result in unexpected behavior.
"""
_args = [
Arg("args", [] if args is None else args, []),
Arg("useEntrypoint", use_entrypoint, False),
Arg(
"experimentalPrivilegedNesting", experimental_privileged_nesting, False
),
Arg("insecureRootCapabilities", insecure_root_capabilities, False),
Arg("expand", expand, False),
Arg("noInit", no_init, False),
]
_ctx = self._select("asService", _args)
return Service(_ctx)
[docs]
def as_tarball(
self,
*,
platform_variants: "list[Container] | None" = None,
forced_compression: ImageLayerCompression | None = None,
media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes,
) -> "File":
"""Package the container state as an OCI image, and return it as a tar
archive
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.
"""
_args = [
Arg(
"platformVariants",
[] if platform_variants is None else platform_variants,
[],
),
Arg("forcedCompression", forced_compression, None),
Arg("mediaTypes", media_types, ImageMediaTypes.OCIMediaTypes),
]
_ctx = self._select("asTarball", _args)
return File(_ctx)
[docs]
async def combined_output(self) -> str:
"""The combined buffered standard output and standard error stream of the
last executed command
Returns an error if no command was executed
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("combinedOutput", _args)
return await _ctx.execute(str)
[docs]
async def default_args(self) -> list[str]:
"""Return the container's default arguments.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("defaultArgs", _args)
return await _ctx.execute(list[str])
[docs]
def directory(
self,
path: str,
*,
expand: bool | None = False,
) -> "Directory":
"""Retrieve a directory from the container's root filesystem
Mounts are included.
Parameters
----------
path:
The path of the directory to retrieve (e.g., "./src").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
def docker_healthcheck(self) -> "HealthcheckConfig":
"""Retrieves this container's configured docker healthcheck."""
_args: list[Arg] = []
_ctx = self._select("dockerHealthcheck", _args)
return HealthcheckConfig(_ctx)
[docs]
async def entrypoint(self) -> list[str]:
"""Return the container's OCI entrypoint.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("entrypoint", _args)
return await _ctx.execute(list[str])
[docs]
async def env_variable(self, name: str) -> str | None:
"""Retrieves the value of the specified persistent environment variable.
Parameters
----------
name:
The name of the environment variable to retrieve (e.g., "PATH").
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("envVariable", _args)
return await _ctx.execute(str | None)
[docs]
async def env_variables(self) -> list["EnvVariable"]:
"""Retrieves the list of persistent environment variables configured on
the container.
"""
_args: list[Arg] = []
_ctx = self._select("envVariables", _args)
return await _ctx.execute_object_list(EnvVariable)
[docs]
async def exists(
self,
path: str,
*,
expected_type: ExistsType | None = None,
do_not_follow_symlinks: bool | None = False,
) -> bool:
"""check if a file or directory exists
Parameters
----------
path:
Path to check (e.g., "/file.txt").
expected_type:
If specified, also validate the type of file (e.g. "REGULAR_TYPE",
"DIRECTORY_TYPE", or "SYMLINK_TYPE").
do_not_follow_symlinks:
If specified, do not follow symlinks.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
Arg("expectedType", expected_type, None),
Arg("doNotFollowSymlinks", do_not_follow_symlinks, False),
]
_ctx = self._select("exists", _args)
return await _ctx.execute(bool)
[docs]
async def exit_code(self) -> int:
"""The exit code of the last executed command
Returns an error if no command was executed
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("exitCode", _args)
return await _ctx.execute(int)
[docs]
def experimental_with_all_gp_us(self) -> Self:
"""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.
"""
_args: list[Arg] = []
_ctx = self._select("experimentalWithAllGPUs", _args)
return Container(_ctx)
[docs]
def experimental_with_gpu(self, devices: list[str]) -> Self:
"""EXPERIMENTAL API! Subject to change/removal at any time.
Configures the provided list of devices to be accessible to this
container.
This currently works for Nvidia devices only.
Parameters
----------
devices:
List of devices to be accessible to this container.
"""
_args = [
Arg("devices", devices),
]
_ctx = self._select("experimentalWithGPU", _args)
return Container(_ctx)
[docs]
async def export(
self,
path: str,
*,
platform_variants: "list[Container] | None" = None,
forced_compression: ImageLayerCompression | None = None,
media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes,
expand: bool | None = False,
) -> str:
"""Writes the container as an OCI tarball to the destination file path on
the host.
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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
Arg(
"platformVariants",
[] if platform_variants is None else platform_variants,
[],
),
Arg("forcedCompression", forced_compression, None),
Arg("mediaTypes", media_types, ImageMediaTypes.OCIMediaTypes),
Arg("expand", expand, False),
]
_ctx = self._select("export", _args)
return await _ctx.execute(str)
[docs]
async def export_image(
self,
name: str,
*,
platform_variants: "list[Container] | None" = None,
forced_compression: ImageLayerCompression | None = None,
media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes,
) -> Void:
"""Exports the container as an image to the host's container image store.
Parameters
----------
name:
Name of image to export to in the host's store
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
-------
Void
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
Arg(
"platformVariants",
[] if platform_variants is None else platform_variants,
[],
),
Arg("forcedCompression", forced_compression, None),
Arg("mediaTypes", media_types, ImageMediaTypes.OCIMediaTypes),
]
_ctx = self._select("exportImage", _args)
await _ctx.execute()
[docs]
async def exposed_ports(self) -> list["Port"]:
"""Retrieves the list of exposed ports.
This includes ports already exposed by the image, even if not
explicitly added with dagger.
"""
_args: list[Arg] = []
_ctx = self._select("exposedPorts", _args)
return await _ctx.execute_object_list(Port)
[docs]
def file(
self,
path: str,
*,
expand: bool | None = False,
) -> "File":
"""Retrieves a file at the given path.
Mounts are included.
Parameters
----------
path:
The path of the file to retrieve (e.g., "./README.md").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs]
def from_(self, address: str) -> Self:
"""Download a container image, and apply it to the container state. All
previous state will be lost.
Parameters
----------
address:
Address of the container image to download, in standard OCI ref
format. Example:"registry.dagger.io/engine:latest"
"""
_args = [
Arg("address", address),
]
_ctx = self._select("from", _args)
return Container(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this Container.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def image_ref(self) -> str:
"""The unique image reference which can only be retrieved immediately
after the 'Container.From' call.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("imageRef", _args)
return await _ctx.execute(str)
[docs]
def import_(
self,
source: "File",
*,
tag: str | None = "",
) -> Self:
"""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.
"""
_args = [
Arg("source", source),
Arg("tag", tag, ""),
]
_ctx = self._select("import", _args)
return Container(_ctx)
[docs]
async def label(self, name: str) -> str | None:
"""Retrieves the value of the specified label.
Parameters
----------
name:
The name of the label (e.g.,
"org.opencontainers.artifact.created").
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("label", _args)
return await _ctx.execute(str | None)
[docs]
async def labels(self) -> list["Label"]:
"""Retrieves the list of labels passed to container."""
_args: list[Arg] = []
_ctx = self._select("labels", _args)
return await _ctx.execute_object_list(Label)
[docs]
async def mounts(self) -> list[str]:
"""Retrieves the list of paths where a directory is mounted.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("mounts", _args)
return await _ctx.execute(list[str])
[docs]
async def publish(
self,
address: str,
*,
platform_variants: "list[Container] | None" = None,
forced_compression: ImageLayerCompression | None = None,
media_types: ImageMediaTypes | None = ImageMediaTypes.OCIMediaTypes,
) -> str:
"""Package the container state as an OCI image, and publish it to a
registry
Returns the fully qualified address of the published image, with
digest
Parameters
----------
address:
The OCI address to publish to
Same format as "docker push". Example:
"registry.example.com/user/repo:tag"
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 compatible with most recent
registries, but "Docker" may be needed for older registries
without OCI support.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("address", address),
Arg(
"platformVariants",
[] if platform_variants is None else platform_variants,
[],
),
Arg("forcedCompression", forced_compression, None),
Arg("mediaTypes", media_types, ImageMediaTypes.OCIMediaTypes),
]
_ctx = self._select("publish", _args)
return await _ctx.execute(str)
[docs]
def rootfs(self) -> "Directory":
"""Return a snapshot of the container's root filesystem. The snapshot can
be modified then written back using withRootfs. Use that method for
filesystem modifications.
"""
_args: list[Arg] = []
_ctx = self._select("rootfs", _args)
return Directory(_ctx)
[docs]
def stat(
self,
path: str,
*,
do_not_follow_symlinks: bool | None = False,
) -> "Stat":
"""Return file status
Parameters
----------
path:
Path to check (e.g., "/file.txt").
do_not_follow_symlinks:
If specified, do not follow symlinks.
"""
_args = [
Arg("path", path),
Arg("doNotFollowSymlinks", do_not_follow_symlinks, False),
]
_ctx = self._select("stat", _args)
return Stat(_ctx)
[docs]
async def stderr(self) -> str:
"""The buffered standard error stream of the last executed command
Returns an error if no command was executed
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("stderr", _args)
return await _ctx.execute(str)
[docs]
async def stdout(self) -> str:
"""The buffered standard output stream of the last executed command
Returns an error if no command was executed
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("stdout", _args)
return await _ctx.execute(str)
[docs]
async def sync(self) -> Self:
"""Forces evaluation of the pipeline in the engine.
It doesn't run the default command if no exec has been set.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def terminal(
self,
*,
cmd: list[str] | None = None,
experimental_privileged_nesting: bool | None = False,
insecure_root_capabilities: bool | None = False,
) -> Self:
"""Opens an interactive terminal for this container using its configured
default terminal command if not overridden by args (or sh as a
fallback default).
Parameters
----------
cmd:
If set, override the container's default terminal command and
invoke these command arguments instead.
experimental_privileged_nesting:
Provides Dagger access to the executed command.
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.
"""
_args = [
Arg("cmd", [] if cmd is None else cmd, []),
Arg(
"experimentalPrivilegedNesting", experimental_privileged_nesting, False
),
Arg("insecureRootCapabilities", insecure_root_capabilities, False),
]
_ctx = self._select("terminal", _args)
return Container(_ctx)
[docs]
async def up(
self,
*,
random: bool | None = False,
ports: list[PortForward] | None = None,
args: list[str] | None = None,
use_entrypoint: bool | None = False,
experimental_privileged_nesting: bool | None = False,
insecure_root_capabilities: bool | None = False,
expand: bool | None = False,
no_init: bool | None = False,
) -> Void | None:
"""Starts a Service and creates a tunnel that forwards traffic from the
caller's network to that service.
Be sure to set any exposed ports before calling this api.
Parameters
----------
random:
Bind each tunnel port to a random port on the host.
ports:
List of frontend/backend port mappings to forward.
Frontend is the port accepting traffic on the host, backend is the
service port.
args:
Command to run instead of the container's default command (e.g.,
["go", "run", "main.go"]).
If empty, the container's default command is used.
use_entrypoint:
If the container has an entrypoint, prepend it to the args.
experimental_privileged_nesting:
Provides Dagger access to the executed command.
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.
expand:
Replace "${VAR}" or "$VAR" in the args according to the current
environment variables defined in the container (e.g. "/$VAR/foo").
no_init:
If set, skip the automatic init process injected into containers
by default.
This should only be used if the user requires that their exec
process be the pid 1 process in the container. Otherwise it may
result in unexpected behavior.
Returns
-------
Void | None
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("random", random, False),
Arg("ports", [] if ports is None else ports, []),
Arg("args", [] if args is None else args, []),
Arg("useEntrypoint", use_entrypoint, False),
Arg(
"experimentalPrivilegedNesting", experimental_privileged_nesting, False
),
Arg("insecureRootCapabilities", insecure_root_capabilities, False),
Arg("expand", expand, False),
Arg("noInit", no_init, False),
]
_ctx = self._select("up", _args)
await _ctx.execute()
[docs]
async def user(self) -> str:
"""Retrieves the user to be set for all commands.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("user", _args)
return await _ctx.execute(str)
[docs]
def with_annotation(self, name: str, value: str) -> Self:
"""Retrieves this container plus the given OCI annotation.
Parameters
----------
name:
The name of the annotation.
value:
The value of the annotation.
"""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withAnnotation", _args)
return Container(_ctx)
[docs]
def with_default_args(self, args: list[str]) -> Self:
"""Configures default arguments for future commands. Like CMD in
Dockerfile.
Parameters
----------
args:
Arguments to prepend to future executions (e.g., ["-v", "--no-
cache"]).
"""
_args = [
Arg("args", args),
]
_ctx = self._select("withDefaultArgs", _args)
return Container(_ctx)
[docs]
def with_default_terminal_cmd(
self,
args: list[str],
*,
experimental_privileged_nesting: bool | None = False,
insecure_root_capabilities: bool | None = False,
) -> Self:
"""Set the default command to invoke for the container's terminal API.
Parameters
----------
args:
The args of the command.
experimental_privileged_nesting:
Provides Dagger access to the executed command.
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.
"""
_args = [
Arg("args", args),
Arg(
"experimentalPrivilegedNesting", experimental_privileged_nesting, False
),
Arg("insecureRootCapabilities", insecure_root_capabilities, False),
]
_ctx = self._select("withDefaultTerminalCmd", _args)
return Container(_ctx)
[docs]
def with_directory(
self,
path: str,
source: "Directory",
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
owner: str | None = "",
expand: bool | None = False,
permissions: int | None = None,
) -> Self:
"""Return a new container snapshot, with a directory added to its
filesystem
Parameters
----------
path:
Location of the written directory (e.g., "/tmp/directory").
source:
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"]).
gitignore:
Apply .gitignore rules when writing the directory.
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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
permissions:
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
Arg("owner", owner, ""),
Arg("expand", expand, False),
Arg("permissions", permissions, None),
]
_ctx = self._select("withDirectory", _args)
return Container(_ctx)
[docs]
def with_docker_healthcheck(
self,
args: list[str],
*,
shell: bool | None = None,
interval: str | None = None,
timeout: str | None = None,
start_period: str | None = None,
start_interval: str | None = None,
retries: int | None = None,
) -> Self:
"""Retrieves this container with the specificed docker healtcheck command
set.
Parameters
----------
args:
Healthcheck command to execute. Example: ["go", "run", "main.go"].
shell:
When true, command must be a single element, which is run using
the container's shell
interval:
Interval between running healthcheck. Example: "30s"
timeout:
Healthcheck timeout. Example: "3s"
start_period:
StartPeriod allows for failures during this initial startup period
which do not count towards maximum number of retries. Example:
"0s"
start_interval:
StartInterval configures the duration between checks during the
startup phase. Example: "5s"
retries:
The maximum number of consecutive failures before the container is
marked as unhealthy. Example: "3"
"""
_args = [
Arg("args", args),
Arg("shell", shell, None),
Arg("interval", interval, None),
Arg("timeout", timeout, None),
Arg("startPeriod", start_period, None),
Arg("startInterval", start_interval, None),
Arg("retries", retries, None),
]
_ctx = self._select("withDockerHealthcheck", _args)
return Container(_ctx)
[docs]
def with_entrypoint(
self,
args: list[str],
*,
keep_default_args: bool | None = False,
) -> Self:
"""Set an OCI-style entrypoint. It will be included in the container's
OCI configuration. Note, withExec ignores the entrypoint by default.
Parameters
----------
args:
Arguments of the entrypoint. Example: ["go", "run"].
keep_default_args:
Don't reset the default arguments when setting the entrypoint. By
default it is reset, since entrypoint and default args are often
tightly coupled.
"""
_args = [
Arg("args", args),
Arg("keepDefaultArgs", keep_default_args, False),
]
_ctx = self._select("withEntrypoint", _args)
return Container(_ctx)
[docs]
def with_env_file_variables(self, source: "EnvFile") -> Self:
"""Export environment variables from an env-file to the container.
Parameters
----------
source:
Identifier of the envfile
"""
_args = [
Arg("source", source),
]
_ctx = self._select("withEnvFileVariables", _args)
return Container(_ctx)
[docs]
def with_env_variable(
self,
name: str,
value: str,
*,
expand: bool | None = False,
) -> Self:
"""Set a new environment variable in the container.
Parameters
----------
name:
Name of the environment variable (e.g., "HOST").
value:
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").
"""
_args = [
Arg("name", name),
Arg("value", value),
Arg("expand", expand, False),
]
_ctx = self._select("withEnvVariable", _args)
return Container(_ctx)
[docs]
def with_error(self, err: str) -> Self:
"""Raise an error.
Parameters
----------
err:
Message of the error to raise. If empty, the error will be
ignored.
"""
_args = [
Arg("err", err),
]
_ctx = self._select("withError", _args)
return Container(_ctx)
[docs]
def with_exec(
self,
args: list[str],
*,
use_entrypoint: bool | None = False,
stdin: str | None = "",
redirect_stdin: str | None = "",
redirect_stdout: str | None = "",
redirect_stderr: str | None = "",
expect: ReturnType | None = ReturnType.SUCCESS,
experimental_privileged_nesting: bool | None = False,
insecure_root_capabilities: bool | None = False,
expand: bool | None = False,
no_init: bool | None = False,
) -> Self:
"""Execute a command in the container, and return a new snapshot of the
container state after execution.
Parameters
----------
args:
Command to execute. Must be valid exec() arguments, not a shell
command. Example: ["go", "run", "main.go"].
To run a shell command, execute the shell and pass the shell
command as argument. Example: ["sh", "-c", "ls -l | grep foo"]
Defaults to the container's default arguments (see "defaultArgs"
and "withDefaultArgs").
use_entrypoint:
Apply the OCI entrypoint, if present, by prepending it to the
args. Ignored by default.
stdin:
Content to write to the command's standard input. Example: "Hello
world")
redirect_stdin:
Redirect the command's standard input from a file in the
container. Example: "./stdin.txt"
redirect_stdout:
Redirect the command's standard output to a file in the container.
Example: "./stdout.txt"
redirect_stderr:
Redirect the command's standard error to a file in the container.
Example: "./stderr.txt"
expect:
Exit codes this command is allowed to exit with without error
experimental_privileged_nesting:
Provides Dagger access to the executed command.
insecure_root_capabilities:
Execute the command with all root capabilities. Like --privileged
in Docker
DANGER: this grants the command full access to the host system.
Only use when 1) you trust the command being executed and 2) you
specifically need this level of access.
expand:
Replace "${VAR}" or "$VAR" in the args according to the current
environment variables defined in the container (e.g. "/$VAR/foo").
no_init:
Skip the automatic init process injected into containers by
default.
Only use this if you specifically need the command to be pid 1 in
the container. Otherwise it may result in unexpected behavior. If
you're not sure, you don't need this.
"""
_args = [
Arg("args", args),
Arg("useEntrypoint", use_entrypoint, False),
Arg("stdin", stdin, ""),
Arg("redirectStdin", redirect_stdin, ""),
Arg("redirectStdout", redirect_stdout, ""),
Arg("redirectStderr", redirect_stderr, ""),
Arg("expect", expect, ReturnType.SUCCESS),
Arg(
"experimentalPrivilegedNesting", experimental_privileged_nesting, False
),
Arg("insecureRootCapabilities", insecure_root_capabilities, False),
Arg("expand", expand, False),
Arg("noInit", no_init, False),
]
_ctx = self._select("withExec", _args)
return Container(_ctx)
[docs]
def with_exposed_port(
self,
port: int,
*,
protocol: NetworkProtocol | None = NetworkProtocol.TCP,
description: str | None = None,
experimental_skip_healthcheck: bool | None = False,
) -> Self:
"""Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck
support)
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. Example: 8080
protocol:
Network protocol. Example: "tcp"
description:
Port description. Example: "payment API endpoint"
experimental_skip_healthcheck:
Skip the health check when run as a service.
"""
_args = [
Arg("port", port),
Arg("protocol", protocol, NetworkProtocol.TCP),
Arg("description", description, None),
Arg("experimentalSkipHealthcheck", experimental_skip_healthcheck, False),
]
_ctx = self._select("withExposedPort", _args)
return Container(_ctx)
[docs]
def with_file(
self,
path: str,
source: "File",
*,
permissions: int | None = None,
owner: str | None = "",
expand: bool | None = False,
) -> Self:
"""Return a container snapshot with a file added
Parameters
----------
path:
Path of the new file. Example: "/path/to/new-file.txt"
source:
File to add
permissions:
Permissions of the new file. Example: 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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("permissions", permissions, None),
Arg("owner", owner, ""),
Arg("expand", expand, False),
]
_ctx = self._select("withFile", _args)
return Container(_ctx)
[docs]
def with_files(
self,
path: str,
sources: list["File"],
*,
permissions: int | None = None,
owner: str | None = "",
expand: bool | None = False,
) -> Self:
"""Retrieves this container plus the contents of the given files copied
to the given path.
Parameters
----------
path:
Location where copied files should be placed (e.g., "/src").
sources:
Identifiers of the files to copy.
permissions:
Permission given to the copied files (e.g., 0600).
owner:
A user:group to set for the files.
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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("path", path),
Arg("sources", sources),
Arg("permissions", permissions, None),
Arg("owner", owner, ""),
Arg("expand", expand, False),
]
_ctx = self._select("withFiles", _args)
return Container(_ctx)
[docs]
def with_label(self, name: str, value: str) -> Self:
"""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").
"""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withLabel", _args)
return Container(_ctx)
[docs]
def with_mounted_cache(
self,
path: str,
cache: CacheVolume,
*,
source: "Directory | None" = None,
sharing: CacheSharingMode | None = CacheSharingMode.SHARED,
owner: str | None = "",
expand: bool | None = False,
) -> Self:
"""Retrieves this container plus a cache volume mounted at the given
path.
Parameters
----------
path:
Location of the cache directory (e.g., "/root/.npm").
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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("cache", cache),
Arg("source", source, None),
Arg("sharing", sharing, CacheSharingMode.SHARED),
Arg("owner", owner, ""),
Arg("expand", expand, False),
]
_ctx = self._select("withMountedCache", _args)
return Container(_ctx)
[docs]
def with_mounted_directory(
self,
path: str,
source: "Directory",
*,
owner: str | None = "",
read_only: bool | None = False,
expand: bool | None = False,
) -> Self:
"""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.
read_only:
Mount the directory read-only.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("owner", owner, ""),
Arg("readOnly", read_only, False),
Arg("expand", expand, False),
]
_ctx = self._select("withMountedDirectory", _args)
return Container(_ctx)
[docs]
def with_mounted_file(
self,
path: str,
source: "File",
*,
owner: str | None = "",
expand: bool | None = False,
) -> Self:
"""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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("owner", owner, ""),
Arg("expand", expand, False),
]
_ctx = self._select("withMountedFile", _args)
return Container(_ctx)
[docs]
def with_mounted_secret(
self,
path: str,
source: "Secret",
*,
owner: str | None = "",
mode: int | None = 256,
expand: bool | None = False,
) -> Self:
"""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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("owner", owner, ""),
Arg("mode", mode, 256),
Arg("expand", expand, False),
]
_ctx = self._select("withMountedSecret", _args)
return Container(_ctx)
[docs]
def with_mounted_temp(
self,
path: str,
*,
size: int | None = None,
expand: bool | None = False,
) -> Self:
"""Retrieves this container plus a temporary directory mounted at the
given path. Any writes will be ephemeral to a single withExec call;
they will not be persisted to subsequent withExecs.
Parameters
----------
path:
Location of the temporary directory (e.g., "/tmp/temp_dir").
size:
Size of the temporary directory in bytes.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("size", size, None),
Arg("expand", expand, False),
]
_ctx = self._select("withMountedTemp", _args)
return Container(_ctx)
[docs]
def with_new_file(
self,
path: str,
contents: str,
*,
permissions: int | None = 420,
owner: str | None = "",
expand: bool | None = False,
) -> Self:
"""Return a new container snapshot, with a file added to its filesystem
with text content
Parameters
----------
path:
Path of the new file. May be relative or absolute. Example:
"README.md" or "/etc/profile"
contents:
Contents of the new file. Example: "Hello world!"
permissions:
Permissions of the new file. Example: 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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("path", path),
Arg("contents", contents),
Arg("permissions", permissions, 420),
Arg("owner", owner, ""),
Arg("expand", expand, False),
]
_ctx = self._select("withNewFile", _args)
return Container(_ctx)
[docs]
def with_registry_auth(
self,
address: str,
username: str,
secret: "Secret",
) -> Self:
"""Attach credentials for future publishing to a registry. Use in
combination with publish
Parameters
----------
address:
The image address that needs authentication. Same format as
"docker push". Example: "registry.dagger.io/dagger:latest"
username:
The username to authenticate with. Example: "alice"
secret:
The API key, password or token to authenticate to this registry
"""
_args = [
Arg("address", address),
Arg("username", username),
Arg("secret", secret),
]
_ctx = self._select("withRegistryAuth", _args)
return Container(_ctx)
[docs]
def with_rootfs(self, directory: "Directory") -> Self:
"""Change the container's root filesystem. The previous root filesystem
will be lost.
Parameters
----------
directory:
The new root filesystem.
"""
_args = [
Arg("directory", directory),
]
_ctx = self._select("withRootfs", _args)
return Container(_ctx)
[docs]
def with_secret_variable(self, name: str, secret: "Secret") -> Self:
"""Set a new environment variable, using a secret value
Parameters
----------
name:
Name of the secret variable (e.g., "API_SECRET").
secret:
Identifier of the secret value.
"""
_args = [
Arg("name", name),
Arg("secret", secret),
]
_ctx = self._select("withSecretVariable", _args)
return Container(_ctx)
[docs]
def with_service_binding(self, alias: str, service: "Service") -> Self:
"""Establish a runtime dependency from a container to a network 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:
Hostname that will resolve to the target service (only accessible
from within this container)
service:
The target service
"""
_args = [
Arg("alias", alias),
Arg("service", service),
]
_ctx = self._select("withServiceBinding", _args)
return Container(_ctx)
[docs]
def with_symlink(
self,
target: str,
link_name: str,
*,
expand: bool | None = False,
) -> Self:
"""Return a snapshot with a symlink
Parameters
----------
target:
Location of the file or directory to link to (e.g.,
"/existing/file").
link_name:
Location where the symbolic link will be created (e.g., "/new-
file-link").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("target", target),
Arg("linkName", link_name),
Arg("expand", expand, False),
]
_ctx = self._select("withSymlink", _args)
return Container(_ctx)
[docs]
def with_unix_socket(
self,
path: str,
source: "Socket",
*,
owner: str | None = "",
expand: bool | None = False,
) -> Self:
"""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.
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("owner", owner, ""),
Arg("expand", expand, False),
]
_ctx = self._select("withUnixSocket", _args)
return Container(_ctx)
[docs]
def with_user(self, name: str) -> Self:
"""Retrieves this container with a different command user.
Parameters
----------
name:
The user to set (e.g., "root").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withUser", _args)
return Container(_ctx)
[docs]
def with_volatile_variable(self, name: str, value: str) -> Self:
"""Set a new non-secret environment variable for future execs without
invalidating exec cache when only its value changes.
This is an expert-only escape hatch. If a volatile value affects
observable exec results, stale cached results may be reused.
Parameters
----------
name:
Name of the volatile variable (e.g., "CI_RUN_ID").
value:
Value of the volatile variable.
"""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withVolatileVariable", _args)
return Container(_ctx)
[docs]
def with_workdir(
self,
path: str,
*,
expand: bool | None = False,
) -> Self:
"""Change the container's working directory. Like WORKDIR in Dockerfile.
Parameters
----------
path:
The path to set as the working directory (e.g., "/app").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("withWorkdir", _args)
return Container(_ctx)
[docs]
def without_annotation(self, name: str) -> Self:
"""Retrieves this container minus the given OCI annotation.
Parameters
----------
name:
The name of the annotation.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutAnnotation", _args)
return Container(_ctx)
[docs]
def without_default_args(self) -> Self:
"""Remove the container's default arguments."""
_args: list[Arg] = []
_ctx = self._select("withoutDefaultArgs", _args)
return Container(_ctx)
[docs]
def without_directory(
self,
path: str,
*,
expand: bool | None = False,
) -> Self:
"""Return a new container snapshot, with a directory removed from its
filesystem
Parameters
----------
path:
Location of the directory to remove (e.g., ".github/").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("withoutDirectory", _args)
return Container(_ctx)
[docs]
def without_docker_healthcheck(self) -> Self:
"""Retrieves this container without a configured docker healtcheck
command.
"""
_args: list[Arg] = []
_ctx = self._select("withoutDockerHealthcheck", _args)
return Container(_ctx)
[docs]
def without_entrypoint(
self,
*,
keep_default_args: bool | None = False,
) -> Self:
"""Reset the container's OCI entrypoint.
Parameters
----------
keep_default_args:
Don't remove the default arguments when unsetting the entrypoint.
"""
_args = [
Arg("keepDefaultArgs", keep_default_args, False),
]
_ctx = self._select("withoutEntrypoint", _args)
return Container(_ctx)
[docs]
def without_env_variable(self, name: str) -> Self:
"""Retrieves this container minus the given environment variable.
Parameters
----------
name:
The name of the environment variable (e.g., "HOST").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutEnvVariable", _args)
return Container(_ctx)
[docs]
def without_exposed_port(
self,
port: int,
*,
protocol: NetworkProtocol | None = NetworkProtocol.TCP,
) -> Self:
"""Unexpose a previously exposed port.
Parameters
----------
port:
Port number to unexpose
protocol:
Port protocol to unexpose
"""
_args = [
Arg("port", port),
Arg("protocol", protocol, NetworkProtocol.TCP),
]
_ctx = self._select("withoutExposedPort", _args)
return Container(_ctx)
[docs]
def without_file(
self,
path: str,
*,
expand: bool | None = False,
) -> Self:
"""Retrieves this container with the file at the given path removed.
Parameters
----------
path:
Location of the file to remove (e.g., "/file.txt").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("withoutFile", _args)
return Container(_ctx)
[docs]
def without_files(
self,
paths: list[str],
*,
expand: bool | None = False,
) -> Self:
"""Return a new container spanshot with specified files removed
Parameters
----------
paths:
Paths of the files to remove. Example: ["foo.txt,
"/root/.ssh/config"
expand:
Replace "${VAR}" or "$VAR" in the value of paths according to the
current environment variables defined in the container (e.g.
"/$VAR/foo.txt").
"""
_args = [
Arg("paths", paths),
Arg("expand", expand, False),
]
_ctx = self._select("withoutFiles", _args)
return Container(_ctx)
[docs]
def without_label(self, name: str) -> Self:
"""Retrieves this container minus the given environment label.
Parameters
----------
name:
The name of the label to remove (e.g.,
"org.opencontainers.artifact.created").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutLabel", _args)
return Container(_ctx)
[docs]
def without_mount(
self,
path: str,
*,
expand: bool | None = False,
) -> Self:
"""Retrieves this container after unmounting everything at the given
path.
Parameters
----------
path:
Location of the cache directory (e.g., "/root/.npm").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("withoutMount", _args)
return Container(_ctx)
[docs]
def without_registry_auth(self, address: str) -> Self:
"""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).
"""
_args = [
Arg("address", address),
]
_ctx = self._select("withoutRegistryAuth", _args)
return Container(_ctx)
[docs]
def without_secret_variable(self, name: str) -> Self:
"""Retrieves this container minus the given environment variable
containing the secret.
Parameters
----------
name:
The name of the environment variable (e.g., "HOST").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutSecretVariable", _args)
return Container(_ctx)
[docs]
def without_unix_socket(
self,
path: str,
*,
expand: bool | None = False,
) -> Self:
"""Retrieves this container with a previously added Unix socket removed.
Parameters
----------
path:
Location of the socket to remove (e.g., "/tmp/socket").
expand:
Replace "${VAR}" or "$VAR" in the value of path according to the
current environment variables defined in the container (e.g.
"/$VAR/foo").
"""
_args = [
Arg("path", path),
Arg("expand", expand, False),
]
_ctx = self._select("withoutUnixSocket", _args)
return Container(_ctx)
[docs]
def without_user(self) -> Self:
"""Retrieves this container with an unset command user.
Should default to root.
"""
_args: list[Arg] = []
_ctx = self._select("withoutUser", _args)
return Container(_ctx)
[docs]
def without_volatile_variable(self, name: str) -> Self:
"""Retrieves this container minus the given volatile environment
variable.
Parameters
----------
name:
The name of the volatile environment variable (e.g., "CI_RUN_ID").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutVolatileVariable", _args)
return Container(_ctx)
[docs]
def without_workdir(self) -> Self:
"""Unset the container's working directory.
Should default to "/".
"""
_args: list[Arg] = []
_ctx = self._select("withoutWorkdir", _args)
return Container(_ctx)
[docs]
async def workdir(self) -> str:
"""Retrieves the working directory for all commands.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("workdir", _args)
return await _ctx.execute(str)
[docs]
def with_(self, cb: Callable[["Container"], "Container"]) -> "Container":
"""Call the provided callable with current Container.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class CurrentModule(Type):
"""Reflective module API provided to functions at runtime."""
[docs]
async def dependencies(self) -> list["Module"]:
"""The dependencies of the module."""
_args: list[Arg] = []
_ctx = self._select("dependencies", _args)
return await _ctx.execute_object_list(Module)
[docs]
def generated_context_directory(self) -> "Directory":
"""The generated files and directories made on top of the module source's
context directory.
"""
_args: list[Arg] = []
_ctx = self._select("generatedContextDirectory", _args)
return Directory(_ctx)
[docs]
def generators(
self,
*,
include: list[str] | None = None,
) -> "GeneratorGroup":
"""Return all generators defined by the module
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
include:
Only include generators matching the specified patterns
"""
_args = [
Arg("include", include, None),
]
_ctx = self._select("generators", _args)
return GeneratorGroup(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this CurrentModule.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the module being executed in
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source(self) -> "Directory":
"""The directory containing the module's source code loaded into the
engine (plus any generated code that may have been created).
"""
_args: list[Arg] = []
_ctx = self._select("source", _args)
return Directory(_ctx)
[docs]
def workdir(
self,
path: str,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
) -> "Directory":
"""Load a directory from the module's scratch working directory,
including any changes that may have been made to it during module
function execution.
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.*"]).
gitignore:
Apply .gitignore filter rules inside the directory
"""
_args = [
Arg("path", path),
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
]
_ctx = self._select("workdir", _args)
return Directory(_ctx)
[docs]
def workdir_file(self, path: str) -> "File":
"""Load a file from the module's scratch working directory, including any
changes that may have been made to it during module function
execution.Load a file from the module's scratch working directory,
including any changes that may have been made to it during module
function execution.
Parameters
----------
path:
Location of the file to retrieve (e.g., "README.md").
"""
_args = [
Arg("path", path),
]
_ctx = self._select("workdirFile", _args)
return File(_ctx)
@typecheck
class DiffStat(Type):
[docs]
async def added_lines(self) -> int:
"""Number of added lines for this path.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("addedLines", _args)
return await _ctx.execute(int)
[docs]
async def id(self) -> str:
"""A unique identifier for this DiffStat.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def kind(self) -> DiffStatKind:
"""Type of change.
Returns
-------
DiffStatKind
The type of change for a diff stat entry.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("kind", _args)
return await _ctx.execute(DiffStatKind)
[docs]
async def old_path(self) -> str | None:
"""Previous path of the file, set only for renames.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("oldPath", _args)
return await _ctx.execute(str | None)
[docs]
async def path(self) -> str:
"""Path of the changed file or directory.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("path", _args)
return await _ctx.execute(str)
[docs]
async def removed_lines(self) -> int:
"""Number of removed lines for this path.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("removedLines", _args)
return await _ctx.execute(int)
@typecheck
class Directory(Type):
"""A directory."""
[docs]
def as_git(self) -> "GitRepository":
"""Converts this directory to a local git repository"""
_args: list[Arg] = []
_ctx = self._select("asGit", _args)
return GitRepository(_ctx)
[docs]
def as_module(
self,
*,
source_root_path: str | None = ".",
) -> "Module":
"""Load the directory as a Dagger module source
Parameters
----------
source_root_path:
An optional subpath of the directory which contains the module's
configuration file.
If not set, the module source code is loaded from the root of the
directory.
"""
_args = [
Arg("sourceRootPath", source_root_path, "."),
]
_ctx = self._select("asModule", _args)
return Module(_ctx)
[docs]
def as_module_source(
self,
*,
source_root_path: str | None = ".",
) -> "ModuleSource":
"""Load the directory as a Dagger module source
Parameters
----------
source_root_path:
An optional subpath of the directory which contains the module's
configuration file.
If not set, the module source code is loaded from the root of the
directory.
"""
_args = [
Arg("sourceRootPath", source_root_path, "."),
]
_ctx = self._select("asModuleSource", _args)
return ModuleSource(_ctx)
[docs]
def changes(self, from_: Self) -> Changeset:
"""Return the difference between this directory and another directory,
typically an older snapshot.
The difference is encoded as a changeset, which also tracks removed
files, and can be applied to other directories.
Parameters
----------
from_:
The base directory snapshot to compare against
"""
_args = [
Arg("from", from_),
]
_ctx = self._select("changes", _args)
return Changeset(_ctx)
[docs]
def chown(self, path: str, owner: str) -> Self:
"""Change the owner of the directory contents recursively.
Parameters
----------
path:
Path of the directory to change ownership of (e.g., "/").
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.
"""
_args = [
Arg("path", path),
Arg("owner", owner),
]
_ctx = self._select("chown", _args)
return Directory(_ctx)
[docs]
def diff(self, other: Self) -> Self:
"""Return the difference between this directory and an another directory.
The difference is encoded as a directory.
Parameters
----------
other:
The directory to compare against
"""
_args = [
Arg("other", other),
]
_ctx = self._select("diff", _args)
return Directory(_ctx)
[docs]
async def digest(self) -> str:
"""Return the directory's digest. The format of the digest is not
guaranteed to be stable between releases of Dagger. It is guaranteed
to be stable between invocations of the same Dagger engine.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("digest", _args)
return await _ctx.execute(str)
[docs]
def directory(self, path: str) -> Self:
"""Retrieves a directory at the given path.
Parameters
----------
path:
Location of the directory to retrieve. Example: "/src"
"""
_args = [
Arg("path", path),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
def docker_build(
self,
*,
dockerfile: str | None = "Dockerfile",
platform: Platform | None = None,
build_args: list[BuildArg] | None = None,
target: str | None = "",
secrets: "list[Secret] | None" = None,
no_init: bool | None = False,
ssh: "Socket | None" = None,
) -> Container:
"""Use Dockerfile compatibility to build a container from this directory.
Only use this function for Dockerfile compatibility. Otherwise use the
native Container type directly, it is feature-complete and supports
all Dockerfile features.
Parameters
----------
dockerfile:
Path to the Dockerfile to use (e.g., "frontend.Dockerfile").
platform:
The platform to build.
build_args:
Build arguments to use in the build.
target:
Target build stage to build.
secrets:
Secrets to pass to the build.
They will be mounted at /run/secrets/[secret-name].
no_init:
If set, skip the automatic init process injected into containers
created by RUN statements.
This should only be used if the user requires that their exec
processes be the pid 1 process in the container. Otherwise it may
result in unexpected behavior.
ssh:
A socket to use for SSH authentication during the build
(e.g., for Dockerfile RUN --mount=type=ssh instructions).
Typically obtained via host.unixSocket() pointing to the
SSH_AUTH_SOCK.
"""
_args = [
Arg("dockerfile", dockerfile, "Dockerfile"),
Arg("platform", platform, None),
Arg("buildArgs", [] if build_args is None else build_args, []),
Arg("target", target, ""),
Arg("secrets", [] if secrets is None else secrets, []),
Arg("noInit", no_init, False),
Arg("ssh", ssh, None),
]
_ctx = self._select("dockerBuild", _args)
return Container(_ctx)
[docs]
async def entries(self, *, path: str | None = None) -> list[str]:
"""Returns a list of files and directories at the given path.
Parameters
----------
path:
Location of the directory to look at (e.g., "/src").
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path, None),
]
_ctx = self._select("entries", _args)
return await _ctx.execute(list[str])
[docs]
async def exists(
self,
path: str,
*,
expected_type: ExistsType | None = None,
do_not_follow_symlinks: bool | None = False,
) -> bool:
"""check if a file or directory exists
Parameters
----------
path:
Path to check (e.g., "/file.txt").
expected_type:
If specified, also validate the type of file (e.g. "REGULAR_TYPE",
"DIRECTORY_TYPE", or "SYMLINK_TYPE").
do_not_follow_symlinks:
If specified, do not follow symlinks.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
Arg("expectedType", expected_type, None),
Arg("doNotFollowSymlinks", do_not_follow_symlinks, False),
]
_ctx = self._select("exists", _args)
return await _ctx.execute(bool)
[docs]
async def export(
self,
path: str,
*,
wipe: bool | None = False,
) -> str:
"""Writes the contents of the directory to a path on the host.
Parameters
----------
path:
Location of the copied directory (e.g., "logs/").
wipe:
If true, then the host directory will be wiped clean before
exporting so that it exactly matches the directory being exported;
this means it will delete any files on the host that aren't in the
exported dir. If false (the default), the contents of the
directory will be merged with any existing contents of the host
directory, leaving any existing files on the host that aren't in
the exported directory alone.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
Arg("wipe", wipe, False),
]
_ctx = self._select("export", _args)
return await _ctx.execute(str)
[docs]
def file(self, path: str) -> "File":
"""Retrieve a file at the given path.
Parameters
----------
path:
Location of the file to retrieve (e.g., "README.md").
"""
_args = [
Arg("path", path),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs]
def filter(
self,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
) -> Self:
"""Return a snapshot with some paths included or excluded
Parameters
----------
exclude:
If set, paths matching one of these glob patterns is excluded from
the new snapshot. Example: ["node_modules/", ".git*", ".env"]
include:
If set, only paths matching one of these glob patterns is included
in the new snapshot. Example: (e.g., ["app/", "package.*"]).
gitignore:
If set, apply .gitignore rules when filtering the directory.
"""
_args = [
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
]
_ctx = self._select("filter", _args)
return Directory(_ctx)
[docs]
async def find_up(self, name: str, start: str) -> str | None:
"""Search up the directory tree for a file or directory, and return its
path. If no match, return null
Parameters
----------
name:
The name of the file or directory to search for
start:
The path to start the search from
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
Arg("start", start),
]
_ctx = self._select("findUp", _args)
return await _ctx.execute(str | None)
[docs]
async def glob(self, pattern: str) -> list[str]:
"""Returns a list of files and directories that matche the given pattern.
Parameters
----------
pattern:
Pattern to match (e.g., "*.md").
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("pattern", pattern),
]
_ctx = self._select("glob", _args)
return await _ctx.execute(list[str])
[docs]
async def id(self) -> str:
"""A unique identifier for this Directory.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""Returns the name of the directory.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def search(
self,
pattern: str,
*,
paths: list[str] | None = None,
globs: list[str] | None = None,
literal: bool | None = False,
multiline: bool | None = False,
dotall: bool | None = False,
insensitive: bool | None = False,
skip_ignored: bool | None = False,
skip_hidden: bool | None = False,
files_only: bool | None = False,
limit: int | None = None,
) -> list["SearchResult"]:
"""Searches for content matching the given regular expression or literal
string.
Uses Rust regex syntax; escape literal ., [, ], {, }, | with
backslashes.
Parameters
----------
pattern:
The text to match.
paths:
Directory or file paths to search
globs:
Glob patterns to match (e.g., "*.md")
literal:
Interpret the pattern as a literal string instead of a regular
expression.
multiline:
Enable searching across multiple lines.
dotall:
Allow the . pattern to match newlines in multiline mode.
insensitive:
Enable case-insensitive matching.
skip_ignored:
Honor .gitignore, .ignore, and .rgignore files.
skip_hidden:
Skip hidden files (files starting with .).
files_only:
Only return matching files, not lines and content
limit:
Limit the number of results to return
"""
_args = [
Arg("pattern", pattern),
Arg("paths", [] if paths is None else paths, []),
Arg("globs", [] if globs is None else globs, []),
Arg("literal", literal, False),
Arg("multiline", multiline, False),
Arg("dotall", dotall, False),
Arg("insensitive", insensitive, False),
Arg("skipIgnored", skip_ignored, False),
Arg("skipHidden", skip_hidden, False),
Arg("filesOnly", files_only, False),
Arg("limit", limit, None),
]
_ctx = self._select("search", _args)
return await _ctx.execute_object_list(SearchResult)
[docs]
def stat(
self,
path: str,
*,
do_not_follow_symlinks: bool | None = False,
) -> "Stat":
"""Return file status
Parameters
----------
path:
Path to stat (e.g., "/file.txt").
do_not_follow_symlinks:
If specified, do not follow symlinks.
"""
_args = [
Arg("path", path),
Arg("doNotFollowSymlinks", do_not_follow_symlinks, False),
]
_ctx = self._select("stat", _args)
return Stat(_ctx)
[docs]
async def sync(self) -> Self:
"""Force evaluation in the engine.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def terminal(
self,
*,
container: Container | None = None,
cmd: list[str] | None = None,
experimental_privileged_nesting: bool | None = False,
insecure_root_capabilities: bool | None = False,
) -> Self:
"""Opens an interactive terminal in new container with this directory
mounted inside.
Parameters
----------
container:
If set, override the default container used for the terminal.
cmd:
If set, override the container's default terminal command and
invoke these command arguments instead.
experimental_privileged_nesting:
Provides Dagger access to the executed command.
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.
"""
_args = [
Arg("container", container, None),
Arg("cmd", [] if cmd is None else cmd, []),
Arg(
"experimentalPrivilegedNesting", experimental_privileged_nesting, False
),
Arg("insecureRootCapabilities", insecure_root_capabilities, False),
]
_ctx = self._select("terminal", _args)
return Directory(_ctx)
[docs]
def with_changes(self, changes: Changeset) -> Self:
"""Return a directory with changes from another directory applied to it.
Parameters
----------
changes:
Changes to apply to the directory
"""
_args = [
Arg("changes", changes),
]
_ctx = self._select("withChanges", _args)
return Directory(_ctx)
[docs]
def with_directory(
self,
path: str,
source: Self,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
owner: str | None = "",
permissions: int | None = None,
) -> Self:
"""Return a snapshot with a directory added
Parameters
----------
path:
Location of the written directory (e.g., "/src/").
source:
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.*"]).
gitignore:
Apply .gitignore filter rules inside the directory
owner:
A user:group to set for the copied 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.
permissions:
Permission given to the copied directory and contents (e.g.,
0755).
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
Arg("owner", owner, ""),
Arg("permissions", permissions, None),
]
_ctx = self._select("withDirectory", _args)
return Directory(_ctx)
[docs]
def with_error(self, err: str) -> Self:
"""Raise an error.
Parameters
----------
err:
Message of the error to raise. If empty, the error will be
ignored.
"""
_args = [
Arg("err", err),
]
_ctx = self._select("withError", _args)
return Directory(_ctx)
[docs]
def with_file(
self,
path: str,
source: "File",
*,
permissions: int | None = None,
owner: str | None = "",
) -> Self:
"""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).
owner:
A user:group to set for the copied 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.
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("permissions", permissions, None),
Arg("owner", owner, ""),
]
_ctx = self._select("withFile", _args)
return Directory(_ctx)
[docs]
def with_files(
self,
path: str,
sources: list["File"],
*,
permissions: int | None = None,
) -> Self:
"""Retrieves this directory plus the contents of the given files copied
to the given path.
Parameters
----------
path:
Location where copied files should be placed (e.g., "/src").
sources:
Identifiers of the files to copy.
permissions:
Permission given to the copied files (e.g., 0600).
"""
_args = [
Arg("path", path),
Arg("sources", sources),
Arg("permissions", permissions, None),
]
_ctx = self._select("withFiles", _args)
return Directory(_ctx)
[docs]
def with_new_directory(
self,
path: str,
*,
permissions: int | None = 420,
) -> Self:
"""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).
"""
_args = [
Arg("path", path),
Arg("permissions", permissions, 420),
]
_ctx = self._select("withNewDirectory", _args)
return Directory(_ctx)
[docs]
def with_new_file(
self,
path: str,
contents: str,
*,
permissions: int | None = 420,
) -> Self:
"""Return a snapshot with a new file added
Parameters
----------
path:
Path of the new file. Example: "foo/bar.txt"
contents:
Contents of the new file. Example: "Hello world!"
permissions:
Permissions of the new file. Example: 0600
"""
_args = [
Arg("path", path),
Arg("contents", contents),
Arg("permissions", permissions, 420),
]
_ctx = self._select("withNewFile", _args)
return Directory(_ctx)
[docs]
def with_patch(self, patch: str) -> Self:
"""Retrieves this directory with the given Git-compatible patch applied.
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
patch:
Patch to apply (e.g., "diff --git a/file.txt b/file.txt\nindex
1234567..abcdef8 100644\n--- a/file.txt\n+++ b/file.txt\n@@ -1,1
+1,1 @@\n-Hello\n+World\n").
"""
_args = [
Arg("patch", patch),
]
_ctx = self._select("withPatch", _args)
return Directory(_ctx)
[docs]
def with_patch_file(self, patch: "File") -> Self:
"""Retrieves this directory with the given Git-compatible patch file
applied.
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
patch:
File containing the patch to apply
"""
_args = [
Arg("patch", patch),
]
_ctx = self._select("withPatchFile", _args)
return Directory(_ctx)
[docs]
def with_symlink(self, target: str, link_name: str) -> Self:
"""Return a snapshot with a symlink
Parameters
----------
target:
Location of the file or directory to link to (e.g.,
"/existing/file").
link_name:
Location where the symbolic link will be created (e.g., "/new-
file-link").
"""
_args = [
Arg("target", target),
Arg("linkName", link_name),
]
_ctx = self._select("withSymlink", _args)
return Directory(_ctx)
[docs]
def with_timestamps(self, timestamp: int) -> Self:
"""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).
"""
_args = [
Arg("timestamp", timestamp),
]
_ctx = self._select("withTimestamps", _args)
return Directory(_ctx)
[docs]
def without_directory(self, path: str) -> Self:
"""Return a snapshot with a subdirectory removed
Parameters
----------
path:
Path of the subdirectory to remove. Example: ".github/workflows"
"""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutDirectory", _args)
return Directory(_ctx)
[docs]
def without_file(self, path: str) -> Self:
"""Return a snapshot with a file removed
Parameters
----------
path:
Path of the file to remove (e.g., "/file.txt").
"""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutFile", _args)
return Directory(_ctx)
[docs]
def without_files(self, paths: list[str]) -> Self:
"""Return a snapshot with files removed
Parameters
----------
paths:
Paths of the files to remove (e.g., ["/file.txt"]).
"""
_args = [
Arg("paths", paths),
]
_ctx = self._select("withoutFiles", _args)
return Directory(_ctx)
[docs]
def with_(self, cb: Callable[["Directory"], "Directory"]) -> "Directory":
"""Call the provided callable with current Directory.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Engine(Type):
"""The Dagger engine configuration and state"""
[docs]
async def clients(self) -> list[str]:
"""The list of connected client IDs
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("clients", _args)
return await _ctx.execute(list[str])
[docs]
async def id(self) -> str:
"""A unique identifier for this Engine.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def local_cache(self) -> "EngineCache":
"""The local engine cache state tracked by dagql"""
_args: list[Arg] = []
_ctx = self._select("localCache", _args)
return EngineCache(_ctx)
[docs]
async def name(self) -> str:
"""The name of the engine instance.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
@typecheck
class EngineCache(Type):
"""A cache storage for the Dagger engine"""
[docs]
def entry_set(self, *, key: str | None = "") -> "EngineCacheEntrySet":
"""The current set of entries in the cache"""
_args = [
Arg("key", key, ""),
]
_ctx = self._select("entrySet", _args)
return EngineCacheEntrySet(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this EngineCache.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def max_used_space(self) -> int:
"""The maximum bytes to keep in the cache without pruning.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("maxUsedSpace", _args)
return await _ctx.execute(int)
[docs]
async def min_free_space(self) -> int:
"""The target amount of free disk space the garbage collector will
attempt to leave.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("minFreeSpace", _args)
return await _ctx.execute(int)
[docs]
async def prune(
self,
*,
use_default_policy: bool | None = False,
max_used_space: str | None = "",
reserved_space: str | None = "",
min_free_space: str | None = "",
target_space: str | None = "",
) -> Void | None:
"""Prune the cache of releaseable entries
Parameters
----------
use_default_policy:
Use the engine-wide default pruning policy if true, otherwise
prune the whole cache of any releasable entries.
max_used_space:
Override the maximum disk space to keep before pruning (e.g.
"200GB" or "80%").
reserved_space:
Override the minimum disk space to retain during pruning (e.g.
"500GB" or "10%").
min_free_space:
Override the minimum free disk space target during pruning (e.g.
"20GB" or "20%").
target_space:
Override the target disk space to keep after pruning (e.g. "200GB"
or "50%").
Returns
-------
Void | None
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("useDefaultPolicy", use_default_policy, False),
Arg("maxUsedSpace", max_used_space, ""),
Arg("reservedSpace", reserved_space, ""),
Arg("minFreeSpace", min_free_space, ""),
Arg("targetSpace", target_space, ""),
]
_ctx = self._select("prune", _args)
await _ctx.execute()
[docs]
async def reserved_space(self) -> int:
"""The minimum amount of disk space this policy is guaranteed to retain.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("reservedSpace", _args)
return await _ctx.execute(int)
[docs]
async def target_space(self) -> int:
"""The target number of bytes to keep when pruning.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("targetSpace", _args)
return await _ctx.execute(int)
@typecheck
class EngineCacheEntry(Type):
"""An individual cache entry in a cache entry set"""
[docs]
async def actively_used(self) -> bool:
"""Whether the cache entry is actively being used.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("activelyUsed", _args)
return await _ctx.execute(bool)
[docs]
async def created_time_unix_nano(self) -> int:
"""The time the cache entry was created, in Unix nanoseconds.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("createdTimeUnixNano", _args)
return await _ctx.execute(int)
[docs]
async def dagql_call(self) -> str:
"""The DagQL call that produced this cache entry.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("dagqlCall", _args)
return await _ctx.execute(str)
[docs]
async def description(self) -> str:
"""The description of the cache entry.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def disk_space_bytes(self) -> int:
"""The disk space used by the cache entry.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("diskSpaceBytes", _args)
return await _ctx.execute(int)
[docs]
async def id(self) -> str:
"""A unique identifier for this EngineCacheEntry.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def most_recent_use_time_unix_nano(self) -> int:
"""The most recent time the cache entry was used, in Unix nanoseconds.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("mostRecentUseTimeUnixNano", _args)
return await _ctx.execute(int)
[docs]
async def record_type(self) -> str:
"""The type of the cache record (e.g. regular, internal, frontend,
source.local, source.git.checkout, exec.cachemount).
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("recordType", _args)
return await _ctx.execute(str)
[docs]
async def record_types(self) -> list[str]:
"""The storage record types represented by this cache entry.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("recordTypes", _args)
return await _ctx.execute(list[str])
@typecheck
class EngineCacheEntrySet(Type):
"""A set of cache entries returned by a query to a cache"""
[docs]
async def disk_space_bytes(self) -> int:
"""The total disk space used by the cache entries in this set.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("diskSpaceBytes", _args)
return await _ctx.execute(int)
[docs]
async def entries(self) -> list[EngineCacheEntry]:
"""The list of individual cache entries in the set"""
_args: list[Arg] = []
_ctx = self._select("entries", _args)
return await _ctx.execute_object_list(EngineCacheEntry)
[docs]
async def entry_count(self) -> int:
"""The number of cache entries in this set.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("entryCount", _args)
return await _ctx.execute(int)
[docs]
async def id(self) -> str:
"""A unique identifier for this EngineCacheEntrySet.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class EnumTypeDef(Type):
"""A definition of a custom enum defined in a Module."""
[docs]
async def description(self) -> str:
"""A doc string for the enum, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this EnumTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def members(self) -> list["EnumValueTypeDef"]:
"""The members of the enum."""
_args: list[Arg] = []
_ctx = self._select("members", _args)
return await _ctx.execute_object_list(EnumValueTypeDef)
[docs]
async def name(self) -> str:
"""The name of the enum.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this enum declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
async def source_module_name(self) -> str:
"""If this EnumTypeDef is associated with a Module, the name of the
module. Unset otherwise.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceModuleName", _args)
return await _ctx.execute(str)
[docs]
async def values(self) -> list["EnumValueTypeDef"]:
"""The members of the enum.
.. deprecated::
use members instead
"""
warnings.warn(
'Method "values" is deprecated: use members instead',
DeprecationWarning,
stacklevel=4,
)
_args: list[Arg] = []
_ctx = self._select("values", _args)
return await _ctx.execute_object_list(EnumValueTypeDef)
@typecheck
class EnumValueTypeDef(Type):
"""A definition of a value in a custom enum defined in a Module."""
[docs]
async def deprecated(self) -> str | None:
"""The reason this enum member is deprecated, if any.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("deprecated", _args)
return await _ctx.execute(str | None)
[docs]
async def description(self) -> str:
"""A doc string for the enum member, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this EnumValueTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the enum member.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this enum member declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
async def value(self) -> str:
"""The value of the enum member
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
@typecheck
class Env(Type):
[docs]
def check(self, name: str) -> Check:
"""Return the check with the given name from the installed modules. Must
match exactly one check.
.. caution::
Experimental: Checks API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
name:
The name of the check to retrieve
"""
_args = [
Arg("name", name),
]
_ctx = self._select("check", _args)
return Check(_ctx)
[docs]
def checks(
self,
*,
include: list[str] | None = None,
no_generate: bool | None = None,
) -> CheckGroup:
"""Return all checks defined by the installed modules
.. caution::
Experimental: Checks API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
include:
Only include checks matching the specified patterns
no_generate:
When true, only return annotated check functions; exclude
generate-as-checks
"""
_args = [
Arg("include", include, None),
Arg("noGenerate", no_generate, None),
]
_ctx = self._select("checks", _args)
return CheckGroup(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this Env.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def output(self, name: str) -> Binding:
"""Retrieves an output binding by name"""
_args = [
Arg("name", name),
]
_ctx = self._select("output", _args)
return Binding(_ctx)
[docs]
async def outputs(self) -> list[Binding]:
"""Returns all declared output bindings for the environment"""
_args: list[Arg] = []
_ctx = self._select("outputs", _args)
return await _ctx.execute_object_list(Binding)
[docs]
def services(
self,
*,
include: list[str] | None = None,
) -> "UpGroup":
"""Return all services defined by the installed modules
.. caution::
Experimental: Services API is highly experimental and may be
removed or replaced entirely.
Parameters
----------
include:
Only include services matching the specified patterns
"""
_args = [
Arg("include", include, None),
]
_ctx = self._select("services", _args)
return UpGroup(_ctx)
[docs]
def with_address_output(self, name: str, description: str) -> Self:
"""Declare a desired Address output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withAddressOutput", _args)
return Env(_ctx)
[docs]
def with_cache_volume_output(self, name: str, description: str) -> Self:
"""Declare a desired CacheVolume output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withCacheVolumeOutput", _args)
return Env(_ctx)
[docs]
def with_changeset_output(self, name: str, description: str) -> Self:
"""Declare a desired Changeset output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withChangesetOutput", _args)
return Env(_ctx)
[docs]
def with_check_group_output(self, name: str, description: str) -> Self:
"""Declare a desired CheckGroup output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withCheckGroupOutput", _args)
return Env(_ctx)
[docs]
def with_check_output(self, name: str, description: str) -> Self:
"""Declare a desired Check output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withCheckOutput", _args)
return Env(_ctx)
[docs]
def with_cloud_output(self, name: str, description: str) -> Self:
"""Declare a desired Cloud output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withCloudOutput", _args)
return Env(_ctx)
[docs]
def with_container_output(self, name: str, description: str) -> Self:
"""Declare a desired Container output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withContainerOutput", _args)
return Env(_ctx)
[docs]
def with_current_module(self) -> Self:
"""Installs the current module into the environment, exposing its
functions to the model
Contextual path arguments will be populated using the environment's
workspace.
"""
_args: list[Arg] = []
_ctx = self._select("withCurrentModule", _args)
return Env(_ctx)
[docs]
def with_diff_stat_output(self, name: str, description: str) -> Self:
"""Declare a desired DiffStat output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withDiffStatOutput", _args)
return Env(_ctx)
[docs]
def with_directory_output(self, name: str, description: str) -> Self:
"""Declare a desired Directory output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withDirectoryOutput", _args)
return Env(_ctx)
[docs]
def with_env_file_output(self, name: str, description: str) -> Self:
"""Declare a desired EnvFile output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withEnvFileOutput", _args)
return Env(_ctx)
[docs]
def with_env_output(self, name: str, description: str) -> Self:
"""Declare a desired Env output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withEnvOutput", _args)
return Env(_ctx)
[docs]
def with_file_output(self, name: str, description: str) -> Self:
"""Declare a desired File output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withFileOutput", _args)
return Env(_ctx)
[docs]
def with_generator_group_output(self, name: str, description: str) -> Self:
"""Declare a desired GeneratorGroup output to be assigned in the
environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withGeneratorGroupOutput", _args)
return Env(_ctx)
[docs]
def with_generator_output(self, name: str, description: str) -> Self:
"""Declare a desired Generator output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withGeneratorOutput", _args)
return Env(_ctx)
[docs]
def with_git_ref_output(self, name: str, description: str) -> Self:
"""Declare a desired GitRef output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withGitRefOutput", _args)
return Env(_ctx)
[docs]
def with_git_repository_output(self, name: str, description: str) -> Self:
"""Declare a desired GitRepository output to be assigned in the
environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withGitRepositoryOutput", _args)
return Env(_ctx)
[docs]
def with_http_state_output(self, name: str, description: str) -> Self:
"""Declare a desired HTTPState output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withHTTPStateOutput", _args)
return Env(_ctx)
[docs]
def with_json_value_output(self, name: str, description: str) -> Self:
"""Declare a desired JSONValue output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withJSONValueOutput", _args)
return Env(_ctx)
[docs]
def with_main_module(self, module: "Module") -> Self:
"""Sets the main module for this environment (the project being worked
on)
Contextual path arguments will be populated using the environment's
workspace.
"""
_args = [
Arg("module", module),
]
_ctx = self._select("withMainModule", _args)
return Env(_ctx)
[docs]
def with_module(self, module: "Module") -> Self:
"""Installs a module into the environment, exposing its functions to the
model
Contextual path arguments will be populated using the environment's
workspace.
.. deprecated::
Use withMainModule instead
"""
warnings.warn(
'Method "with_module" is deprecated: Use withMainModule instead',
DeprecationWarning,
stacklevel=4,
)
_args = [
Arg("module", module),
]
_ctx = self._select("withModule", _args)
return Env(_ctx)
[docs]
def with_module_config_client_output(self, name: str, description: str) -> Self:
"""Declare a desired ModuleConfigClient output to be assigned in the
environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withModuleConfigClientOutput", _args)
return Env(_ctx)
[docs]
def with_module_output(self, name: str, description: str) -> Self:
"""Declare a desired Module output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withModuleOutput", _args)
return Env(_ctx)
[docs]
def with_module_source_output(self, name: str, description: str) -> Self:
"""Declare a desired ModuleSource output to be assigned in the
environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withModuleSourceOutput", _args)
return Env(_ctx)
[docs]
def with_search_result_output(self, name: str, description: str) -> Self:
"""Declare a desired SearchResult output to be assigned in the
environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withSearchResultOutput", _args)
return Env(_ctx)
[docs]
def with_search_submatch_output(self, name: str, description: str) -> Self:
"""Declare a desired SearchSubmatch output to be assigned in the
environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withSearchSubmatchOutput", _args)
return Env(_ctx)
[docs]
def with_secret_output(self, name: str, description: str) -> Self:
"""Declare a desired Secret output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withSecretOutput", _args)
return Env(_ctx)
[docs]
def with_service_output(self, name: str, description: str) -> Self:
"""Declare a desired Service output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withServiceOutput", _args)
return Env(_ctx)
[docs]
def with_socket_output(self, name: str, description: str) -> Self:
"""Declare a desired Socket output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withSocketOutput", _args)
return Env(_ctx)
[docs]
def with_stat_output(self, name: str, description: str) -> Self:
"""Declare a desired Stat output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withStatOutput", _args)
return Env(_ctx)
[docs]
def with_string_output(self, name: str, description: str) -> Self:
"""Declares a desired string output binding
Parameters
----------
name:
The name of the binding
description:
The description of the output
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withStringOutput", _args)
return Env(_ctx)
[docs]
def with_up_group_output(self, name: str, description: str) -> Self:
"""Declare a desired UpGroup output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withUpGroupOutput", _args)
return Env(_ctx)
[docs]
def with_up_output(self, name: str, description: str) -> Self:
"""Declare a desired Up output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withUpOutput", _args)
return Env(_ctx)
[docs]
def with_workspace(self, workspace: Directory) -> Self:
"""Returns a new environment with the provided workspace
Parameters
----------
workspace:
The directory to set as the host filesystem
"""
_args = [
Arg("workspace", workspace),
]
_ctx = self._select("withWorkspace", _args)
return Env(_ctx)
[docs]
def with_workspace_output(self, name: str, description: str) -> Self:
"""Declare a desired Workspace output to be assigned in the environment
Parameters
----------
name:
The name of the binding
description:
A description of the desired value of the binding
"""
_args = [
Arg("name", name),
Arg("description", description),
]
_ctx = self._select("withWorkspaceOutput", _args)
return Env(_ctx)
[docs]
def without_outputs(self) -> Self:
"""Returns a new environment without any outputs"""
_args: list[Arg] = []
_ctx = self._select("withoutOutputs", _args)
return Env(_ctx)
[docs]
def workspace(self) -> Directory:
_args: list[Arg] = []
_ctx = self._select("workspace", _args)
return Directory(_ctx)
[docs]
def with_(self, cb: Callable[["Env"], "Env"]) -> "Env":
"""Call the provided callable with current Env.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class EnvFile(Type):
"""A collection of environment variables."""
[docs]
def as_file(self) -> "File":
"""Return as a file"""
_args: list[Arg] = []
_ctx = self._select("asFile", _args)
return File(_ctx)
[docs]
async def exists(self, name: str) -> bool:
"""Check if a variable exists
Parameters
----------
name:
Variable name
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("exists", _args)
return await _ctx.execute(bool)
[docs]
async def get(
self,
name: str,
*,
raw: bool | None = None,
) -> str:
"""Lookup a variable (last occurrence wins) and return its value, or an
empty string
Parameters
----------
name:
Variable name
raw:
Return the value exactly as written to the file. No quote removal
or variable expansion
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
Arg("raw", raw, None),
]
_ctx = self._select("get", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this EnvFile.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def namespace(self, prefix: str) -> Self:
"""Filters variables by prefix and removes the pref from keys. Variables
without the prefix are excluded. For example, with the prefix
"MY_APP_" and variables: MY_APP_TOKEN=topsecret MY_APP_NAME=hello
FOO=bar the resulting environment will contain: TOKEN=topsecret
NAME=hello
Parameters
----------
prefix:
The prefix to filter by
"""
_args = [
Arg("prefix", prefix),
]
_ctx = self._select("namespace", _args)
return EnvFile(_ctx)
[docs]
async def variables(self, *, raw: bool | None = None) -> list["EnvVariable"]:
"""Return all variables
Parameters
----------
raw:
Return values exactly as written to the file. No quote removal or
variable expansion
"""
_args = [
Arg("raw", raw, None),
]
_ctx = self._select("variables", _args)
return await _ctx.execute_object_list(EnvVariable)
[docs]
def with_variable(self, name: str, value: str) -> Self:
"""Add a variable
Parameters
----------
name:
Variable name
value:
Variable value
"""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withVariable", _args)
return EnvFile(_ctx)
[docs]
def without_variable(self, name: str) -> Self:
"""Remove all occurrences of the named variable
Parameters
----------
name:
Variable name
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutVariable", _args)
return EnvFile(_ctx)
[docs]
def with_(self, cb: Callable[["EnvFile"], "EnvFile"]) -> "EnvFile":
"""Call the provided callable with current EnvFile.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class EnvVariable(Type):
"""An environment variable name and value."""
[docs]
async def id(self) -> str:
"""A unique identifier for this EnvVariable.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The environment variable name.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def value(self) -> str:
"""The environment variable value.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
@typecheck
class Error(Type):
[docs]
async def id(self) -> str:
"""A unique identifier for this Error.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def message(self) -> str:
"""A description of the error.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("message", _args)
return await _ctx.execute(str)
[docs]
async def values(self) -> list["ErrorValue"]:
"""The extensions of the error."""
_args: list[Arg] = []
_ctx = self._select("values", _args)
return await _ctx.execute_object_list(ErrorValue)
[docs]
def with_value(self, name: str, value: JSON) -> Self:
"""Add a value to the error.
Parameters
----------
name:
The name of the value.
value:
The value to store on the error.
"""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withValue", _args)
return Error(_ctx)
[docs]
def with_(self, cb: Callable[["Error"], "Error"]) -> "Error":
"""Call the provided callable with current Error.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class ErrorValue(Type):
[docs]
async def id(self) -> str:
"""A unique identifier for this ErrorValue.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the value.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def value(self) -> JSON:
"""The value.
Returns
-------
JSON
An arbitrary JSON-encoded value.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(JSON)
@typecheck
class FieldTypeDef(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)."""
[docs]
async def deprecated(self) -> str | None:
"""The reason this enum member is deprecated, if any.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("deprecated", _args)
return await _ctx.execute(str | None)
[docs]
async def description(self) -> str:
"""A doc string for the field, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this FieldTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the field in lowerCamelCase format.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this field declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
def type_def(self) -> "TypeDef":
"""The type of the field."""
_args: list[Arg] = []
_ctx = self._select("typeDef", _args)
return TypeDef(_ctx)
@typecheck
class File(Type):
"""A file."""
[docs]
def as_env_file(self, *, expand: bool | None = None) -> EnvFile:
"""Parse as an env file
Parameters
----------
expand:
Replace "${VAR}" or "$VAR" with the value of other vars
.. deprecated:: Variable expansion is now enabled by default
"""
_args = [
Arg("expand", expand, None),
]
_ctx = self._select("asEnvFile", _args)
return EnvFile(_ctx)
[docs]
def as_json(self) -> "JSONValue":
"""Parse the file contents as JSON."""
_args: list[Arg] = []
_ctx = self._select("asJSON", _args)
return JSONValue(_ctx)
[docs]
def chown(self, owner: str) -> Self:
"""Change the owner of the file recursively.
Parameters
----------
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.
"""
_args = [
Arg("owner", owner),
]
_ctx = self._select("chown", _args)
return File(_ctx)
[docs]
async def contents(
self,
*,
offset_lines: int | None = None,
limit_lines: int | None = None,
) -> str:
"""Retrieves the contents of the file.
Parameters
----------
offset_lines:
Start reading after this line
limit_lines:
Maximum number of lines to read
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("offsetLines", offset_lines, None),
Arg("limitLines", limit_lines, None),
]
_ctx = self._select("contents", _args)
return await _ctx.execute(str)
[docs]
async def digest(
self,
*,
exclude_metadata: bool | None = False,
) -> str:
"""Return the file's digest. The format of the digest is not guaranteed
to be stable between releases of Dagger. It is guaranteed to be stable
between invocations of the same Dagger engine.
Parameters
----------
exclude_metadata:
If true, exclude metadata from the digest.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("excludeMetadata", exclude_metadata, False),
]
_ctx = self._select("digest", _args)
return await _ctx.execute(str)
[docs]
async def export(
self,
path: str,
*,
allow_parent_dir_path: bool | None = False,
) -> str:
"""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
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("path", path),
Arg("allowParentDirPath", allow_parent_dir_path, False),
]
_ctx = self._select("export", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this File.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""Retrieves the name of the file.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def search(
self,
pattern: str,
*,
literal: bool | None = False,
multiline: bool | None = False,
dotall: bool | None = False,
insensitive: bool | None = False,
skip_ignored: bool | None = False,
skip_hidden: bool | None = False,
files_only: bool | None = False,
limit: int | None = None,
paths: list[str] | None = None,
globs: list[str] | None = None,
) -> list["SearchResult"]:
"""Searches for content matching the given regular expression or literal
string.
Uses Rust regex syntax; escape literal ., [, ], {, }, | with
backslashes.
Parameters
----------
pattern:
The text to match.
literal:
Interpret the pattern as a literal string instead of a regular
expression.
multiline:
Enable searching across multiple lines.
dotall:
Allow the . pattern to match newlines in multiline mode.
insensitive:
Enable case-insensitive matching.
skip_ignored:
Honor .gitignore, .ignore, and .rgignore files.
skip_hidden:
Skip hidden files (files starting with .).
files_only:
Only return matching files, not lines and content
limit:
Limit the number of results to return
paths:
globs:
"""
_args = [
Arg("pattern", pattern),
Arg("literal", literal, False),
Arg("multiline", multiline, False),
Arg("dotall", dotall, False),
Arg("insensitive", insensitive, False),
Arg("skipIgnored", skip_ignored, False),
Arg("skipHidden", skip_hidden, False),
Arg("filesOnly", files_only, False),
Arg("limit", limit, None),
Arg("paths", [] if paths is None else paths, []),
Arg("globs", [] if globs is None else globs, []),
]
_ctx = self._select("search", _args)
return await _ctx.execute_object_list(SearchResult)
[docs]
async def size(self) -> int:
"""Retrieves the size of the file, in bytes.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("size", _args)
return await _ctx.execute(int)
[docs]
def stat(self) -> "Stat":
"""Return file status"""
_args: list[Arg] = []
_ctx = self._select("stat", _args)
return Stat(_ctx)
[docs]
async def sync(self) -> Self:
"""Force evaluation in the engine.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def with_name(self, name: str) -> Self:
"""Retrieves this file with its name set to the given name.
Parameters
----------
name:
Name to set file to.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withName", _args)
return File(_ctx)
[docs]
def with_replaced(
self,
search: str,
replacement: str,
*,
all: bool | None = False,
first_from: int | None = None,
) -> Self:
"""Retrieves the file with content replaced with the given text.
If 'all' is true, all occurrences of the pattern will be replaced.
If 'firstAfter' is specified, only the first match starting at the
specified line will be replaced.
If neither are specified, and there are multiple matches for the
pattern, this will error.
If there are no matches for the pattern, this will error.
Parameters
----------
search:
The text to match.
replacement:
The text to match.
all:
Replace all occurrences of the pattern.
first_from:
Replace the first match starting from the specified line.
"""
_args = [
Arg("search", search),
Arg("replacement", replacement),
Arg("all", all, False),
Arg("firstFrom", first_from, None),
]
_ctx = self._select("withReplaced", _args)
return File(_ctx)
[docs]
def with_timestamps(self, timestamp: int) -> Self:
"""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).
"""
_args = [
Arg("timestamp", timestamp),
]
_ctx = self._select("withTimestamps", _args)
return File(_ctx)
[docs]
def with_(self, cb: Callable[["File"], "File"]) -> "File":
"""Call the provided callable with current File.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Function(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."""
[docs]
async def args(self) -> list["FunctionArg"]:
"""Arguments accepted by the function, if any."""
_args: list[Arg] = []
_ctx = self._select("args", _args)
return await _ctx.execute_object_list(FunctionArg)
[docs]
async def deprecated(self) -> str | None:
"""The reason this function is deprecated, if any.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("deprecated", _args)
return await _ctx.execute(str | None)
[docs]
async def description(self) -> str:
"""A doc string for the function, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this Function.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the function.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def return_type(self) -> "TypeDef":
"""The type returned by the function."""
_args: list[Arg] = []
_ctx = self._select("returnType", _args)
return TypeDef(_ctx)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this function declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
async def source_module_name(self) -> str:
"""If this function is provided by a module, the name of the module.
Unset otherwise.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceModuleName", _args)
return await _ctx.execute(str)
[docs]
def with_arg(
self,
name: str,
type_def: "TypeDef",
*,
description: str | None = "",
default_value: JSON | None = None,
default_path: str | None = "",
ignore: list[str] | None = None,
source_map: "SourceMap | None" = None,
deprecated: str | None = None,
default_address: str | None = "",
) -> Self:
"""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
default_path:
If the argument is a Directory or File type, default to load path
from context directory, relative to root directory.
ignore:
Patterns to ignore when loading the contextual argument value.
source_map:
The source map for the argument definition.
deprecated:
If deprecated, the reason or migration path.
default_address:
"""
_args = [
Arg("name", name),
Arg("typeDef", type_def),
Arg("description", description, ""),
Arg("defaultValue", default_value, None),
Arg("defaultPath", default_path, ""),
Arg("ignore", [] if ignore is None else ignore, []),
Arg("sourceMap", source_map, None),
Arg("deprecated", deprecated, None),
Arg("defaultAddress", default_address, ""),
]
_ctx = self._select("withArg", _args)
return Function(_ctx)
[docs]
def with_cache_policy(
self,
policy: FunctionCachePolicy,
*,
time_to_live: str | None = None,
) -> Self:
"""Returns the function updated to use the provided cache policy.
Parameters
----------
policy:
The cache policy to use.
time_to_live:
The TTL for the cache policy, if applicable. Provided as a
duration string, e.g. "5m", "1h30s".
"""
_args = [
Arg("policy", policy),
Arg("timeToLive", time_to_live, None),
]
_ctx = self._select("withCachePolicy", _args)
return Function(_ctx)
[docs]
def with_check(self) -> Self:
"""Returns the function with a flag indicating it's a check."""
_args: list[Arg] = []
_ctx = self._select("withCheck", _args)
return Function(_ctx)
[docs]
def with_deprecated(self, *, reason: str | None = None) -> Self:
"""Returns the function with the provided deprecation reason.
Parameters
----------
reason:
Reason or migration path describing the deprecation.
"""
_args = [
Arg("reason", reason, None),
]
_ctx = self._select("withDeprecated", _args)
return Function(_ctx)
[docs]
def with_description(self, description: str) -> Self:
"""Returns the function with the given doc string.
Parameters
----------
description:
The doc string to set.
"""
_args = [
Arg("description", description),
]
_ctx = self._select("withDescription", _args)
return Function(_ctx)
[docs]
def with_generator(self) -> Self:
"""Returns the function with a flag indicating it's a generator."""
_args: list[Arg] = []
_ctx = self._select("withGenerator", _args)
return Function(_ctx)
[docs]
def with_source_map(self, source_map: "SourceMap") -> Self:
"""Returns the function with the given source map.
Parameters
----------
source_map:
The source map for the function definition.
"""
_args = [
Arg("sourceMap", source_map),
]
_ctx = self._select("withSourceMap", _args)
return Function(_ctx)
[docs]
def with_up(self) -> Self:
"""Returns the function with a flag indicating it returns a service for
dagger up.
"""
_args: list[Arg] = []
_ctx = self._select("withUp", _args)
return Function(_ctx)
[docs]
def with_(self, cb: Callable[["Function"], "Function"]) -> "Function":
"""Call the provided callable with current Function.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class FunctionArg(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."""
[docs]
async def default_address(self) -> str:
"""Only applies to arguments of type Container. If the argument is not
set, load it from the given address (e.g. alpine:latest)
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("defaultAddress", _args)
return await _ctx.execute(str)
[docs]
async def default_path(self) -> str:
"""Only applies to arguments of type File or Directory. If the argument
is not set, load it from the given path in the context directory
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("defaultPath", _args)
return await _ctx.execute(str)
[docs]
async def default_value(self) -> JSON:
"""A default value to use for this argument when not explicitly set by
the caller, if any.
Returns
-------
JSON
An arbitrary JSON-encoded value.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("defaultValue", _args)
return await _ctx.execute(JSON)
[docs]
async def deprecated(self) -> str | None:
"""The reason this function is deprecated, if any.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("deprecated", _args)
return await _ctx.execute(str | None)
[docs]
async def description(self) -> str:
"""A doc string for the argument, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this FunctionArg.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def ignore(self) -> list[str]:
"""Only applies to arguments of type Directory. The ignore patterns are
applied to the input directory, and matching entries are filtered out,
in a cache-efficient manner.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("ignore", _args)
return await _ctx.execute(list[str])
[docs]
async def name(self) -> str:
"""The name of the argument in lowerCamelCase format.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this arg declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
def type_def(self) -> "TypeDef":
"""The type of the argument."""
_args: list[Arg] = []
_ctx = self._select("typeDef", _args)
return TypeDef(_ctx)
@typecheck
class FunctionCall(Type):
"""An active function call."""
[docs]
async def id(self) -> str:
"""A unique identifier for this FunctionCall.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the function being called.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def parent(self) -> JSON:
"""The value of the parent object of the function being called. If the
function is top-level to the module, this is always an empty object.
Returns
-------
JSON
An arbitrary JSON-encoded value.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("parent", _args)
return await _ctx.execute(JSON)
[docs]
async def parent_name(self) -> str:
"""The name of the parent object of the function being called. If the
function is top-level to the module, this is the name of the module.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("parentName", _args)
return await _ctx.execute(str)
[docs]
async def return_error(self, error: Error) -> Void | None:
"""Return an error from the function.
Parameters
----------
error:
The error to return.
Returns
-------
Void | None
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("error", error),
]
_ctx = self._select("returnError", _args)
await _ctx.execute()
[docs]
async def return_value(self, value: JSON) -> Void | None:
"""Set the return value of the function call to the provided value.
Parameters
----------
value:
JSON serialization of the return value.
Returns
-------
Void | None
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("value", value),
]
_ctx = self._select("returnValue", _args)
await _ctx.execute()
@typecheck
class FunctionCallArgValue(Type):
"""A value passed as a named argument to a function call."""
[docs]
async def id(self) -> str:
"""A unique identifier for this FunctionCallArgValue.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the argument.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def value(self) -> JSON:
"""The value of the argument represented as a JSON serialized string.
Returns
-------
JSON
An arbitrary JSON-encoded value.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(JSON)
@typecheck
class GeneratedCode(Type):
"""The result of running an SDK's codegen."""
[docs]
def code(self) -> Directory:
"""The directory containing the generated code."""
_args: list[Arg] = []
_ctx = self._select("code", _args)
return Directory(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this GeneratedCode.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def vcs_generated_paths(self) -> list[str]:
"""List of paths to mark generated in version control (i.e.
.gitattributes).
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("vcsGeneratedPaths", _args)
return await _ctx.execute(list[str])
[docs]
async def vcs_ignored_paths(self) -> list[str]:
"""List of paths to ignore in version control (i.e. .gitignore).
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("vcsIgnoredPaths", _args)
return await _ctx.execute(list[str])
[docs]
def with_vcs_generated_paths(self, paths: list[str]) -> Self:
"""Set the list of paths to mark generated in version control."""
_args = [
Arg("paths", paths),
]
_ctx = self._select("withVCSGeneratedPaths", _args)
return GeneratedCode(_ctx)
[docs]
def with_vcs_ignored_paths(self, paths: list[str]) -> Self:
"""Set the list of paths to ignore in version control."""
_args = [
Arg("paths", paths),
]
_ctx = self._select("withVCSIgnoredPaths", _args)
return GeneratedCode(_ctx)
[docs]
def with_(
self, cb: Callable[["GeneratedCode"], "GeneratedCode"]
) -> "GeneratedCode":
"""Call the provided callable with current GeneratedCode.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Generator(Type):
[docs]
def changes(self) -> Changeset:
"""The generated changeset from the last run"""
_args: list[Arg] = []
_ctx = self._select("changes", _args)
return Changeset(_ctx)
[docs]
async def completed(self) -> bool:
"""Whether the generator complete
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("completed", _args)
return await _ctx.execute(bool)
[docs]
async def description(self) -> str:
"""Return the description of the generator
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this Generator.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def is_empty(self) -> bool:
"""Whether changeset from the last generator run is empty or not
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("isEmpty", _args)
return await _ctx.execute(bool)
[docs]
async def name(self) -> str:
"""Return the fully qualified name of the generator
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def original_module(self) -> "Module":
"""The original module in which the generator has been defined"""
_args: list[Arg] = []
_ctx = self._select("originalModule", _args)
return Module(_ctx)
[docs]
async def path(self) -> list[str]:
"""The path of the generator within its module
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("path", _args)
return await _ctx.execute(list[str])
[docs]
def run(self) -> Self:
"""Execute the generator"""
_args: list[Arg] = []
_ctx = self._select("run", _args)
return Generator(_ctx)
[docs]
def with_(self, cb: Callable[["Generator"], "Generator"]) -> "Generator":
"""Call the provided callable with current Generator.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class GeneratorGroup(Type):
[docs]
def changes(
self,
*,
on_conflict: ChangesetsMergeConflict
| None = ChangesetsMergeConflict.FAIL_EARLY,
) -> Changeset:
"""The combined changes from the last run of the generators
If any conflict occurs, for instance if the same file is modified by
multiple generators, or if a file is both modified and deleted, an
error is raised and the merge of the changesets will failed.
Set 'continueOnConflicts' flag to force to merge the changes in a
'last write wins' strategy.
Parameters
----------
on_conflict:
Strategy to apply on conflicts between generators
"""
_args = [
Arg("onConflict", on_conflict, ChangesetsMergeConflict.FAIL_EARLY),
]
_ctx = self._select("changes", _args)
return Changeset(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this GeneratorGroup.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def is_empty(self) -> bool:
"""Whether the generated changeset from the last run is empty or not
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("isEmpty", _args)
return await _ctx.execute(bool)
[docs]
async def list_(self) -> list[Generator]:
"""Return a list of individual generators and their details"""
_args: list[Arg] = []
_ctx = self._select("list", _args)
return await _ctx.execute_object_list(Generator)
[docs]
def run(self) -> Self:
"""Execute all selected generators"""
_args: list[Arg] = []
_ctx = self._select("run", _args)
return GeneratorGroup(_ctx)
[docs]
def with_(
self, cb: Callable[["GeneratorGroup"], "GeneratorGroup"]
) -> "GeneratorGroup":
"""Call the provided callable with current GeneratorGroup.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class GitRef(Type):
"""A git ref (tag, branch, or commit)."""
[docs]
async def commit(self) -> str:
"""The resolved commit id at this ref.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("commit", _args)
return await _ctx.execute(str)
[docs]
def common_ancestor(self, other: Self) -> Self:
"""Find the best common ancestor between this ref and another ref.
Parameters
----------
other:
The other ref to compare against.
"""
_args = [
Arg("other", other),
]
_ctx = self._select("commonAncestor", _args)
return GitRef(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this GitRef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def ref(self) -> str:
"""The resolved ref name at this ref.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("ref", _args)
return await _ctx.execute(str)
[docs]
def tree(
self,
*,
discard_git_dir: bool | None = False,
depth: int | None = 1,
include_tags: bool | None = False,
) -> Directory:
"""The filesystem tree at this ref.
Parameters
----------
discard_git_dir:
Set to true to discard .git directory.
depth:
The depth of the tree to fetch.
include_tags:
Set to true to populate tag refs in the local checkout .git.
"""
_args = [
Arg("discardGitDir", discard_git_dir, False),
Arg("depth", depth, 1),
Arg("includeTags", include_tags, False),
]
_ctx = self._select("tree", _args)
return Directory(_ctx)
[docs]
def with_(self, cb: Callable[["GitRef"], "GitRef"]) -> "GitRef":
"""Call the provided callable with current GitRef.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class GitRepository(Type):
"""A git repository."""
[docs]
def branch(self, name: str) -> GitRef:
"""Returns details of a branch.
Parameters
----------
name:
Branch's name (e.g., "main").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("branch", _args)
return GitRef(_ctx)
[docs]
async def branches(
self,
*,
patterns: list[str] | None = None,
) -> list[str]:
"""branches that match any of the given glob patterns.
Parameters
----------
patterns:
Glob patterns (e.g., "refs/tags/v*").
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("patterns", patterns, None),
]
_ctx = self._select("branches", _args)
return await _ctx.execute(list[str])
[docs]
def commit(self, id: str) -> GitRef:
"""Returns details of a commit.
Parameters
----------
id:
Identifier of the commit (e.g.,
"b6315d8f2810962c601af73f86831f6866ea798b").
"""
_args = [
Arg("id", id),
]
_ctx = self._select("commit", _args)
return GitRef(_ctx)
[docs]
def head(self) -> GitRef:
"""Returns details for HEAD."""
_args: list[Arg] = []
_ctx = self._select("head", _args)
return GitRef(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this GitRepository.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def latest_version(self) -> GitRef:
"""Returns details for the latest semver tag."""
_args: list[Arg] = []
_ctx = self._select("latestVersion", _args)
return GitRef(_ctx)
[docs]
def ref(self, name: str) -> GitRef:
"""Returns details of a ref.
Parameters
----------
name:
Ref's name (can be a commit identifier, a tag name, a branch name,
or a fully-qualified ref).
"""
_args = [
Arg("name", name),
]
_ctx = self._select("ref", _args)
return GitRef(_ctx)
[docs]
def tag(self, name: str) -> GitRef:
"""Returns details of a tag.
Parameters
----------
name:
Tag's name (e.g., "v0.3.9").
"""
_args = [
Arg("name", name),
]
_ctx = self._select("tag", _args)
return GitRef(_ctx)
[docs]
def uncommitted(self) -> Changeset:
"""Returns the changeset of uncommitted changes in the git repository."""
_args: list[Arg] = []
_ctx = self._select("uncommitted", _args)
return Changeset(_ctx)
[docs]
async def url(self) -> str | None:
"""The URL of the git repository.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("url", _args)
return await _ctx.execute(str | None)
@typecheck
class HTTPState(Type):
"""An internal persistent HTTP state."""
[docs]
async def id(self) -> str:
"""A unique identifier for this HTTPState.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class HealthcheckConfig(Type):
"""Image healthcheck configuration."""
[docs]
async def args(self) -> list[str]:
"""Healthcheck command arguments.
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("args", _args)
return await _ctx.execute(list[str])
[docs]
async def id(self) -> str:
"""A unique identifier for this HealthcheckConfig.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def interval(self) -> str:
"""Interval between running healthcheck. Example:30s
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("interval", _args)
return await _ctx.execute(str)
[docs]
async def retries(self) -> int:
"""The maximum number of consecutive failures before the container is
marked as unhealthy. Example:3
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("retries", _args)
return await _ctx.execute(int)
[docs]
async def shell(self) -> bool:
"""Healthcheck command is a shell command.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("shell", _args)
return await _ctx.execute(bool)
[docs]
async def start_interval(self) -> str:
"""StartInterval configures the duration between checks during the
startup phase. Example:5s
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("startInterval", _args)
return await _ctx.execute(str)
[docs]
async def start_period(self) -> str:
"""StartPeriod allows for failures during this initial startup period
which do not count towards maximum number of retries. Example:0s
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("startPeriod", _args)
return await _ctx.execute(str)
[docs]
async def timeout(self) -> str:
"""Healthcheck timeout. Example:3s
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("timeout", _args)
return await _ctx.execute(str)
@typecheck
class Host(Type):
"""Information about the host environment."""
[docs]
def container_image(self, name: str) -> Container:
"""Accesses a container image on the host.
Parameters
----------
name:
Name of the image to access.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("containerImage", _args)
return Container(_ctx)
[docs]
def directory(
self,
path: str,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
no_cache: bool | None = False,
gitignore: bool | None = False,
) -> Directory:
"""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.*"]).
no_cache:
If true, the directory will always be reloaded from the host.
gitignore:
Apply .gitignore filter rules inside the directory
"""
_args = [
Arg("path", path),
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("noCache", no_cache, False),
Arg("gitignore", gitignore, False),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
def file(
self,
path: str,
*,
no_cache: bool | None = False,
) -> File:
"""Accesses a file on the host.
Parameters
----------
path:
Location of the file to retrieve (e.g., "README.md").
no_cache:
If true, the file will always be reloaded from the host.
"""
_args = [
Arg("path", path),
Arg("noCache", no_cache, False),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs]
async def find_up(
self,
name: str,
*,
no_cache: bool | None = False,
) -> str | None:
"""Search for a file or directory by walking up the tree from system
workdir. Return its relative path. If no match, return null
Parameters
----------
name:
name of the file or directory to search for
no_cache:
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
Arg("noCache", no_cache, False),
]
_ctx = self._select("findUp", _args)
return await _ctx.execute(str | None)
[docs]
async def id(self) -> str:
"""A unique identifier for this Host.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def service(
self,
ports: list[PortForward],
*,
host: str | None = "localhost",
) -> "Service":
"""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.
"""
_args = [
Arg("ports", ports),
Arg("host", host, "localhost"),
]
_ctx = self._select("service", _args)
return Service(_ctx)
[docs]
def tunnel(
self,
service: "Service",
*,
native: bool | None = False,
ports: list[PortForward] | None = None,
) -> "Service":
"""Creates a tunnel that forwards traffic from the host to a service.
Parameters
----------
service:
Service to send traffic from the tunnel.
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.
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.
"""
_args = [
Arg("service", service),
Arg("native", native, False),
Arg("ports", [] if ports is None else ports, []),
]
_ctx = self._select("tunnel", _args)
return Service(_ctx)
[docs]
def unix_socket(self, path: str) -> "Socket":
"""Accesses a Unix socket on the host.
Parameters
----------
path:
Location of the Unix socket (e.g., "/var/run/docker.sock").
"""
_args = [
Arg("path", path),
]
_ctx = self._select("unixSocket", _args)
return Socket(_ctx)
@typecheck
class InputTypeDef(Type):
"""A graphql input type, which is essentially just a group of named
args. This is currently only used to represent pre-existing usage of
graphql input types in the core API. It is not used by user modules
and shouldn't ever be as user module accept input objects via their id
rather than graphql input types."""
@typecheck
class InterfaceTypeDef(Type):
"""A definition of a custom interface defined in a Module."""
[docs]
async def description(self) -> str:
"""The doc string for the interface, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def functions(self) -> list[Function]:
"""Functions defined on this interface, if any."""
_args: list[Arg] = []
_ctx = self._select("functions", _args)
return await _ctx.execute_object_list(Function)
[docs]
async def id(self) -> str:
"""A unique identifier for this InterfaceTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the interface.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this interface declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
async def source_module_name(self) -> str:
"""If this InterfaceTypeDef is associated with a Module, the name of the
module. Unset otherwise.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceModuleName", _args)
return await _ctx.execute(str)
@typecheck
class JSONValue(Type):
[docs]
async def as_array(self) -> list["JSONValue"]:
"""Decode an array from json"""
_args: list[Arg] = []
_ctx = self._select("asArray", _args)
return await _ctx.execute_object_list(JSONValue)
[docs]
async def as_boolean(self) -> bool:
"""Decode a boolean from json
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("asBoolean", _args)
return await _ctx.execute(bool)
[docs]
async def as_integer(self) -> int:
"""Decode an integer from json
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("asInteger", _args)
return await _ctx.execute(int)
[docs]
async def as_string(self) -> str:
"""Decode a string from json
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("asString", _args)
return await _ctx.execute(str)
[docs]
async def contents(
self,
*,
pretty: bool | None = False,
indent: str | None = " ",
) -> JSON:
"""Return the value encoded as json
Parameters
----------
pretty:
Pretty-print
indent:
Optional line prefix
Returns
-------
JSON
An arbitrary JSON-encoded value.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("pretty", pretty, False),
Arg("indent", indent, " "),
]
_ctx = self._select("contents", _args)
return await _ctx.execute(JSON)
[docs]
def field(self, path: list[str]) -> Self:
"""Lookup the field at the given path, and return its value.
Parameters
----------
path:
Path of the field to lookup, encoded as an array of field names
"""
_args = [
Arg("path", path),
]
_ctx = self._select("field", _args)
return JSONValue(_ctx)
[docs]
async def fields(self) -> list[str]:
"""List fields of the encoded object
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("fields", _args)
return await _ctx.execute(list[str])
[docs]
async def id(self) -> str:
"""A unique identifier for this JSONValue.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def new_boolean(self, value: bool) -> Self:
"""Encode a boolean to json
Parameters
----------
value:
New boolean value
"""
_args = [
Arg("value", value),
]
_ctx = self._select("newBoolean", _args)
return JSONValue(_ctx)
[docs]
def new_integer(self, value: int) -> Self:
"""Encode an integer to json
Parameters
----------
value:
New integer value
"""
_args = [
Arg("value", value),
]
_ctx = self._select("newInteger", _args)
return JSONValue(_ctx)
[docs]
def new_string(self, value: str) -> Self:
"""Encode a string to json
Parameters
----------
value:
New string value
"""
_args = [
Arg("value", value),
]
_ctx = self._select("newString", _args)
return JSONValue(_ctx)
[docs]
def with_contents(self, contents: JSON) -> Self:
"""Return a new json value, decoded from the given content
Parameters
----------
contents:
New JSON-encoded contents
"""
_args = [
Arg("contents", contents),
]
_ctx = self._select("withContents", _args)
return JSONValue(_ctx)
[docs]
def with_field(self, path: list[str], value: Self) -> Self:
"""Set a new field at the given path
Parameters
----------
path:
Path of the field to set, encoded as an array of field names
value:
The new value of the field
"""
_args = [
Arg("path", path),
Arg("value", value),
]
_ctx = self._select("withField", _args)
return JSONValue(_ctx)
[docs]
def with_(self, cb: Callable[["JSONValue"], "JSONValue"]) -> "JSONValue":
"""Call the provided callable with current JSONValue.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class LLM(Type):
[docs]
def attempt(self, number: int) -> Self:
"""create a branch in the LLM's history"""
_args = [
Arg("number", number),
]
_ctx = self._select("attempt", _args)
return LLM(_ctx)
[docs]
def bind_result(self, name: str) -> Binding:
"""returns the type of the current state"""
_args = [
Arg("name", name),
]
_ctx = self._select("bindResult", _args)
return Binding(_ctx)
[docs]
def env(self) -> Env:
"""return the LLM's current environment"""
_args: list[Arg] = []
_ctx = self._select("env", _args)
return Env(_ctx)
[docs]
async def has_prompt(self) -> bool:
"""Indicates whether there are any queued prompts or tool results to send
to the model
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("hasPrompt", _args)
return await _ctx.execute(bool)
[docs]
async def history(self) -> list[str]:
"""return the llm message history
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("history", _args)
return await _ctx.execute(list[str])
[docs]
async def history_json(self) -> JSON:
"""return the raw llm message history as json
Returns
-------
JSON
An arbitrary JSON-encoded value.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("historyJSON", _args)
return await _ctx.execute(JSON)
[docs]
async def id(self) -> str:
"""A unique identifier for this LLM.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def last_reply(self) -> str:
"""return the last llm reply from the history
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("lastReply", _args)
return await _ctx.execute(str)
[docs]
def loop(self) -> Self:
"""Submit the queued prompt, evaluate any tool calls, queue their
results, and keep going until the model ends its turn
"""
_args: list[Arg] = []
_ctx = self._select("loop", _args)
return LLM(_ctx)
[docs]
async def model(self) -> str:
"""return the model used by the llm
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("model", _args)
return await _ctx.execute(str)
[docs]
async def provider(self) -> str:
"""return the provider used by the llm
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("provider", _args)
return await _ctx.execute(str)
[docs]
async def step(self) -> Self:
"""Submit the queued prompt or tool call results, evaluate any tool
calls, and queue their results
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "step", _args)
[docs]
async def sync(self) -> Self:
"""synchronize LLM state
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def token_usage(self) -> "LLMTokenUsage":
"""returns the token usage of the current state"""
_args: list[Arg] = []
_ctx = self._select("tokenUsage", _args)
return LLMTokenUsage(_ctx)
[docs]
def with_blocked_function(self, type_name: str, function: str) -> Self:
"""Return a new LLM with the specified function no longer exposed as a
tool
Parameters
----------
type_name:
The type name whose function will be blocked
function:
The function to block
Will be converted to lowerCamelCase if necessary.
"""
_args = [
Arg("typeName", type_name),
Arg("function", function),
]
_ctx = self._select("withBlockedFunction", _args)
return LLM(_ctx)
[docs]
def with_env(self, env: Env) -> Self:
"""allow the LLM to interact with an environment via MCP"""
_args = [
Arg("env", env),
]
_ctx = self._select("withEnv", _args)
return LLM(_ctx)
[docs]
def with_mcp_server(self, name: str, service: "Service") -> Self:
"""Add an external MCP server to the LLM
Parameters
----------
name:
The name of the MCP server
service:
The MCP service to run and communicate with over stdio
"""
_args = [
Arg("name", name),
Arg("service", service),
]
_ctx = self._select("withMCPServer", _args)
return LLM(_ctx)
[docs]
def with_model(self, model: str) -> Self:
"""swap out the llm model
Parameters
----------
model:
The model to use
"""
_args = [
Arg("model", model),
]
_ctx = self._select("withModel", _args)
return LLM(_ctx)
[docs]
def with_prompt(self, prompt: str) -> Self:
"""append a prompt to the llm context
Parameters
----------
prompt:
The prompt to send
"""
_args = [
Arg("prompt", prompt),
]
_ctx = self._select("withPrompt", _args)
return LLM(_ctx)
[docs]
def with_prompt_file(self, file: File) -> Self:
"""append the contents of a file to the llm context
Parameters
----------
file:
The file to read the prompt from
"""
_args = [
Arg("file", file),
]
_ctx = self._select("withPromptFile", _args)
return LLM(_ctx)
[docs]
def with_system_prompt(self, prompt: str) -> Self:
"""Add a system prompt to the LLM's environment
Parameters
----------
prompt:
The system prompt to send
"""
_args = [
Arg("prompt", prompt),
]
_ctx = self._select("withSystemPrompt", _args)
return LLM(_ctx)
[docs]
def without_default_system_prompt(self) -> Self:
"""Disable the default system prompt"""
_args: list[Arg] = []
_ctx = self._select("withoutDefaultSystemPrompt", _args)
return LLM(_ctx)
[docs]
def without_message_history(self) -> Self:
"""Clear the message history, leaving only the system prompts"""
_args: list[Arg] = []
_ctx = self._select("withoutMessageHistory", _args)
return LLM(_ctx)
[docs]
def without_system_prompts(self) -> Self:
"""Clear the system prompts, leaving only the default system prompt"""
_args: list[Arg] = []
_ctx = self._select("withoutSystemPrompts", _args)
return LLM(_ctx)
[docs]
def with_(self, cb: Callable[["LLM"], "LLM"]) -> "LLM":
"""Call the provided callable with current LLM.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class LLMTokenUsage(Type):
[docs]
async def cached_token_reads(self) -> int:
"""Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("cachedTokenReads", _args)
return await _ctx.execute(int)
[docs]
async def cached_token_writes(self) -> int:
"""Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("cachedTokenWrites", _args)
return await _ctx.execute(int)
[docs]
async def id(self) -> str:
"""A unique identifier for this LLMTokenUsage.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def output_tokens(self) -> int:
"""Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("outputTokens", _args)
return await _ctx.execute(int)
[docs]
async def total_tokens(self) -> int:
"""Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("totalTokens", _args)
return await _ctx.execute(int)
@typecheck
class Label(Type):
"""A simple key value object that represents a label."""
[docs]
async def id(self) -> str:
"""A unique identifier for this Label.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The label name.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def value(self) -> str:
"""The label value.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
@typecheck
class ListTypeDef(Type):
"""A definition of a list type in a Module."""
[docs]
def element_type_def(self) -> "TypeDef":
"""The type of the elements in the list."""
_args: list[Arg] = []
_ctx = self._select("elementTypeDef", _args)
return TypeDef(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this ListTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class Module(Type):
"""A Dagger module."""
[docs]
def check(self, name: str) -> Check:
"""Return the check defined by the module with the given name. Must match
to exactly one check.
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
name:
The name of the check to retrieve
"""
_args = [
Arg("name", name),
]
_ctx = self._select("check", _args)
return Check(_ctx)
[docs]
def checks(
self,
*,
include: list[str] | None = None,
no_generate: bool | None = None,
) -> CheckGroup:
"""Return all checks defined by the module
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
include:
Only include checks matching the specified patterns
no_generate:
When true, only return annotated check functions; exclude
generate-as-checks
"""
_args = [
Arg("include", include, None),
Arg("noGenerate", no_generate, None),
]
_ctx = self._select("checks", _args)
return CheckGroup(_ctx)
[docs]
async def dependencies(self) -> list["Module"]:
"""The dependencies of the module."""
_args: list[Arg] = []
_ctx = self._select("dependencies", _args)
return await _ctx.execute_object_list(Module)
[docs]
async def description(self) -> str:
"""The doc string of the module, if any
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def enums(self) -> list["TypeDef"]:
"""Enumerations served by this module."""
_args: list[Arg] = []
_ctx = self._select("enums", _args)
return await _ctx.execute_object_list(TypeDef)
[docs]
def generated_context_directory(self) -> Directory:
"""The generated files and directories made on top of the module source's
context directory.
"""
_args: list[Arg] = []
_ctx = self._select("generatedContextDirectory", _args)
return Directory(_ctx)
[docs]
def generator(self, name: str) -> Generator:
"""Return the generator defined by the module with the given name. Must
match to exactly one generator.
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
name:
The name of the generator to retrieve
"""
_args = [
Arg("name", name),
]
_ctx = self._select("generator", _args)
return Generator(_ctx)
[docs]
def generators(
self,
*,
include: list[str] | None = None,
) -> GeneratorGroup:
"""Return all generators defined by the module
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
include:
Only include generators matching the specified patterns
"""
_args = [
Arg("include", include, None),
]
_ctx = self._select("generators", _args)
return GeneratorGroup(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this Module.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def interfaces(self) -> list["TypeDef"]:
"""Interfaces served by this module."""
_args: list[Arg] = []
_ctx = self._select("interfaces", _args)
return await _ctx.execute_object_list(TypeDef)
[docs]
def introspection_schema_json(self) -> File:
"""The introspection schema JSON file for this module.
This file represents the schema visible to the module's source code,
including all core types and those from the dependencies.
Note: this is in the context of a module, so some core types may be
hidden.
"""
_args: list[Arg] = []
_ctx = self._select("introspectionSchemaJSON", _args)
return File(_ctx)
[docs]
async def name(self) -> str:
"""The name of the module
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def objects(self) -> list["TypeDef"]:
"""Objects served by this module."""
_args: list[Arg] = []
_ctx = self._select("objects", _args)
return await _ctx.execute_object_list(TypeDef)
[docs]
def runtime(self) -> Container:
"""The container that runs the module's entrypoint. It will fail to
execute if the module doesn't compile.
"""
_args: list[Arg] = []
_ctx = self._select("runtime", _args)
return Container(_ctx)
[docs]
def sdk(self) -> "SDKConfig":
"""The SDK config used by this module."""
_args: list[Arg] = []
_ctx = self._select("sdk", _args)
return SDKConfig(_ctx)
[docs]
async def serve(
self,
*,
include_dependencies: bool | None = None,
entrypoint: bool | None = None,
) -> Void | None:
"""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.
Parameters
----------
include_dependencies:
Expose the dependencies of this module to the client
entrypoint:
Install the module as the entrypoint, promoting its main-object
methods onto the Query root
Returns
-------
Void | None
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("includeDependencies", include_dependencies, None),
Arg("entrypoint", entrypoint, None),
]
_ctx = self._select("serve", _args)
await _ctx.execute()
[docs]
def services(
self,
*,
include: list[str] | None = None,
) -> "UpGroup":
"""Return all services defined by the module
.. caution::
Experimental: This API is highly experimental and may be removed
or replaced entirely.
Parameters
----------
include:
Only include services matching the specified patterns
"""
_args = [
Arg("include", include, None),
]
_ctx = self._select("services", _args)
return UpGroup(_ctx)
[docs]
def source(self) -> "ModuleSource":
"""The source for the module."""
_args: list[Arg] = []
_ctx = self._select("source", _args)
return ModuleSource(_ctx)
[docs]
async def sync(self) -> Self:
"""Forces evaluation of the module, including any loading into the engine
and associated validation.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def user_defaults(self) -> EnvFile:
"""User-defined default values, loaded from local .env files."""
_args: list[Arg] = []
_ctx = self._select("userDefaults", _args)
return EnvFile(_ctx)
[docs]
def with_description(self, description: str) -> Self:
"""Retrieves the module with the given description
Parameters
----------
description:
The description to set
"""
_args = [
Arg("description", description),
]
_ctx = self._select("withDescription", _args)
return Module(_ctx)
[docs]
def with_enum(self, enum: "TypeDef") -> Self:
"""This module plus the given Enum type and associated values"""
_args = [
Arg("enum", enum),
]
_ctx = self._select("withEnum", _args)
return Module(_ctx)
[docs]
def with_interface(self, iface: "TypeDef") -> Self:
"""This module plus the given Interface type and associated functions"""
_args = [
Arg("iface", iface),
]
_ctx = self._select("withInterface", _args)
return Module(_ctx)
[docs]
def with_object(self, object: "TypeDef") -> Self:
"""This module plus the given Object type and associated functions."""
_args = [
Arg("object", object),
]
_ctx = self._select("withObject", _args)
return Module(_ctx)
[docs]
def with_(self, cb: Callable[["Module"], "Module"]) -> "Module":
"""Call the provided callable with current Module.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class ModuleConfigClient(Type):
"""The client generated for the module."""
[docs]
async def directory(self) -> str:
"""The directory the client is generated in.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("directory", _args)
return await _ctx.execute(str)
[docs]
async def generator(self) -> str:
"""The generator to use
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("generator", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this ModuleConfigClient.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class ModuleSource(Type):
"""The source needed to load and run a module, along with any metadata
about the source such as versions/urls/etc."""
[docs]
def as_module(self) -> Module:
"""Load the source as a module. If this is a local source, the parent
directory must have been provided during module source creation
"""
_args: list[Arg] = []
_ctx = self._select("asModule", _args)
return Module(_ctx)
[docs]
async def as_string(self) -> str:
"""A human readable ref string representation of this module source.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("asString", _args)
return await _ctx.execute(str)
[docs]
def blueprint(self) -> Self:
"""The blueprint referenced by the module source."""
_args: list[Arg] = []
_ctx = self._select("blueprint", _args)
return ModuleSource(_ctx)
[docs]
async def clone_ref(self) -> str:
"""The ref to clone the root of the git repo from. Only valid for git
sources.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("cloneRef", _args)
return await _ctx.execute(str)
[docs]
async def commit(self) -> str:
"""The resolved commit of the git repo this source points to.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("commit", _args)
return await _ctx.execute(str)
[docs]
async def config_clients(self) -> list[ModuleConfigClient]:
"""The clients generated for the module."""
_args: list[Arg] = []
_ctx = self._select("configClients", _args)
return await _ctx.execute_object_list(ModuleConfigClient)
[docs]
async def config_exists(self) -> bool:
"""Whether an existing dagger.json for the module was found.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("configExists", _args)
return await _ctx.execute(bool)
[docs]
def context_directory(self) -> Directory:
"""The full directory loaded for the module source, including the source
code as a subdirectory.
"""
_args: list[Arg] = []
_ctx = self._select("contextDirectory", _args)
return Directory(_ctx)
[docs]
async def dependencies(self) -> list["ModuleSource"]:
"""The dependencies of the module source."""
_args: list[Arg] = []
_ctx = self._select("dependencies", _args)
return await _ctx.execute_object_list(ModuleSource)
[docs]
async def digest(self) -> str:
"""A content-hash of the module source. Module sources with the same
digest will output the same generated context and convert into the
same module instance.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("digest", _args)
return await _ctx.execute(str)
[docs]
def directory(self, path: str) -> Directory:
"""The directory containing the module configuration and source code
(source code may be in a subdir).
Parameters
----------
path:
A subpath from the source directory to select.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
async def engine_version(self) -> str:
"""The engine version of the module.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("engineVersion", _args)
return await _ctx.execute(str)
[docs]
def generated_context_changeset(self) -> Changeset:
"""The generated files and directories made on top of the module source's
context directory, returned as a Changeset.
"""
_args: list[Arg] = []
_ctx = self._select("generatedContextChangeset", _args)
return Changeset(_ctx)
[docs]
def generated_context_directory(self) -> Directory:
"""The generated files and directories made on top of the module source's
context directory.
"""
_args: list[Arg] = []
_ctx = self._select("generatedContextDirectory", _args)
return Directory(_ctx)
[docs]
async def html_repo_url(self) -> str:
"""The URL to access the web view of the repository (e.g., GitHub,
GitLab, Bitbucket).
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("htmlRepoURL", _args)
return await _ctx.execute(str)
[docs]
async def html_url(self) -> str:
"""The URL to the source's git repo in a web browser. Only valid for git
sources.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("htmlURL", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this ModuleSource.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def introspection_schema_json(self) -> File:
"""The introspection schema JSON file for this module source.
This file represents the schema visible to the module's source code,
including all core types and those from the dependencies.
Note: this is in the context of a module, so some core types may be
hidden.
"""
_args: list[Arg] = []
_ctx = self._select("introspectionSchemaJSON", _args)
return File(_ctx)
[docs]
async def kind(self) -> ModuleSourceKind:
"""The kind of module source (currently local, git or dir).
Returns
-------
ModuleSourceKind
The kind of module source.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("kind", _args)
return await _ctx.execute(ModuleSourceKind)
[docs]
async def local_context_directory_path(self) -> str:
"""The full absolute path to the context directory on the caller's host
filesystem that this module source is loaded from. Only valid for
local module sources.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("localContextDirectoryPath", _args)
return await _ctx.execute(str)
[docs]
async def module_name(self) -> str:
"""The name of the module, including any setting via the withName API.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("moduleName", _args)
return await _ctx.execute(str)
[docs]
async def module_original_name(self) -> str:
"""The original name of the module as read from the module's dagger.json
(or set for the first time with the withName API).
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("moduleOriginalName", _args)
return await _ctx.execute(str)
[docs]
async def original_subpath(self) -> str:
"""The original subpath used when instantiating this module source,
relative to the context directory.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("originalSubpath", _args)
return await _ctx.execute(str)
[docs]
async def pin(self) -> str:
"""The pinned version of this module source.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("pin", _args)
return await _ctx.execute(str)
[docs]
async def repo_root_path(self) -> str:
"""The import path corresponding to the root of the git repo this source
points to. Only valid for git sources.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("repoRootPath", _args)
return await _ctx.execute(str)
[docs]
def sdk(self) -> "SDKConfig":
"""The SDK configuration of the module."""
_args: list[Arg] = []
_ctx = self._select("sdk", _args)
return SDKConfig(_ctx)
[docs]
async def source_root_subpath(self) -> str:
"""The path, relative to the context directory, that contains the
module's dagger.json.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceRootSubpath", _args)
return await _ctx.execute(str)
[docs]
async def source_subpath(self) -> str:
"""The path to the directory containing the module's source code,
relative to the context directory.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceSubpath", _args)
return await _ctx.execute(str)
[docs]
async def sync(self) -> Self:
"""Forces evaluation of the module source, including any loading into the
engine and associated validation.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def user_defaults(self) -> EnvFile:
"""User-defined defaults read from local .env files"""
_args: list[Arg] = []
_ctx = self._select("userDefaults", _args)
return EnvFile(_ctx)
[docs]
async def version(self) -> str:
"""The specified version of the git repo this source points to.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("version", _args)
return await _ctx.execute(str)
[docs]
def with_blueprint(self, blueprint: Self) -> Self:
"""Set a blueprint for the module source.
Parameters
----------
blueprint:
The blueprint module to set.
"""
_args = [
Arg("blueprint", blueprint),
]
_ctx = self._select("withBlueprint", _args)
return ModuleSource(_ctx)
[docs]
def with_client(self, generator: str, output_dir: str) -> Self:
"""Update the module source with a new client to generate.
Parameters
----------
generator:
The generator to use
output_dir:
The output directory for the generated client.
"""
_args = [
Arg("generator", generator),
Arg("outputDir", output_dir),
]
_ctx = self._select("withClient", _args)
return ModuleSource(_ctx)
[docs]
def with_dependencies(self, dependencies: list["ModuleSource"]) -> Self:
"""Append the provided dependencies to the module source's dependency
list.
Parameters
----------
dependencies:
The dependencies to append.
"""
_args = [
Arg("dependencies", dependencies),
]
_ctx = self._select("withDependencies", _args)
return ModuleSource(_ctx)
[docs]
def with_engine_version(self, version: str) -> Self:
"""Upgrade the engine version of the module to the given value.
Parameters
----------
version:
The engine version to upgrade to.
"""
_args = [
Arg("version", version),
]
_ctx = self._select("withEngineVersion", _args)
return ModuleSource(_ctx)
[docs]
def with_experimental_features(
self,
features: list[ModuleSourceExperimentalFeature],
) -> Self:
"""Enable the experimental features for the module source.
Parameters
----------
features:
The experimental features to enable.
"""
_args = [
Arg("features", features),
]
_ctx = self._select("withExperimentalFeatures", _args)
return ModuleSource(_ctx)
[docs]
def with_includes(self, patterns: list[str]) -> Self:
"""Update the module source with additional include patterns for
files+directories from its context that are required for building it
Parameters
----------
patterns:
The new additional include patterns.
"""
_args = [
Arg("patterns", patterns),
]
_ctx = self._select("withIncludes", _args)
return ModuleSource(_ctx)
[docs]
def with_name(self, name: str) -> Self:
"""Update the module source with a new name.
Parameters
----------
name:
The name to set.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("withName", _args)
return ModuleSource(_ctx)
[docs]
def with_sdk(self, source: str) -> Self:
"""Update the module source with a new SDK.
Parameters
----------
source:
The SDK source to set.
"""
_args = [
Arg("source", source),
]
_ctx = self._select("withSDK", _args)
return ModuleSource(_ctx)
[docs]
def with_source_subpath(self, path: str) -> Self:
"""Update the module source with a new source subpath.
Parameters
----------
path:
The path to set as the source subpath. Must be relative to the
module source's source root directory.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("withSourceSubpath", _args)
return ModuleSource(_ctx)
[docs]
def with_update_blueprint(self) -> Self:
"""Update the blueprint module to the latest version."""
_args: list[Arg] = []
_ctx = self._select("withUpdateBlueprint", _args)
return ModuleSource(_ctx)
[docs]
def with_update_dependencies(self, dependencies: list[str]) -> Self:
"""Update one or more module dependencies.
Parameters
----------
dependencies:
The dependencies to update.
"""
_args = [
Arg("dependencies", dependencies),
]
_ctx = self._select("withUpdateDependencies", _args)
return ModuleSource(_ctx)
[docs]
def with_updated_clients(self, clients: list[str]) -> Self:
"""Update one or more clients.
Parameters
----------
clients:
The clients to update
"""
_args = [
Arg("clients", clients),
]
_ctx = self._select("withUpdatedClients", _args)
return ModuleSource(_ctx)
[docs]
def without_blueprint(self) -> Self:
"""Remove the current blueprint from the module source."""
_args: list[Arg] = []
_ctx = self._select("withoutBlueprint", _args)
return ModuleSource(_ctx)
[docs]
def without_client(self, path: str) -> Self:
"""Remove a client from the module source.
Parameters
----------
path:
The path of the client to remove.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutClient", _args)
return ModuleSource(_ctx)
[docs]
def without_dependencies(self, dependencies: list[str]) -> Self:
"""Remove the provided dependencies from the module source's dependency
list.
Parameters
----------
dependencies:
The dependencies to remove.
"""
_args = [
Arg("dependencies", dependencies),
]
_ctx = self._select("withoutDependencies", _args)
return ModuleSource(_ctx)
[docs]
def without_experimental_features(
self,
features: list[ModuleSourceExperimentalFeature],
) -> Self:
"""Disable experimental features for the module source.
Parameters
----------
features:
The experimental features to disable.
"""
_args = [
Arg("features", features),
]
_ctx = self._select("withoutExperimentalFeatures", _args)
return ModuleSource(_ctx)
[docs]
def with_(self, cb: Callable[["ModuleSource"], "ModuleSource"]) -> "ModuleSource":
"""Call the provided callable with current ModuleSource.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class ObjectTypeDef(Type):
"""A definition of a custom object defined in a Module."""
[docs]
def constructor(self) -> Function:
"""The function used to construct new instances of this object, if any."""
_args: list[Arg] = []
_ctx = self._select("constructor", _args)
return Function(_ctx)
[docs]
async def deprecated(self) -> str | None:
"""The reason this enum member is deprecated, if any.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("deprecated", _args)
return await _ctx.execute(str | None)
[docs]
async def description(self) -> str:
"""The doc string for the object, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def fields(self) -> list[FieldTypeDef]:
"""Static fields defined on this object, if any."""
_args: list[Arg] = []
_ctx = self._select("fields", _args)
return await _ctx.execute_object_list(FieldTypeDef)
[docs]
async def functions(self) -> list[Function]:
"""Functions defined on this object, if any."""
_args: list[Arg] = []
_ctx = self._select("functions", _args)
return await _ctx.execute_object_list(Function)
[docs]
async def id(self) -> str:
"""A unique identifier for this ObjectTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the object.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def source_map(self) -> "SourceMap":
"""The location of this object declaration."""
_args: list[Arg] = []
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
async def source_module_name(self) -> str:
"""If this ObjectTypeDef is associated with a Module, the name of the
module. Unset otherwise.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceModuleName", _args)
return await _ctx.execute(str)
@typecheck
class Port(Type):
"""A port exposed by a container."""
[docs]
async def description(self) -> str | None:
"""The port description.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str | None)
[docs]
async def experimental_skip_healthcheck(self) -> bool:
"""Skip the health check when run as a service.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("experimentalSkipHealthcheck", _args)
return await _ctx.execute(bool)
[docs]
async def id(self) -> str:
"""A unique identifier for this Port.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def port(self) -> int:
"""The port number.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("port", _args)
return await _ctx.execute(int)
[docs]
async def protocol(self) -> NetworkProtocol:
"""The transport layer protocol.
Returns
-------
NetworkProtocol
Transport layer network protocol associated to a port.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("protocol", _args)
return await _ctx.execute(NetworkProtocol)
@typecheck
class Query(Root):
"""The root of the DAG."""
[docs]
def address(self, value: str) -> Address:
"""initialize an address to load directories, containers, secrets or
other object types.
"""
_args = [
Arg("value", value),
]
_ctx = self._select("address", _args)
return Address(_ctx)
[docs]
def cache_volume(
self,
key: str,
*,
source: Directory | None = None,
sharing: CacheSharingMode | None = CacheSharingMode.SHARED,
owner: str | None = "",
) -> CacheVolume:
"""Constructs a cache volume for a given cache key.
Parameters
----------
key:
A string identifier to target this cache volume (e.g., "modules-
cache").
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 cache volume root.
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.
"""
_args = [
Arg("key", key),
Arg("source", source, None),
Arg("sharing", sharing, CacheSharingMode.SHARED),
Arg("owner", owner, ""),
]
_ctx = self._select("cacheVolume", _args)
return CacheVolume(_ctx)
[docs]
def changeset(self) -> Changeset:
"""Creates an empty changeset"""
_args: list[Arg] = []
_ctx = self._select("changeset", _args)
return Changeset(_ctx)
[docs]
def cloud(self) -> Cloud:
"""Dagger Cloud configuration and state"""
_args: list[Arg] = []
_ctx = self._select("cloud", _args)
return Cloud(_ctx)
[docs]
def container(
self,
*,
platform: Platform | None = None,
) -> Container:
"""Creates a scratch container, with no image or metadata.
To pull an image, follow up with the "from" function.
Parameters
----------
platform:
Platform to initialize the container with. Defaults to the native
platform of the current engine
"""
_args = [
Arg("platform", platform, None),
]
_ctx = self._select("container", _args)
return Container(_ctx)
[docs]
def current_env(self) -> Env:
"""Returns the current environment
When called from a function invoked via an LLM tool call, this will be
the LLM's current environment, including any modifications made
through calling tools. Env values returned by functions become the new
environment for subsequent calls, and Changeset values returned by
functions are applied to the environment's workspace.
When called from a module function outside of an LLM, this returns an
Env with the current module installed, and with the current module's
source directory as its workspace.
.. caution::
Experimental: Programmatic env access is speculative and might be
replaced.
"""
_args: list[Arg] = []
_ctx = self._select("currentEnv", _args)
return Env(_ctx)
[docs]
def current_function_call(self) -> FunctionCall:
"""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.
"""
_args: list[Arg] = []
_ctx = self._select("currentFunctionCall", _args)
return FunctionCall(_ctx)
[docs]
def current_module(self) -> CurrentModule:
"""The module currently being served in the session, if any."""
_args: list[Arg] = []
_ctx = self._select("currentModule", _args)
return CurrentModule(_ctx)
[docs]
async def current_type_defs(
self,
*,
return_all_types: bool | None = False,
hide_core: bool | None = None,
) -> list["TypeDef"]:
"""The TypeDef representations of the objects currently being served in
the session.
Parameters
----------
return_all_types:
Return the full referenced typedef closure instead of only top-
level served typedefs.
hide_core:
Strip core API functions from the Query type, leaving only module-
sourced functions (constructors, entrypoint proxies, etc.).
Core types (Container, Directory, etc.) are kept so return types
and method chaining still work.
"""
_args = [
Arg("returnAllTypes", return_all_types, False),
Arg("hideCore", hide_core, None),
]
_ctx = self._select("currentTypeDefs", _args)
return await _ctx.execute_object_list(TypeDef)
[docs]
def current_workspace(self) -> "Workspace":
"""Detect and return the current workspace.
.. caution::
Experimental: Highly experimental API extracted from a more
ambitious workspace implementation.
"""
_args: list[Arg] = []
_ctx = self._select("currentWorkspace", _args)
return Workspace(_ctx)
[docs]
def directory(self) -> Directory:
"""Creates an empty directory."""
_args: list[Arg] = []
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
def engine(self) -> Engine:
"""The Dagger engine container configuration and state"""
_args: list[Arg] = []
_ctx = self._select("engine", _args)
return Engine(_ctx)
[docs]
def env(
self,
*,
privileged: bool | None = False,
writable: bool | None = False,
) -> Env:
"""Initializes a new environment
.. caution::
Experimental: Environments are not yet stabilized
Parameters
----------
privileged:
Give the environment the same privileges as the caller: core API
including host access, current module, and dependencies
writable:
Allow new outputs to be declared and saved in the environment
"""
_args = [
Arg("privileged", privileged, False),
Arg("writable", writable, False),
]
_ctx = self._select("env", _args)
return Env(_ctx)
[docs]
def env_file(self, *, expand: bool | None = None) -> EnvFile:
"""Initialize an environment file
Parameters
----------
expand:
Replace "${VAR}" or "$VAR" with the value of other vars
.. deprecated:: Variable expansion is now enabled by default
"""
_args = [
Arg("expand", expand, None),
]
_ctx = self._select("envFile", _args)
return EnvFile(_ctx)
[docs]
def error(self, message: str) -> Error:
"""Create a new error.
Parameters
----------
message:
A brief description of the error.
"""
_args = [
Arg("message", message),
]
_ctx = self._select("error", _args)
return Error(_ctx)
[docs]
def file(
self,
name: str,
contents: str,
*,
permissions: int | None = 420,
) -> File:
"""Creates a file with the specified contents.
Parameters
----------
name:
Name of the new file. Example: "foo.txt"
contents:
Contents of the new file. Example: "Hello world!"
permissions:
Permissions of the new file. Example: 0600
"""
_args = [
Arg("name", name),
Arg("contents", contents),
Arg("permissions", permissions, 420),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs]
def function(self, name: str, return_type: "TypeDef") -> Function:
"""Creates a function.
Parameters
----------
name:
Name of the function, in its original format from the
implementation language.
return_type:
Return type of the function.
"""
_args = [
Arg("name", name),
Arg("returnType", return_type),
]
_ctx = self._select("function", _args)
return Function(_ctx)
[docs]
def generated_code(self, code: Directory) -> GeneratedCode:
"""Create a code generation result, given a directory containing the
generated code.
"""
_args = [
Arg("code", code),
]
_ctx = self._select("generatedCode", _args)
return GeneratedCode(_ctx)
[docs]
def git(
self,
url: str,
*,
keep_git_dir: bool | None = True,
ssh_known_hosts: str | None = "",
ssh_auth_socket: "Socket | None" = None,
http_auth_username: str | None = "",
http_auth_token: "Secret | None" = None,
http_auth_header: "Secret | None" = None,
experimental_service_host: "Service | None" = None,
) -> GitRepository:
"""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:
DEPRECATED: Set to true to keep .git directory.
.. deprecated:: Set to true to keep .git directory.
ssh_known_hosts:
Set SSH known hosts
ssh_auth_socket:
Set SSH auth socket
http_auth_username:
Username used to populate the password during basic HTTP
Authorization
http_auth_token:
Secret used to populate the password during basic HTTP
Authorization
http_auth_header:
Secret used to populate the Authorization HTTP header
experimental_service_host:
A service which must be started before the repo is fetched.
"""
_args = [
Arg("url", url),
Arg("keepGitDir", keep_git_dir, True),
Arg("sshKnownHosts", ssh_known_hosts, ""),
Arg("sshAuthSocket", ssh_auth_socket, None),
Arg("httpAuthUsername", http_auth_username, ""),
Arg("httpAuthToken", http_auth_token, None),
Arg("httpAuthHeader", http_auth_header, None),
Arg("experimentalServiceHost", experimental_service_host, None),
]
_ctx = self._select("git", _args)
return GitRepository(_ctx)
[docs]
def host(self) -> Host:
"""Queries the host environment."""
_args: list[Arg] = []
_ctx = self._select("host", _args)
return Host(_ctx)
[docs]
def http(
self,
url: str,
*,
name: str | None = None,
permissions: int | None = None,
checksum: str | None = None,
auth_header: "Secret | None" = None,
experimental_service_host: "Service | None" = None,
) -> File:
"""Returns a file containing an http remote url content.
Parameters
----------
url:
HTTP url to get the content from (e.g., "https://docs.dagger.io").
name:
File name to use for the file. Defaults to the last part of the
URL.
permissions:
Permissions to set on the file.
checksum:
Expected digest of the downloaded content (e.g., "sha256:...").
auth_header:
Secret used to populate the Authorization HTTP header
experimental_service_host:
A service which must be started before the URL is fetched.
"""
_args = [
Arg("url", url),
Arg("name", name, None),
Arg("permissions", permissions, None),
Arg("checksum", checksum, None),
Arg("authHeader", auth_header, None),
Arg("experimentalServiceHost", experimental_service_host, None),
]
_ctx = self._select("http", _args)
return File(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this Query.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
def json(self) -> JSONValue:
"""Initialize a JSON value"""
_args: list[Arg] = []
_ctx = self._select("json", _args)
return JSONValue(_ctx)
[docs]
def llm(
self,
*,
model: str | None = None,
max_api_calls: int | None = None,
) -> LLM:
"""Initialize a Large Language Model (LLM)
.. caution::
Experimental: LLM support is not yet stabilized
Parameters
----------
model:
Model to use
max_api_calls:
Cap the number of API calls for this LLM
"""
_args = [
Arg("model", model, None),
Arg("maxAPICalls", max_api_calls, None),
]
_ctx = self._select("llm", _args)
return LLM(_ctx)
[docs]
def load_address_from_id(self, id: AddressID) -> Address:
"""Load a Address from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadAddressFromID", _args)
return Address(_ctx)
[docs]
def load_binding_from_id(self, id: BindingID) -> Binding:
"""Load a Binding from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadBindingFromID", _args)
return Binding(_ctx)
[docs]
def load_cache_volume_from_id(self, id: CacheVolumeID) -> CacheVolume:
"""Load a CacheVolume from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadCacheVolumeFromID", _args)
return CacheVolume(_ctx)
[docs]
def load_changeset_from_id(self, id: ChangesetID) -> Changeset:
"""Load a Changeset from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadChangesetFromID", _args)
return Changeset(_ctx)
[docs]
def load_check_from_id(self, id: CheckID) -> Check:
"""Load a Check from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadCheckFromID", _args)
return Check(_ctx)
[docs]
def load_check_group_from_id(self, id: CheckGroupID) -> CheckGroup:
"""Load a CheckGroup from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadCheckGroupFromID", _args)
return CheckGroup(_ctx)
[docs]
def load_client_filesync_mirror_from_id(
self, id: ClientFilesyncMirrorID
) -> ClientFilesyncMirror:
"""Load a ClientFilesyncMirror from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadClientFilesyncMirrorFromID", _args)
return ClientFilesyncMirror(_ctx)
[docs]
def load_cloud_from_id(self, id: CloudID) -> Cloud:
"""Load a Cloud from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadCloudFromID", _args)
return Cloud(_ctx)
[docs]
def load_container_from_id(self, id: ContainerID) -> Container:
"""Load a Container from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadContainerFromID", _args)
return Container(_ctx)
[docs]
def load_current_module_from_id(self, id: CurrentModuleID) -> CurrentModule:
"""Load a CurrentModule from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadCurrentModuleFromID", _args)
return CurrentModule(_ctx)
[docs]
def load_diff_stat_from_id(self, id: DiffStatID) -> DiffStat:
"""Load a DiffStat from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadDiffStatFromID", _args)
return DiffStat(_ctx)
[docs]
def load_directory_from_id(self, id: DirectoryID) -> Directory:
"""Load a Directory from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadDirectoryFromID", _args)
return Directory(_ctx)
[docs]
def load_engine_cache_entry_from_id(
self, id: EngineCacheEntryID
) -> EngineCacheEntry:
"""Load a EngineCacheEntry from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEngineCacheEntryFromID", _args)
return EngineCacheEntry(_ctx)
[docs]
def load_engine_cache_entry_set_from_id(
self, id: EngineCacheEntrySetID
) -> EngineCacheEntrySet:
"""Load a EngineCacheEntrySet from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEngineCacheEntrySetFromID", _args)
return EngineCacheEntrySet(_ctx)
[docs]
def load_engine_cache_from_id(self, id: EngineCacheID) -> EngineCache:
"""Load a EngineCache from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEngineCacheFromID", _args)
return EngineCache(_ctx)
[docs]
def load_engine_from_id(self, id: EngineID) -> Engine:
"""Load a Engine from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEngineFromID", _args)
return Engine(_ctx)
[docs]
def load_enum_type_def_from_id(self, id: EnumTypeDefID) -> EnumTypeDef:
"""Load a EnumTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEnumTypeDefFromID", _args)
return EnumTypeDef(_ctx)
[docs]
def load_enum_value_type_def_from_id(
self, id: EnumValueTypeDefID
) -> EnumValueTypeDef:
"""Load a EnumValueTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEnumValueTypeDefFromID", _args)
return EnumValueTypeDef(_ctx)
[docs]
def load_env_file_from_id(self, id: EnvFileID) -> EnvFile:
"""Load a EnvFile from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEnvFileFromID", _args)
return EnvFile(_ctx)
[docs]
def load_env_from_id(self, id: EnvID) -> Env:
"""Load a Env from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEnvFromID", _args)
return Env(_ctx)
[docs]
def load_env_variable_from_id(self, id: EnvVariableID) -> EnvVariable:
"""Load a EnvVariable from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadEnvVariableFromID", _args)
return EnvVariable(_ctx)
[docs]
def load_error_from_id(self, id: ErrorID) -> Error:
"""Load a Error from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadErrorFromID", _args)
return Error(_ctx)
[docs]
def load_error_value_from_id(self, id: ErrorValueID) -> ErrorValue:
"""Load a ErrorValue from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadErrorValueFromID", _args)
return ErrorValue(_ctx)
[docs]
def load_exportable_from_id(self, id: ExportableID) -> Exportable:
"""Load a Exportable from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadExportableFromID", _args)
return _ExportableClient(_ctx)
[docs]
def load_field_type_def_from_id(self, id: FieldTypeDefID) -> FieldTypeDef:
"""Load a FieldTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadFieldTypeDefFromID", _args)
return FieldTypeDef(_ctx)
[docs]
def load_file_from_id(self, id: FileID) -> File:
"""Load a File from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadFileFromID", _args)
return File(_ctx)
[docs]
def load_function_arg_from_id(self, id: FunctionArgID) -> FunctionArg:
"""Load a FunctionArg from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadFunctionArgFromID", _args)
return FunctionArg(_ctx)
[docs]
def load_function_call_arg_value_from_id(
self, id: FunctionCallArgValueID
) -> FunctionCallArgValue:
"""Load a FunctionCallArgValue from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadFunctionCallArgValueFromID", _args)
return FunctionCallArgValue(_ctx)
[docs]
def load_function_call_from_id(self, id: FunctionCallID) -> FunctionCall:
"""Load a FunctionCall from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadFunctionCallFromID", _args)
return FunctionCall(_ctx)
[docs]
def load_function_from_id(self, id: FunctionID) -> Function:
"""Load a Function from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadFunctionFromID", _args)
return Function(_ctx)
[docs]
def load_generated_code_from_id(self, id: GeneratedCodeID) -> GeneratedCode:
"""Load a GeneratedCode from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadGeneratedCodeFromID", _args)
return GeneratedCode(_ctx)
[docs]
def load_generator_from_id(self, id: GeneratorID) -> Generator:
"""Load a Generator from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadGeneratorFromID", _args)
return Generator(_ctx)
[docs]
def load_generator_group_from_id(self, id: GeneratorGroupID) -> GeneratorGroup:
"""Load a GeneratorGroup from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadGeneratorGroupFromID", _args)
return GeneratorGroup(_ctx)
[docs]
def load_git_ref_from_id(self, id: GitRefID) -> GitRef:
"""Load a GitRef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadGitRefFromID", _args)
return GitRef(_ctx)
[docs]
def load_git_repository_from_id(self, id: GitRepositoryID) -> GitRepository:
"""Load a GitRepository from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadGitRepositoryFromID", _args)
return GitRepository(_ctx)
[docs]
def load_http_state_from_id(self, id: HTTPStateID) -> HTTPState:
"""Load a HTTPState from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadHTTPStateFromID", _args)
return HTTPState(_ctx)
[docs]
def load_healthcheck_config_from_id(
self, id: HealthcheckConfigID
) -> HealthcheckConfig:
"""Load a HealthcheckConfig from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadHealthcheckConfigFromID", _args)
return HealthcheckConfig(_ctx)
[docs]
def load_host_from_id(self, id: HostID) -> Host:
"""Load a Host from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadHostFromID", _args)
return Host(_ctx)
[docs]
def load_interface_type_def_from_id(
self, id: InterfaceTypeDefID
) -> InterfaceTypeDef:
"""Load a InterfaceTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadInterfaceTypeDefFromID", _args)
return InterfaceTypeDef(_ctx)
[docs]
def load_json_value_from_id(self, id: JSONValueID) -> JSONValue:
"""Load a JSONValue from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadJSONValueFromID", _args)
return JSONValue(_ctx)
[docs]
def load_llm_from_id(self, id: LLMID) -> LLM:
"""Load a LLM from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadLLMFromID", _args)
return LLM(_ctx)
[docs]
def load_llm_token_usage_from_id(self, id: LLMTokenUsageID) -> LLMTokenUsage:
"""Load a LLMTokenUsage from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadLLMTokenUsageFromID", _args)
return LLMTokenUsage(_ctx)
[docs]
def load_label_from_id(self, id: LabelID) -> Label:
"""Load a Label from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadLabelFromID", _args)
return Label(_ctx)
[docs]
def load_list_type_def_from_id(self, id: ListTypeDefID) -> ListTypeDef:
"""Load a ListTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadListTypeDefFromID", _args)
return ListTypeDef(_ctx)
[docs]
def load_module_config_client_from_id(
self, id: ModuleConfigClientID
) -> ModuleConfigClient:
"""Load a ModuleConfigClient from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadModuleConfigClientFromID", _args)
return ModuleConfigClient(_ctx)
[docs]
def load_module_from_id(self, id: ModuleID) -> Module:
"""Load a Module from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadModuleFromID", _args)
return Module(_ctx)
[docs]
def load_module_source_from_id(self, id: ModuleSourceID) -> ModuleSource:
"""Load a ModuleSource from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadModuleSourceFromID", _args)
return ModuleSource(_ctx)
[docs]
def load_object_type_def_from_id(self, id: ObjectTypeDefID) -> ObjectTypeDef:
"""Load a ObjectTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadObjectTypeDefFromID", _args)
return ObjectTypeDef(_ctx)
[docs]
def load_port_from_id(self, id: PortID) -> Port:
"""Load a Port from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadPortFromID", _args)
return Port(_ctx)
[docs]
def load_remote_git_mirror_from_id(
self, id: RemoteGitMirrorID
) -> "RemoteGitMirror":
"""Load a RemoteGitMirror from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadRemoteGitMirrorFromID", _args)
return RemoteGitMirror(_ctx)
[docs]
def load_sdk_config_from_id(self, id: SDKConfigID) -> "SDKConfig":
"""Load a SDKConfig from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSDKConfigFromID", _args)
return SDKConfig(_ctx)
[docs]
def load_scalar_type_def_from_id(self, id: ScalarTypeDefID) -> "ScalarTypeDef":
"""Load a ScalarTypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadScalarTypeDefFromID", _args)
return ScalarTypeDef(_ctx)
[docs]
def load_search_result_from_id(self, id: SearchResultID) -> "SearchResult":
"""Load a SearchResult from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSearchResultFromID", _args)
return SearchResult(_ctx)
[docs]
def load_search_submatch_from_id(self, id: SearchSubmatchID) -> "SearchSubmatch":
"""Load a SearchSubmatch from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSearchSubmatchFromID", _args)
return SearchSubmatch(_ctx)
[docs]
def load_secret_from_id(self, id: SecretID) -> "Secret":
"""Load a Secret from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSecretFromID", _args)
return Secret(_ctx)
[docs]
def load_service_from_id(self, id: ServiceID) -> "Service":
"""Load a Service from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadServiceFromID", _args)
return Service(_ctx)
[docs]
def load_socket_from_id(self, id: SocketID) -> "Socket":
"""Load a Socket from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSocketFromID", _args)
return Socket(_ctx)
[docs]
def load_source_map_from_id(self, id: SourceMapID) -> "SourceMap":
"""Load a SourceMap from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSourceMapFromID", _args)
return SourceMap(_ctx)
[docs]
def load_stat_from_id(self, id: StatID) -> "Stat":
"""Load a Stat from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadStatFromID", _args)
return Stat(_ctx)
[docs]
def load_syncer_from_id(self, id: SyncerID) -> Syncer:
"""Load a Syncer from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadSyncerFromID", _args)
return _SyncerClient(_ctx)
[docs]
def load_terminal_from_id(self, id: TerminalID) -> "Terminal":
"""Load a Terminal from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadTerminalFromID", _args)
return Terminal(_ctx)
[docs]
def load_type_def_from_id(self, id: TypeDefID) -> "TypeDef":
"""Load a TypeDef from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadTypeDefFromID", _args)
return TypeDef(_ctx)
[docs]
def load_up_from_id(self, id: UpID) -> "Up":
"""Load a Up from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadUpFromID", _args)
return Up(_ctx)
[docs]
def load_up_group_from_id(self, id: UpGroupID) -> "UpGroup":
"""Load a UpGroup from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadUpGroupFromID", _args)
return UpGroup(_ctx)
[docs]
def load_workspace_from_id(self, id: WorkspaceID) -> "Workspace":
"""Load a Workspace from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("loadWorkspaceFromID", _args)
return Workspace(_ctx)
[docs]
def module(self) -> Module:
"""Create a new module."""
_args: list[Arg] = []
_ctx = self._select("module", _args)
return Module(_ctx)
[docs]
def module_source(
self,
ref_string: str,
*,
ref_pin: str | None = "",
disable_find_up: bool | None = False,
allow_not_exists: bool | None = False,
require_kind: ModuleSourceKind | None = None,
) -> ModuleSource:
"""Create a new module source instance from a source ref string
Parameters
----------
ref_string:
The string ref representation of the module source
ref_pin:
The pinned version of the module source
disable_find_up:
If true, do not attempt to find dagger.json in a parent directory
of the provided path. Only relevant for local module sources.
allow_not_exists:
If true, do not error out if the provided ref string is a local
path and does not exist yet. Useful when initializing new modules
in directories that don't exist yet.
require_kind:
If set, error out if the ref string is not of the provided
requireKind.
"""
_args = [
Arg("refString", ref_string),
Arg("refPin", ref_pin, ""),
Arg("disableFindUp", disable_find_up, False),
Arg("allowNotExists", allow_not_exists, False),
Arg("requireKind", require_kind, None),
]
_ctx = self._select("moduleSource", _args)
return ModuleSource(_ctx)
[docs]
def node(self, id: Type) -> Node:
"""Load any object by its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("node", _args)
return _NodeClient(_ctx)
[docs]
def secret(
self,
uri: str,
*,
cache_key: str | None = None,
) -> "Secret":
"""Creates a new secret.
Parameters
----------
uri:
The URI of the secret store
cache_key:
If set, the given string will be used as the cache key for this
secret. This means that any secrets with the same cache key will
be considered equivalent in terms of cache lookups, even if they
have different URIs or plaintext values.
For example, two secrets with the same cache key provided as
secret env vars to other wise equivalent containers will result in
the container withExecs hitting the cache for each other.
If not set, the cache key for the secret will be derived from its
plaintext value as looked up when the secret is constructed.
"""
_args = [
Arg("uri", uri),
Arg("cacheKey", cache_key, None),
]
_ctx = self._select("secret", _args)
return Secret(_ctx)
[docs]
def set_secret(self, name: str, plaintext: str) -> "Secret":
"""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
"""
_args = [
Arg("name", name),
Arg("plaintext", plaintext),
]
_ctx = self._select("setSecret", _args)
return Secret(_ctx)
[docs]
def source_map(
self,
filename: str,
line: int,
column: int,
) -> "SourceMap":
"""Creates source map metadata.
Parameters
----------
filename:
The filename from the module source.
line:
The line number within the filename.
column:
The column number within the line.
"""
_args = [
Arg("filename", filename),
Arg("line", line),
Arg("column", column),
]
_ctx = self._select("sourceMap", _args)
return SourceMap(_ctx)
[docs]
def type_def(self) -> "TypeDef":
"""Create a new TypeDef."""
_args: list[Arg] = []
_ctx = self._select("typeDef", _args)
return TypeDef(_ctx)
[docs]
async def version(self) -> str:
"""Get the current Dagger Engine version.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("version", _args)
return await _ctx.execute(str)
@typecheck
class RemoteGitMirror(Type):
"""An internal persistent bare git mirror."""
[docs]
async def id(self) -> str:
"""A unique identifier for this RemoteGitMirror.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class SDKConfig(Type):
"""The SDK config of the module."""
[docs]
async def debug(self) -> bool:
"""Whether to start the SDK runtime in debug mode with an interactive
terminal.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("debug", _args)
return await _ctx.execute(bool)
[docs]
async def id(self) -> str:
"""A unique identifier for this SDKConfig.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def source(self) -> str:
"""Source of the SDK. Either a name of a builtin SDK or a module source
ref string pointing to the SDK's implementation.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("source", _args)
return await _ctx.execute(str)
@typecheck
class ScalarTypeDef(Type):
"""A definition of a custom scalar defined in a Module."""
[docs]
async def description(self) -> str:
"""A doc string for the scalar, if any.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this ScalarTypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of the scalar.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def source_module_name(self) -> str:
"""If this ScalarTypeDef is associated with a Module, the name of the
module. Unset otherwise.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("sourceModuleName", _args)
return await _ctx.execute(str)
@typecheck
class SearchResult(Type):
[docs]
async def absolute_offset(self) -> int:
"""The byte offset of this line within the file.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("absoluteOffset", _args)
return await _ctx.execute(int)
[docs]
async def file_path(self) -> str:
"""The path to the file that matched.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("filePath", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this SearchResult.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def line_number(self) -> int:
"""The first line that matched.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("lineNumber", _args)
return await _ctx.execute(int)
[docs]
async def matched_lines(self) -> str:
"""The line content that matched.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("matchedLines", _args)
return await _ctx.execute(str)
[docs]
async def submatches(self) -> list["SearchSubmatch"]:
"""Sub-match positions and content within the matched lines."""
_args: list[Arg] = []
_ctx = self._select("submatches", _args)
return await _ctx.execute_object_list(SearchSubmatch)
@typecheck
class SearchSubmatch(Type):
[docs]
async def end(self) -> int:
"""The match's end offset within the matched lines.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("end", _args)
return await _ctx.execute(int)
[docs]
async def id(self) -> str:
"""A unique identifier for this SearchSubmatch.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def start(self) -> int:
"""The match's start offset within the matched lines.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("start", _args)
return await _ctx.execute(int)
[docs]
async def text(self) -> str:
"""The matched text.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("text", _args)
return await _ctx.execute(str)
@typecheck
class Secret(Type):
"""A reference to a secret value, which can be handled more safely
than the value itself."""
[docs]
async def id(self) -> str:
"""A unique identifier for this Secret.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""The name of this secret.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def plaintext(self) -> str:
"""The value of this secret.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("plaintext", _args)
return await _ctx.execute(str)
[docs]
async def uri(self) -> str:
"""The URI of this secret.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("uri", _args)
return await _ctx.execute(str)
@typecheck
class Service(Type):
"""A content-addressed service providing TCP connectivity."""
[docs]
async def endpoint(
self,
*,
port: int | None = None,
scheme: str | None = "",
) -> str:
"""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
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("port", port, None),
Arg("scheme", scheme, ""),
]
_ctx = self._select("endpoint", _args)
return await _ctx.execute(str)
[docs]
async def hostname(self) -> str:
"""Retrieves a hostname which can be used by clients to reach this
container.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("hostname", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this Service.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def ports(self) -> list[Port]:
"""Retrieves the list of ports provided by the service."""
_args: list[Arg] = []
_ctx = self._select("ports", _args)
return await _ctx.execute_object_list(Port)
[docs]
async def start(self) -> Self:
"""Start the service and wait for its health checks to succeed.
Services bound to a Container do not need to be manually started.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "start", _args)
[docs]
async def stop(self, *, kill: bool | None = False) -> Self:
"""Stop the service.
Parameters
----------
kill:
Immediately kill the service without waiting for a graceful exit
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("kill", kill, False),
]
return await self._ctx.execute_sync(self, "stop", _args)
[docs]
async def sync(self) -> Self:
"""Forces evaluation of the pipeline in the engine.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
[docs]
def terminal(self, *, cmd: list[str] | None = None) -> Self:
_args = [
Arg("cmd", [] if cmd is None else cmd, []),
]
_ctx = self._select("terminal", _args)
return Service(_ctx)
[docs]
async def up(
self,
*,
ports: list[PortForward] | None = None,
random: bool | None = False,
) -> Void | None:
"""Creates a tunnel that forwards traffic from the caller's network to
this service.
Parameters
----------
ports:
List of frontend/backend port mappings to forward.
Frontend is the port accepting traffic on the host, backend is the
service port.
random:
Bind each tunnel port to a random port on the host.
Returns
-------
Void | None
The absence of a value. A Null Void is used as a placeholder for
resolvers that do not return anything.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("ports", [] if ports is None else ports, []),
Arg("random", random, False),
]
_ctx = self._select("up", _args)
await _ctx.execute()
[docs]
def with_hostname(self, hostname: str) -> Self:
"""Configures a hostname which can be used by clients within the session
to reach this container.
Parameters
----------
hostname:
The hostname to use.
"""
_args = [
Arg("hostname", hostname),
]
_ctx = self._select("withHostname", _args)
return Service(_ctx)
[docs]
def with_(self, cb: Callable[["Service"], "Service"]) -> "Service":
"""Call the provided callable with current Service.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Socket(Type):
"""A Unix or TCP/IP socket that can be mounted into a container."""
[docs]
async def id(self) -> str:
"""A unique identifier for this Socket.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
@typecheck
class SourceMap(Type):
"""Source location information."""
[docs]
async def column(self) -> int:
"""The column number within the line.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("column", _args)
return await _ctx.execute(int)
[docs]
async def filename(self) -> str:
"""The filename from the module source.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("filename", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this SourceMap.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def line(self) -> int:
"""The line number within the filename.
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("line", _args)
return await _ctx.execute(int)
[docs]
async def module(self) -> str:
"""The module dependency this was declared in.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("module", _args)
return await _ctx.execute(str)
[docs]
async def url(self) -> str:
"""The URL to the file, if any. This can be used to link to the source
map in the browser.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("url", _args)
return await _ctx.execute(str)
@typecheck
class Stat(Type):
"""A file or directory status object."""
[docs]
async def file_type(self) -> FileType | None:
"""file type
Returns
-------
FileType | None
File type.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("fileType", _args)
return await _ctx.execute(FileType | None)
[docs]
async def id(self) -> str:
"""A unique identifier for this Stat.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""file name
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def permissions(self) -> int:
"""permission bits
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("permissions", _args)
return await _ctx.execute(int)
[docs]
async def size(self) -> int:
"""file size
Returns
-------
int
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("size", _args)
return await _ctx.execute(int)
@typecheck
class Terminal(Type):
"""An interactive terminal that clients can connect to."""
[docs]
async def id(self) -> str:
"""A unique identifier for this Terminal.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def sync(self) -> Self:
"""Forces evaluation of the pipeline in the engine.
It doesn't run the default command if no exec has been set.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
return await self._ctx.execute_sync(self, "sync", _args)
def __await__(self):
return self.sync().__await__()
@typecheck
class TypeDef(Type):
"""A definition of a parameter or return type in a Module."""
[docs]
def as_enum(self) -> EnumTypeDef:
"""If kind is ENUM, the enum-specific type definition. If kind is not
ENUM, this will be null.
"""
_args: list[Arg] = []
_ctx = self._select("asEnum", _args)
return EnumTypeDef(_ctx)
[docs]
def as_interface(self) -> InterfaceTypeDef:
"""If kind is INTERFACE, the interface-specific type definition. If kind
is not INTERFACE, this will be null.
"""
_args: list[Arg] = []
_ctx = self._select("asInterface", _args)
return InterfaceTypeDef(_ctx)
[docs]
def as_list(self) -> ListTypeDef:
"""If kind is LIST, the list-specific type definition. If kind is not
LIST, this will be null.
"""
_args: list[Arg] = []
_ctx = self._select("asList", _args)
return ListTypeDef(_ctx)
[docs]
def as_object(self) -> ObjectTypeDef:
"""If kind is OBJECT, the object-specific type definition. If kind is not
OBJECT, this will be null.
"""
_args: list[Arg] = []
_ctx = self._select("asObject", _args)
return ObjectTypeDef(_ctx)
[docs]
def as_scalar(self) -> ScalarTypeDef:
"""If kind is SCALAR, the scalar-specific type definition. If kind is not
SCALAR, this will be null.
"""
_args: list[Arg] = []
_ctx = self._select("asScalar", _args)
return ScalarTypeDef(_ctx)
[docs]
async def id(self) -> str:
"""A unique identifier for this TypeDef.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def kind(self) -> TypeDefKind:
"""The kind of type this is (e.g. primitive, list, object).
Returns
-------
TypeDefKind
Distinguishes the different kinds of TypeDefs.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("kind", _args)
return await _ctx.execute(TypeDefKind)
[docs]
async def name(self) -> str:
"""The canonical non-optional name of the type.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
async def optional(self) -> bool:
"""Whether this type can be set to null. Defaults to false.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("optional", _args)
return await _ctx.execute(bool)
[docs]
def with_constructor(self, function: Function) -> Self:
"""Adds a function for constructing a new instance of an Object TypeDef,
failing if the type is not an object.
"""
_args = [
Arg("function", function),
]
_ctx = self._select("withConstructor", _args)
return TypeDef(_ctx)
[docs]
def with_enum(
self,
name: str,
*,
description: str | None = "",
source_map: SourceMap | None = None,
) -> Self:
"""Returns a TypeDef of kind Enum with the provided name.
Note that an enum's values may be omitted if the intent is only to
refer to an enum. This is how functions are able to return their own,
or any other circular reference.
Parameters
----------
name:
The name of the enum
description:
A doc string for the enum, if any
source_map:
The source map for the enum definition.
"""
_args = [
Arg("name", name),
Arg("description", description, ""),
Arg("sourceMap", source_map, None),
]
_ctx = self._select("withEnum", _args)
return TypeDef(_ctx)
[docs]
def with_enum_member(
self,
name: str,
*,
value: str | None = "",
description: str | None = "",
source_map: SourceMap | None = None,
deprecated: str | None = None,
) -> Self:
"""Adds a static value for an Enum TypeDef, failing if the type is not an
enum.
Parameters
----------
name:
The name of the member in the enum
value:
The value of the member in the enum
description:
A doc string for the member, if any
source_map:
The source map for the enum member definition.
deprecated:
If deprecated, the reason or migration path.
"""
_args = [
Arg("name", name),
Arg("value", value, ""),
Arg("description", description, ""),
Arg("sourceMap", source_map, None),
Arg("deprecated", deprecated, None),
]
_ctx = self._select("withEnumMember", _args)
return TypeDef(_ctx)
[docs]
def with_enum_value(
self,
value: str,
*,
description: str | None = "",
source_map: SourceMap | None = None,
deprecated: str | None = None,
) -> Self:
"""Adds a static value for an Enum TypeDef, failing if the type is not an
enum.
.. deprecated::
Use :py:meth:`with_enum_member` instead
Parameters
----------
value:
The name of the value in the enum
description:
A doc string for the value, if any
source_map:
The source map for the enum value definition.
deprecated:
If deprecated, the reason or migration path.
"""
warnings.warn(
'Method "with_enum_value" is deprecated: Use "with_enum_member" instead',
DeprecationWarning,
stacklevel=4,
)
_args = [
Arg("value", value),
Arg("description", description, ""),
Arg("sourceMap", source_map, None),
Arg("deprecated", deprecated, None),
]
_ctx = self._select("withEnumValue", _args)
return TypeDef(_ctx)
[docs]
def with_field(
self,
name: str,
type_def: Self,
*,
description: str | None = "",
source_map: SourceMap | None = None,
deprecated: str | None = None,
) -> Self:
"""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
source_map:
The source map for the field definition.
deprecated:
If deprecated, the reason or migration path.
"""
_args = [
Arg("name", name),
Arg("typeDef", type_def),
Arg("description", description, ""),
Arg("sourceMap", source_map, None),
Arg("deprecated", deprecated, None),
]
_ctx = self._select("withField", _args)
return TypeDef(_ctx)
[docs]
def with_function(self, function: Function) -> Self:
"""Adds a function for an Object or Interface TypeDef, failing if the
type is not one of those kinds.
"""
_args = [
Arg("function", function),
]
_ctx = self._select("withFunction", _args)
return TypeDef(_ctx)
[docs]
def with_interface(
self,
name: str,
*,
description: str | None = "",
source_map: SourceMap | None = None,
) -> Self:
"""Returns a TypeDef of kind Interface with the provided name."""
_args = [
Arg("name", name),
Arg("description", description, ""),
Arg("sourceMap", source_map, None),
]
_ctx = self._select("withInterface", _args)
return TypeDef(_ctx)
[docs]
def with_kind(self, kind: TypeDefKind) -> Self:
"""Sets the kind of the type."""
_args = [
Arg("kind", kind),
]
_ctx = self._select("withKind", _args)
return TypeDef(_ctx)
[docs]
def with_list_of(self, element_type: Self) -> Self:
"""Returns a TypeDef of kind List with the provided type for its
elements.
"""
_args = [
Arg("elementType", element_type),
]
_ctx = self._select("withListOf", _args)
return TypeDef(_ctx)
[docs]
def with_object(
self,
name: str,
*,
description: str | None = "",
source_map: SourceMap | None = None,
deprecated: str | None = None,
) -> Self:
"""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.
"""
_args = [
Arg("name", name),
Arg("description", description, ""),
Arg("sourceMap", source_map, None),
Arg("deprecated", deprecated, None),
]
_ctx = self._select("withObject", _args)
return TypeDef(_ctx)
[docs]
def with_optional(self, optional: bool) -> Self:
"""Sets whether this type can be set to null."""
_args = [
Arg("optional", optional),
]
_ctx = self._select("withOptional", _args)
return TypeDef(_ctx)
[docs]
def with_scalar(
self,
name: str,
*,
description: str | None = "",
) -> Self:
"""Returns a TypeDef of kind Scalar with the provided name."""
_args = [
Arg("name", name),
Arg("description", description, ""),
]
_ctx = self._select("withScalar", _args)
return TypeDef(_ctx)
[docs]
def with_(self, cb: Callable[["TypeDef"], "TypeDef"]) -> "TypeDef":
"""Call the provided callable with current TypeDef.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Up(Type):
[docs]
async def description(self) -> str:
"""The description of the service
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("description", _args)
return await _ctx.execute(str)
[docs]
async def id(self) -> str:
"""A unique identifier for this Up.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def name(self) -> str:
"""Return the fully qualified name of the service
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs]
def original_module(self) -> Module:
"""The original module in which the service has been defined"""
_args: list[Arg] = []
_ctx = self._select("originalModule", _args)
return Module(_ctx)
[docs]
async def path(self) -> list[str]:
"""The path of the service within its module
Returns
-------
list[str]
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("path", _args)
return await _ctx.execute(list[str])
[docs]
def run(self) -> Self:
"""Execute the service function"""
_args: list[Arg] = []
_ctx = self._select("run", _args)
return Up(_ctx)
[docs]
def with_(self, cb: Callable[["Up"], "Up"]) -> "Up":
"""Call the provided callable with current Up.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class UpGroup(Type):
[docs]
async def id(self) -> str:
"""A unique identifier for this UpGroup.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def list_(self) -> list[Up]:
"""Return a list of individual services and their details"""
_args: list[Arg] = []
_ctx = self._select("list", _args)
return await _ctx.execute_object_list(Up)
[docs]
def run(self) -> Self:
"""Execute all selected service functions"""
_args: list[Arg] = []
_ctx = self._select("run", _args)
return UpGroup(_ctx)
[docs]
def with_(self, cb: Callable[["UpGroup"], "UpGroup"]) -> "UpGroup":
"""Call the provided callable with current UpGroup.
This is useful for reusability and readability by not breaking the calling chain.
"""
return cb(self)
@typecheck
class Workspace(Type):
"""A Dagger workspace detected from the current working directory."""
[docs]
async def address(self) -> str:
"""Canonical Dagger address of the workspace directory.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("address", _args)
return await _ctx.execute(str)
[docs]
def checks(
self,
*,
include: list[str] | None = None,
no_generate: bool | None = None,
only_generate: bool | None = None,
) -> CheckGroup:
"""Return all checks from modules loaded in the workspace.
Parameters
----------
include:
Only include checks matching the specified patterns
no_generate:
When true, only return annotated check functions; exclude
generate-as-checks
only_generate:
When true, only return generate-as-checks; exclude annotated check
functions
"""
_args = [
Arg("include", include, None),
Arg("noGenerate", no_generate, None),
Arg("onlyGenerate", only_generate, None),
]
_ctx = self._select("checks", _args)
return CheckGroup(_ctx)
[docs]
async def client_id(self) -> str:
"""The client ID that owns this workspace's host filesystem.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("clientId", _args)
return await _ctx.execute(str)
[docs]
async def config_path(self) -> str:
"""Path to config.toml relative to the workspace boundary (empty if not
initialized).
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("configPath", _args)
return await _ctx.execute(str)
[docs]
def directory(
self,
path: str,
*,
exclude: list[str] | None = None,
include: list[str] | None = None,
gitignore: bool | None = False,
) -> Directory:
"""Returns a Directory from the workspace.
Relative paths resolve from the workspace directory. Absolute paths
resolve from the workspace boundary.
Parameters
----------
path:
Location of the directory to retrieve. Relative paths (e.g.,
"src") resolve from the workspace directory; absolute paths (e.g.,
"/src") resolve from the workspace boundary.
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.*"]).
gitignore:
Apply .gitignore filter rules inside the directory.
"""
_args = [
Arg("path", path),
Arg("exclude", [] if exclude is None else exclude, []),
Arg("include", [] if include is None else include, []),
Arg("gitignore", gitignore, False),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs]
def file(self, path: str) -> File:
"""Returns a File from the workspace.
Relative paths resolve from the workspace directory. Absolute paths
resolve from the workspace boundary.
Parameters
----------
path:
Location of the file to retrieve. Relative paths (e.g., "go.mod")
resolve from the workspace directory; absolute paths (e.g.,
"/go.mod") resolve from the workspace boundary.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs]
async def find_up(
self,
name: str,
*,
from_: str | None = ".",
) -> str | None:
"""Search for a file or directory by walking up from the start path
within the workspace.
Returns the absolute workspace path if found, or null if not found.
Relative start paths resolve from the workspace directory.
The search stops at the workspace boundary and will not traverse above
it.
Parameters
----------
name:
The name of the file or directory to search for.
from_:
Path to start the search from. Relative paths resolve from the
workspace directory; absolute paths resolve from the workspace
boundary.
Returns
-------
str | None
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args = [
Arg("name", name),
Arg("from", from_, "."),
]
_ctx = self._select("findUp", _args)
return await _ctx.execute(str | None)
[docs]
def generators(
self,
*,
include: list[str] | None = None,
) -> GeneratorGroup:
"""Return all generators from modules loaded in the workspace.
Parameters
----------
include:
Only include generators matching the specified patterns
"""
_args = [
Arg("include", include, None),
]
_ctx = self._select("generators", _args)
return GeneratorGroup(_ctx)
[docs]
async def has_config(self) -> bool:
"""Whether a config.toml file exists in the workspace.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("hasConfig", _args)
return await _ctx.execute(bool)
[docs]
async def id(self) -> str:
"""A unique identifier for this Workspace.
Note
----
This is lazily evaluated, no operation is actually run.
Returns
-------
str
The `ID` scalar type represents a unique identifier, often used to
refetch an object or as key for a cache. The ID type appears in a
JSON response as a String; however, it is not intended to be
human-readable. When expected as an input type, any string (such
as `"4"`) or integer (such as `4`) input value will be accepted as
an ID.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(str)
[docs]
async def initialized(self) -> bool:
"""Whether .dagger/config.toml exists.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("initialized", _args)
return await _ctx.execute(bool)
[docs]
async def path(self) -> str:
"""Workspace directory path relative to the workspace boundary.
Returns
-------
str
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.
Raises
------
ExecuteTimeoutError
If the time to execute the query exceeds the configured timeout.
QueryError
If the API returns an error.
"""
_args: list[Arg] = []
_ctx = self._select("path", _args)
return await _ctx.execute(str)
[docs]
def services(
self,
*,
include: list[str] | None = None,
) -> UpGroup:
"""Return all services from modules loaded in the workspace.
Parameters
----------
include:
Only include services matching the specified patterns
"""
_args = [
Arg("include", include, None),
]
_ctx = self._select("services", _args)
return UpGroup(_ctx)
[docs]
def update(self) -> Changeset:
"""Refresh workspace-managed state and return the resulting changeset.
Currently this refreshes existing lockfile entries only.
.. caution::
Experimental: Experimental workspace update API currently
refreshes existing lockfile entries only.
"""
_args: list[Arg] = []
_ctx = self._select("update", _args)
return Changeset(_ctx)
class Client(Query):
"""The Dagger client.
Inherits all Query API methods and adds connection management.
"""
dag = Client()
"""The global client instance."""
__all__ = [
"JSON",
"LLM",
"LLMID",
"Address",
"AddressID",
"Binding",
"BindingID",
"BuildArg",
"CacheSharingMode",
"CacheVolume",
"CacheVolumeID",
"Changeset",
"ChangesetID",
"ChangesetMergeConflict",
"ChangesetsMergeConflict",
"Check",
"CheckGroup",
"CheckGroupID",
"CheckID",
"Client",
"ClientFilesyncMirror",
"ClientFilesyncMirrorID",
"Cloud",
"CloudID",
"Container",
"ContainerID",
"CurrentModule",
"CurrentModuleID",
"DiffStat",
"DiffStatID",
"DiffStatKind",
"Directory",
"DirectoryID",
"Engine",
"EngineCache",
"EngineCacheEntry",
"EngineCacheEntryID",
"EngineCacheEntrySet",
"EngineCacheEntrySetID",
"EngineCacheID",
"EngineID",
"EnumTypeDef",
"EnumTypeDefID",
"EnumValueTypeDef",
"EnumValueTypeDefID",
"Env",
"EnvFile",
"EnvFileID",
"EnvID",
"EnvVariable",
"EnvVariableID",
"Error",
"ErrorID",
"ErrorValue",
"ErrorValueID",
"ExistsType",
"Exportable",
"ExportableID",
"FieldTypeDef",
"FieldTypeDefID",
"File",
"FileID",
"FileType",
"Function",
"FunctionArg",
"FunctionArgID",
"FunctionCachePolicy",
"FunctionCall",
"FunctionCallArgValue",
"FunctionCallArgValueID",
"FunctionCallID",
"FunctionID",
"GeneratedCode",
"GeneratedCodeID",
"Generator",
"GeneratorGroup",
"GeneratorGroupID",
"GeneratorID",
"GitRef",
"GitRefID",
"GitRepository",
"GitRepositoryID",
"HTTPState",
"HTTPStateID",
"HealthcheckConfig",
"HealthcheckConfigID",
"Host",
"HostID",
"ImageLayerCompression",
"ImageMediaTypes",
"InputTypeDef",
"InputTypeDefID",
"InterfaceTypeDef",
"InterfaceTypeDefID",
"JSONValue",
"JSONValueID",
"LLMTokenUsage",
"LLMTokenUsageID",
"Label",
"LabelID",
"ListTypeDef",
"ListTypeDefID",
"Module",
"ModuleConfigClient",
"ModuleConfigClientID",
"ModuleID",
"ModuleSource",
"ModuleSourceExperimentalFeature",
"ModuleSourceID",
"ModuleSourceKind",
"NetworkProtocol",
"Node",
"ObjectTypeDef",
"ObjectTypeDefID",
"PipelineLabel",
"Platform",
"Port",
"PortForward",
"PortID",
"Query",
"RemoteGitMirror",
"RemoteGitMirrorID",
"ReturnType",
"SDKConfig",
"SDKConfigID",
"ScalarTypeDef",
"ScalarTypeDefID",
"SearchResult",
"SearchResultID",
"SearchSubmatch",
"SearchSubmatchID",
"Secret",
"SecretID",
"Service",
"ServiceID",
"Socket",
"SocketID",
"SourceMap",
"SourceMapID",
"Stat",
"StatID",
"Syncer",
"SyncerID",
"Terminal",
"TerminalID",
"TypeDef",
"TypeDefID",
"TypeDefKind",
"Up",
"UpGroup",
"UpGroupID",
"UpID",
"Void",
"Workspace",
"WorkspaceID",
"dag",
]