# Code generated by dagger. DO NOT EDIT.
from collections.abc import Sequence
from typing import Optional
from dagger.api.base import Arg, Enum, Input, Root, Scalar, Type, typecheck
[docs]class CacheID(Scalar):
"""A global cache volume identifier."""
[docs]class ContainerID(Scalar):
"""A unique container identifier. Null designates an empty container
(scratch)."""
[docs]class DirectoryID(Scalar):
"""A content-addressed directory identifier."""
[docs]class FileID(Scalar):
"""A file identifier."""
[docs]class SecretID(Scalar):
"""A unique identifier for a secret."""
[docs]class SocketID(Scalar):
"""A content-addressed socket identifier."""
[docs]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"""
[docs]class BuildArg(Input):
name: str
value: str
[docs]class CacheVolume(Type):
"""A directory whose contents persist across runs."""
[docs] @typecheck
async def id(self) -> CacheID:
"""Note
----
This is lazyly evaluated, no operation is actually run.
Returns
-------
CacheID
A global cache volume identifier.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(CacheID)
[docs]class Container(Type):
"""An OCI-compatible container, also known as a docker container."""
[docs] @typecheck
def build(
self,
context: "Directory",
dockerfile: Optional[str] = None,
build_args: Optional[Sequence[BuildArg]] = None,
target: Optional[str] = None,
) -> "Container":
"""Initializes this container from a Dockerfile build, using the context,
a dockerfile file path and some additional buildArgs.
Parameters
----------
context:
Directory context used by the Dockerfile.
dockerfile:
Path to the Dockerfile to use.
Defaults to './Dockerfile'.
build_args:
Additional build arguments.
target:
Target build stage to build.
"""
_args = [
Arg("context", context),
Arg("dockerfile", dockerfile, None),
Arg("buildArgs", build_args, None),
Arg("target", target, None),
]
_ctx = self._select("build", _args)
return Container(_ctx)
[docs] @typecheck
async def default_args(self) -> Optional[list[str]]:
"""Retrieves default arguments for future commands.
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("defaultArgs", _args)
return await _ctx.execute(Optional[list[str]])
[docs] @typecheck
def directory(self, path: str) -> "Directory":
"""Retrieves a directory at the given path. Mounts are included."""
_args = [
Arg("path", path),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs] @typecheck
async def entrypoint(self) -> Optional[list[str]]:
"""Retrieves entrypoint to be prepended to the arguments of all commands.
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("entrypoint", _args)
return await _ctx.execute(Optional[list[str]])
[docs] @typecheck
async def env_variable(self, name: str) -> Optional[str]:
"""Retrieves the value of the specified environment variable.
Returns
-------
Optional[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.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("envVariable", _args)
return await _ctx.execute(Optional[str])
[docs] @typecheck
def env_variables(self) -> "EnvVariable":
"""Retrieves the list of environment variables passed to commands."""
_args: list[Arg] = []
_ctx = self._select("envVariables", _args)
return EnvVariable(_ctx)
[docs] @typecheck
def exec(
self,
args: Optional[Sequence[str]] = None,
stdin: Optional[str] = None,
redirect_stdout: Optional[str] = None,
redirect_stderr: Optional[str] = None,
experimental_privileged_nesting: Optional[bool] = None,
) -> "Container":
"""Retrieves this container after executing the specified command inside
it.
.. deprecated::
Replaced by :py:meth:`with_exec`.
Parameters
----------
args:
Command to run instead of the container's default command.
stdin:
Content to write to the command's standard input before closing.
redirect_stdout:
Redirect the command's standard output to a file in the container.
redirect_stderr:
Redirect the command's standard error to a file in the container.
experimental_privileged_nesting:
Provide dagger access to the executed command.
Do not use this option unless you trust the command being
executed.
The command being executed WILL BE GRANTED FULL ACCESS TO YOUR
HOST FILESYSTEM.
"""
_args = [
Arg("args", args, None),
Arg("stdin", stdin, None),
Arg("redirectStdout", redirect_stdout, None),
Arg("redirectStderr", redirect_stderr, None),
Arg("experimentalPrivilegedNesting", experimental_privileged_nesting, None),
]
_ctx = self._select("exec", _args)
return Container(_ctx)
[docs] @typecheck
async def exit_code(self) -> Optional[int]:
"""Exit code of the last executed command. Zero means success.
Null if no command has been executed.
Returns
-------
Optional[int]
The `Int` scalar type represents non-fractional signed whole
numeric values. Int can represent values between -(2^31) and 2^31
- 1.
"""
_args: list[Arg] = []
_ctx = self._select("exitCode", _args)
return await _ctx.execute(Optional[int])
[docs] @typecheck
async def export(
self,
path: str,
platform_variants: Optional[Sequence["Container"]] = None,
) -> bool:
"""Writes the container as an OCI tarball to the destination file path on
the host for the specified platformVariants.
Return true on success.
Parameters
----------
path:
Host's destination path.
Path can be relative to the engine's workdir or absolute.
platform_variants:
Identifiers for other platform specific containers.
Used for multi-platform image.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
"""
_args = [
Arg("path", path),
Arg("platformVariants", platform_variants, None),
]
_ctx = self._select("export", _args)
return await _ctx.execute(bool)
[docs] @typecheck
def file(self, path: str) -> "File":
"""Retrieves a file at the given path. Mounts are included."""
_args = [
Arg("path", path),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs] @typecheck
def from_(self, address: str) -> "Container":
"""Initializes this container from the base image published at the given
address.
Parameters
----------
address:
Image's address from its registry.
Formatted as [host]/[user]/[repo]:[tag] (e.g.
docker.io/dagger/dagger:main).
"""
_args = [
Arg("address", address),
]
_ctx = self._select("from", _args)
return Container(_ctx)
[docs] @typecheck
def fs(self) -> "Directory":
"""Retrieves this container's root filesystem. Mounts are not included.
.. deprecated::
Replaced by :py:meth:`rootfs`.
"""
_args: list[Arg] = []
_ctx = self._select("fs", _args)
return Directory(_ctx)
[docs] @typecheck
async def id(self) -> ContainerID:
"""A unique identifier for this container.
Note
----
This is lazyly evaluated, no operation is actually run.
Returns
-------
ContainerID
A unique container identifier. Null designates an empty container
(scratch).
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(ContainerID)
[docs] @typecheck
async def label(self, name: str) -> Optional[str]:
"""Retrieves the value of the specified label.
Returns
-------
Optional[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.
"""
_args = [
Arg("name", name),
]
_ctx = self._select("label", _args)
return await _ctx.execute(Optional[str])
[docs] @typecheck
def labels(self) -> "Label":
"""Retrieves the list of labels passed to container."""
_args: list[Arg] = []
_ctx = self._select("labels", _args)
return Label(_ctx)
[docs] @typecheck
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.
"""
_args: list[Arg] = []
_ctx = self._select("mounts", _args)
return await _ctx.execute(list[str])
[docs] @typecheck
def pipeline(
self,
name: str,
description: Optional[str] = None,
) -> "Container":
"""Creates a named sub-pipeline"""
_args = [
Arg("name", name),
Arg("description", description, None),
]
_ctx = self._select("pipeline", _args)
return Container(_ctx)
[docs] @typecheck
async def publish(
self,
address: str,
platform_variants: Optional[Sequence["Container"]] = None,
) -> str:
"""Publishes this container as a new image to the specified address, for
the platformVariants, returning a fully qualified ref.
Parameters
----------
address:
Registry's address to publish the image to.
Formatted as [host]/[user]/[repo]:[tag] (e.g.
docker.io/dagger/dagger:main).
platform_variants:
Identifiers for other platform specific containers.
Used for multi-platform image.
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.
"""
_args = [
Arg("address", address),
Arg("platformVariants", platform_variants, None),
]
_ctx = self._select("publish", _args)
return await _ctx.execute(str)
[docs] @typecheck
def rootfs(self) -> "Directory":
"""Retrieves this container's root filesystem. Mounts are not included."""
_args: list[Arg] = []
_ctx = self._select("rootfs", _args)
return Directory(_ctx)
[docs] @typecheck
async def stderr(self) -> Optional[str]:
"""The error stream of the last executed command.
Null if no command has been executed.
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("stderr", _args)
return await _ctx.execute(Optional[str])
[docs] @typecheck
async def stdout(self) -> Optional[str]:
"""The output stream of the last executed command.
Null if no command has been executed.
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("stdout", _args)
return await _ctx.execute(Optional[str])
[docs] @typecheck
async def user(self) -> Optional[str]:
"""Retrieves the user to be set for all commands.
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("user", _args)
return await _ctx.execute(Optional[str])
[docs] @typecheck
def with_default_args(
self,
args: Optional[Sequence[str]] = None,
) -> "Container":
"""Configures default arguments for future commands."""
_args = [
Arg("args", args, None),
]
_ctx = self._select("withDefaultArgs", _args)
return Container(_ctx)
[docs] @typecheck
def with_directory(
self,
path: str,
directory: "Directory",
exclude: Optional[Sequence[str]] = None,
include: Optional[Sequence[str]] = None,
) -> "Container":
"""Retrieves this container plus a directory written at the given path."""
_args = [
Arg("path", path),
Arg("directory", directory),
Arg("exclude", exclude, None),
Arg("include", include, None),
]
_ctx = self._select("withDirectory", _args)
return Container(_ctx)
[docs] @typecheck
def with_entrypoint(self, args: Sequence[str]) -> "Container":
"""Retrieves this container but with a different command entrypoint."""
_args = [
Arg("args", args),
]
_ctx = self._select("withEntrypoint", _args)
return Container(_ctx)
[docs] @typecheck
def with_env_variable(self, name: str, value: str) -> "Container":
"""Retrieves this container plus the given environment variable."""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withEnvVariable", _args)
return Container(_ctx)
[docs] @typecheck
def with_exec(
self,
args: Sequence[str],
stdin: Optional[str] = None,
redirect_stdout: Optional[str] = None,
redirect_stderr: Optional[str] = None,
experimental_privileged_nesting: Optional[bool] = None,
) -> "Container":
"""Retrieves this container after executing the specified command inside
it.
Parameters
----------
args:
Command to run instead of the container's default command.
stdin:
Content to write to the command's standard input before closing.
redirect_stdout:
Redirect the command's standard output to a file in the container.
redirect_stderr:
Redirect the command's standard error to a file in the container.
experimental_privileged_nesting:
Provide dagger access to the executed command.
Do not use this option unless you trust the command being
executed.
The command being executed WILL BE GRANTED FULL ACCESS TO YOUR
HOST FILESYSTEM.
"""
_args = [
Arg("args", args),
Arg("stdin", stdin, None),
Arg("redirectStdout", redirect_stdout, None),
Arg("redirectStderr", redirect_stderr, None),
Arg("experimentalPrivilegedNesting", experimental_privileged_nesting, None),
]
_ctx = self._select("withExec", _args)
return Container(_ctx)
[docs] @typecheck
def with_fs(self, id: "Directory") -> "Container":
"""Initializes this container from this DirectoryID.
.. deprecated::
Replaced by :py:meth:`with_rootfs`.
"""
_args = [
Arg("id", id),
]
_ctx = self._select("withFS", _args)
return Container(_ctx)
[docs] @typecheck
def with_file(
self,
path: str,
source: "File",
permissions: Optional[int] = None,
) -> "Container":
"""Retrieves this container plus the contents of the given file copied to
the given path.
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("permissions", permissions, None),
]
_ctx = self._select("withFile", _args)
return Container(_ctx)
[docs] @typecheck
def with_label(self, name: str, value: str) -> "Container":
"""Retrieves this container plus the given label."""
_args = [
Arg("name", name),
Arg("value", value),
]
_ctx = self._select("withLabel", _args)
return Container(_ctx)
[docs] @typecheck
def with_mounted_cache(
self,
path: str,
cache: CacheVolume,
source: Optional["Directory"] = None,
sharing: Optional[CacheSharingMode] = None,
) -> "Container":
"""Retrieves this container plus a cache volume mounted at the given
path.
Parameters
----------
path:
Path to mount the cache volume at.
cache:
ID of the cache to mount.
source:
Directory to use as the cache volume's root.
sharing:
Sharing mode of the cache volume.
"""
_args = [
Arg("path", path),
Arg("cache", cache),
Arg("source", source, None),
Arg("sharing", sharing, None),
]
_ctx = self._select("withMountedCache", _args)
return Container(_ctx)
[docs] @typecheck
def with_mounted_directory(self, path: str, source: "Directory") -> "Container":
"""Retrieves this container plus a directory mounted at the given path."""
_args = [
Arg("path", path),
Arg("source", source),
]
_ctx = self._select("withMountedDirectory", _args)
return Container(_ctx)
[docs] @typecheck
def with_mounted_file(self, path: str, source: "File") -> "Container":
"""Retrieves this container plus a file mounted at the given path."""
_args = [
Arg("path", path),
Arg("source", source),
]
_ctx = self._select("withMountedFile", _args)
return Container(_ctx)
[docs] @typecheck
def with_mounted_secret(self, path: str, source: "Secret") -> "Container":
"""Retrieves this container plus a secret mounted into a file at the
given path.
"""
_args = [
Arg("path", path),
Arg("source", source),
]
_ctx = self._select("withMountedSecret", _args)
return Container(_ctx)
[docs] @typecheck
def with_mounted_temp(self, path: str) -> "Container":
"""Retrieves this container plus a temporary directory mounted at the
given path.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("withMountedTemp", _args)
return Container(_ctx)
[docs] @typecheck
def with_new_file(
self,
path: str,
contents: Optional[str] = None,
permissions: Optional[int] = None,
) -> "Container":
"""Retrieves this container plus a new file written at the given path."""
_args = [
Arg("path", path),
Arg("contents", contents, None),
Arg("permissions", permissions, None),
]
_ctx = self._select("withNewFile", _args)
return Container(_ctx)
[docs] @typecheck
def with_registry_auth(
self,
address: str,
username: str,
secret: "Secret",
) -> "Container":
"""Retrieves this container with a registry authentication for a given
address.
Parameters
----------
address:
Registry's address to bind the authentication to.
Formatted as [host]/[user]/[repo]:[tag] (e.g.
docker.io/dagger/dagger:main).
username:
The username of the registry's account (e.g., "Dagger").
secret:
The API key, password or token to authenticate to this registry.
"""
_args = [
Arg("address", address),
Arg("username", username),
Arg("secret", secret),
]
_ctx = self._select("withRegistryAuth", _args)
return Container(_ctx)
[docs] @typecheck
def with_rootfs(self, id: "Directory") -> "Container":
"""Initializes this container from this DirectoryID."""
_args = [
Arg("id", id),
]
_ctx = self._select("withRootfs", _args)
return Container(_ctx)
[docs] @typecheck
def with_secret_variable(self, name: str, secret: "Secret") -> "Container":
"""Retrieves this container plus an env variable containing the given
secret.
"""
_args = [
Arg("name", name),
Arg("secret", secret),
]
_ctx = self._select("withSecretVariable", _args)
return Container(_ctx)
[docs] @typecheck
def with_unix_socket(self, path: str, source: "Socket") -> "Container":
"""Retrieves this container plus a socket forwarded to the given Unix
socket path.
"""
_args = [
Arg("path", path),
Arg("source", source),
]
_ctx = self._select("withUnixSocket", _args)
return Container(_ctx)
[docs] @typecheck
def with_user(self, name: str) -> "Container":
"""Retrieves this containers with a different command user."""
_args = [
Arg("name", name),
]
_ctx = self._select("withUser", _args)
return Container(_ctx)
[docs] @typecheck
def with_workdir(self, path: str) -> "Container":
"""Retrieves this container with a different working directory."""
_args = [
Arg("path", path),
]
_ctx = self._select("withWorkdir", _args)
return Container(_ctx)
[docs] @typecheck
def without_env_variable(self, name: str) -> "Container":
"""Retrieves this container minus the given environment variable."""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutEnvVariable", _args)
return Container(_ctx)
[docs] @typecheck
def without_label(self, name: str) -> "Container":
"""Retrieves this container minus the given environment label."""
_args = [
Arg("name", name),
]
_ctx = self._select("withoutLabel", _args)
return Container(_ctx)
[docs] @typecheck
def without_mount(self, path: str) -> "Container":
"""Retrieves this container after unmounting everything at the given
path.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutMount", _args)
return Container(_ctx)
[docs] @typecheck
def without_registry_auth(self, address: str) -> "Container":
"""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] @typecheck
def without_unix_socket(self, path: str) -> "Container":
"""Retrieves this container with a previously added Unix socket removed."""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutUnixSocket", _args)
return Container(_ctx)
[docs] @typecheck
async def workdir(self) -> Optional[str]:
"""Retrieves the working directory for all commands.
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("workdir", _args)
return await _ctx.execute(Optional[str])
[docs]class Directory(Type):
"""A directory."""
[docs] @typecheck
def diff(self, other: "Directory") -> "Directory":
"""Gets the difference between this directory and an another directory."""
_args = [
Arg("other", other),
]
_ctx = self._select("diff", _args)
return Directory(_ctx)
[docs] @typecheck
def directory(self, path: str) -> "Directory":
"""Retrieves a directory at the given path."""
_args = [
Arg("path", path),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs] @typecheck
def docker_build(
self,
dockerfile: Optional[str] = None,
platform: Optional[Platform] = None,
build_args: Optional[Sequence[BuildArg]] = None,
target: Optional[str] = None,
) -> Container:
"""Builds a new Docker container from this directory.
Parameters
----------
dockerfile:
Path to the Dockerfile to use.
Defaults to './Dockerfile'.
platform:
The platform to build.
build_args:
Additional build arguments.
target:
Target build stage to build.
"""
_args = [
Arg("dockerfile", dockerfile, None),
Arg("platform", platform, None),
Arg("buildArgs", build_args, None),
Arg("target", target, None),
]
_ctx = self._select("dockerBuild", _args)
return Container(_ctx)
[docs] @typecheck
async def entries(self, path: Optional[str] = None) -> list[str]:
"""Returns a list of files and directories at the given path.
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.
"""
_args = [
Arg("path", path, None),
]
_ctx = self._select("entries", _args)
return await _ctx.execute(list[str])
[docs] @typecheck
async def export(self, path: str) -> bool:
"""Writes the contents of the directory to a path on the host.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("export", _args)
return await _ctx.execute(bool)
[docs] @typecheck
def file(self, path: str) -> "File":
"""Retrieves a file at the given path."""
_args = [
Arg("path", path),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs] @typecheck
async def id(self) -> DirectoryID:
"""The content-addressed identifier of the directory.
Note
----
This is lazyly evaluated, no operation is actually run.
Returns
-------
DirectoryID
A content-addressed directory identifier.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(DirectoryID)
[docs] @typecheck
def load_project(self, config_path: str) -> "Project":
"""load a project's metadata"""
_args = [
Arg("configPath", config_path),
]
_ctx = self._select("loadProject", _args)
return Project(_ctx)
[docs] @typecheck
def pipeline(
self,
name: str,
description: Optional[str] = None,
) -> "Directory":
"""Creates a named sub-pipeline."""
_args = [
Arg("name", name),
Arg("description", description, None),
]
_ctx = self._select("pipeline", _args)
return Directory(_ctx)
[docs] @typecheck
def with_directory(
self,
path: str,
directory: "Directory",
exclude: Optional[Sequence[str]] = None,
include: Optional[Sequence[str]] = None,
) -> "Directory":
"""Retrieves this directory plus a directory written at the given path.
Parameters
----------
path:
directory:
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.*"]).
"""
_args = [
Arg("path", path),
Arg("directory", directory),
Arg("exclude", exclude, None),
Arg("include", include, None),
]
_ctx = self._select("withDirectory", _args)
return Directory(_ctx)
[docs] @typecheck
def with_file(
self,
path: str,
source: "File",
permissions: Optional[int] = None,
) -> "Directory":
"""Retrieves this directory plus the contents of the given file copied to
the given path.
"""
_args = [
Arg("path", path),
Arg("source", source),
Arg("permissions", permissions, None),
]
_ctx = self._select("withFile", _args)
return Directory(_ctx)
[docs] @typecheck
def with_new_directory(
self,
path: str,
permissions: Optional[int] = None,
) -> "Directory":
"""Retrieves this directory plus a new directory created at the given
path.
"""
_args = [
Arg("path", path),
Arg("permissions", permissions, None),
]
_ctx = self._select("withNewDirectory", _args)
return Directory(_ctx)
[docs] @typecheck
def with_new_file(
self,
path: str,
contents: str,
permissions: Optional[int] = None,
) -> "Directory":
"""Retrieves this directory plus a new file written at the given path."""
_args = [
Arg("path", path),
Arg("contents", contents),
Arg("permissions", permissions, None),
]
_ctx = self._select("withNewFile", _args)
return Directory(_ctx)
[docs] @typecheck
def with_timestamps(self, timestamp: int) -> "Directory":
"""Retrieves this directory with all file/dir timestamps set to the given
time, in seconds from the Unix epoch.
"""
_args = [
Arg("timestamp", timestamp),
]
_ctx = self._select("withTimestamps", _args)
return Directory(_ctx)
[docs] @typecheck
def without_directory(self, path: str) -> "Directory":
"""Retrieves this directory with the directory at the given path removed."""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutDirectory", _args)
return Directory(_ctx)
[docs] @typecheck
def without_file(self, path: str) -> "Directory":
"""Retrieves this directory with the file at the given path removed."""
_args = [
Arg("path", path),
]
_ctx = self._select("withoutFile", _args)
return Directory(_ctx)
[docs]class EnvVariable(Type):
"""A simple key value object that represents an environment
variable."""
[docs] @typecheck
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.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs] @typecheck
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.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
[docs]class File(Type):
"""A file."""
[docs] @typecheck
async def contents(self) -> str:
"""Retrieves the contents 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.
"""
_args: list[Arg] = []
_ctx = self._select("contents", _args)
return await _ctx.execute(str)
[docs] @typecheck
async def export(self, path: str) -> bool:
"""Writes the file to a file path on the host.
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
"""
_args = [
Arg("path", path),
]
_ctx = self._select("export", _args)
return await _ctx.execute(bool)
[docs] @typecheck
async def id(self) -> FileID:
"""Retrieves the content-addressed identifier of the file.
Note
----
This is lazyly evaluated, no operation is actually run.
Returns
-------
FileID
A file identifier.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(FileID)
[docs] @typecheck
def secret(self) -> "Secret":
"""Retrieves a secret referencing the contents of this file."""
_args: list[Arg] = []
_ctx = self._select("secret", _args)
return Secret(_ctx)
[docs] @typecheck
async def size(self) -> int:
"""Gets 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.
"""
_args: list[Arg] = []
_ctx = self._select("size", _args)
return await _ctx.execute(int)
[docs] @typecheck
def with_timestamps(self, timestamp: int) -> "File":
"""Retrieves this file with its created/modified timestamps set to the
given time, in seconds from the Unix epoch.
"""
_args = [
Arg("timestamp", timestamp),
]
_ctx = self._select("withTimestamps", _args)
return File(_ctx)
[docs]class GitRef(Type):
"""A git ref (tag, branch or commit)."""
[docs] @typecheck
async def digest(self) -> str:
"""The digest of the current value of 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.
"""
_args: list[Arg] = []
_ctx = self._select("digest", _args)
return await _ctx.execute(str)
[docs] @typecheck
def tree(
self,
ssh_known_hosts: Optional[str] = None,
ssh_auth_socket: Optional["Socket"] = None,
) -> Directory:
"""The filesystem tree at this ref."""
_args = [
Arg("sshKnownHosts", ssh_known_hosts, None),
Arg("sshAuthSocket", ssh_auth_socket, None),
]
_ctx = self._select("tree", _args)
return Directory(_ctx)
[docs]class GitRepository(Type):
"""A git repository."""
[docs] @typecheck
def branch(self, name: str) -> GitRef:
"""Returns details on one branch."""
_args = [
Arg("name", name),
]
_ctx = self._select("branch", _args)
return GitRef(_ctx)
[docs] @typecheck
async def branches(self) -> list[str]:
"""Lists of branches on the repository.
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.
"""
_args: list[Arg] = []
_ctx = self._select("branches", _args)
return await _ctx.execute(list[str])
[docs] @typecheck
def commit(self, id: str) -> GitRef:
"""Returns details on one commit."""
_args = [
Arg("id", id),
]
_ctx = self._select("commit", _args)
return GitRef(_ctx)
[docs] @typecheck
def tag(self, name: str) -> GitRef:
"""Returns details on one tag."""
_args = [
Arg("name", name),
]
_ctx = self._select("tag", _args)
return GitRef(_ctx)
[docs]class Host(Type):
"""Information about the host execution environment."""
[docs] @typecheck
def directory(
self,
path: str,
exclude: Optional[Sequence[str]] = None,
include: Optional[Sequence[str]] = None,
) -> Directory:
"""Accesses a directory on the host."""
_args = [
Arg("path", path),
Arg("exclude", exclude, None),
Arg("include", include, None),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs] @typecheck
def env_variable(self, name: str) -> "HostVariable":
"""Accesses an environment variable on the host."""
_args = [
Arg("name", name),
]
_ctx = self._select("envVariable", _args)
return HostVariable(_ctx)
[docs] @typecheck
def unix_socket(self, path: str) -> "Socket":
"""Accesses a Unix socket on the host."""
_args = [
Arg("path", path),
]
_ctx = self._select("unixSocket", _args)
return Socket(_ctx)
[docs] @typecheck
def workdir(
self,
exclude: Optional[Sequence[str]] = None,
include: Optional[Sequence[str]] = None,
) -> Directory:
"""Retrieves the current working directory on the host.
.. deprecated::
Use :py:meth:`directory` with path set to '.' instead.
"""
_args = [
Arg("exclude", exclude, None),
Arg("include", include, None),
]
_ctx = self._select("workdir", _args)
return Directory(_ctx)
[docs]class HostVariable(Type):
"""An environment variable on the host environment."""
[docs] @typecheck
def secret(self) -> "Secret":
"""A secret referencing the value of this variable."""
_args: list[Arg] = []
_ctx = self._select("secret", _args)
return Secret(_ctx)
[docs] @typecheck
async def value(self) -> str:
"""The value of this variable.
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.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
[docs]class Label(Type):
"""A simple key value object that represents a label."""
[docs] @typecheck
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.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs] @typecheck
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.
"""
_args: list[Arg] = []
_ctx = self._select("value", _args)
return await _ctx.execute(str)
[docs]class Project(Type):
"""A set of scripts and/or extensions"""
[docs] @typecheck
def extensions(self) -> "Project":
"""extensions in this project"""
_args: list[Arg] = []
_ctx = self._select("extensions", _args)
return Project(_ctx)
[docs] @typecheck
def generated_code(self) -> Directory:
"""Code files generated by the SDKs in the project"""
_args: list[Arg] = []
_ctx = self._select("generatedCode", _args)
return Directory(_ctx)
[docs] @typecheck
async def install(self) -> bool:
"""install the project's schema
Returns
-------
bool
The `Boolean` scalar type represents `true` or `false`.
"""
_args: list[Arg] = []
_ctx = self._select("install", _args)
return await _ctx.execute(bool)
[docs] @typecheck
async def name(self) -> str:
"""name of the project
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.
"""
_args: list[Arg] = []
_ctx = self._select("name", _args)
return await _ctx.execute(str)
[docs] @typecheck
async def schema(self) -> Optional[str]:
"""schema provided by the project
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("schema", _args)
return await _ctx.execute(Optional[str])
[docs] @typecheck
async def sdk(self) -> Optional[str]:
"""sdk used to generate code for and/or execute this project
Returns
-------
Optional[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.
"""
_args: list[Arg] = []
_ctx = self._select("sdk", _args)
return await _ctx.execute(Optional[str])
[docs]class Client(Root):
[docs] @typecheck
def cache_volume(self, key: str) -> CacheVolume:
"""Constructs a cache volume for a given cache key.
Parameters
----------
key:
A string identifier to target this cache volume (e.g. "myapp-
cache").
"""
_args = [
Arg("key", key),
]
_ctx = self._select("cacheVolume", _args)
return CacheVolume(_ctx)
[docs] @typecheck
def container(
self,
id: Optional[ContainerID] = None,
platform: Optional[Platform] = None,
) -> Container:
"""Loads a container from ID.
Null ID returns an empty container (scratch).
Optional platform argument initializes new containers to execute and
publish as that platform. Platform defaults to that of the builder's
host.
"""
_args = [
Arg("id", id, None),
Arg("platform", platform, None),
]
_ctx = self._select("container", _args)
return Container(_ctx)
[docs] @typecheck
def directory(self, id: Optional[DirectoryID] = None) -> Directory:
"""Load a directory by ID. No argument produces an empty directory."""
_args = [
Arg("id", id, None),
]
_ctx = self._select("directory", _args)
return Directory(_ctx)
[docs] @typecheck
def file(self, id: FileID) -> File:
"""Loads a file by ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("file", _args)
return File(_ctx)
[docs] @typecheck
def git(
self,
url: str,
keep_git_dir: Optional[bool] = None,
) -> GitRepository:
"""Queries a git repository."""
_args = [
Arg("url", url),
Arg("keepGitDir", keep_git_dir, None),
]
_ctx = self._select("git", _args)
return GitRepository(_ctx)
[docs] @typecheck
def host(self) -> Host:
"""Queries the host environment."""
_args: list[Arg] = []
_ctx = self._select("host", _args)
return Host(_ctx)
[docs] @typecheck
def http(self, url: str) -> File:
"""Returns a file containing an http remote url content."""
_args = [
Arg("url", url),
]
_ctx = self._select("http", _args)
return File(_ctx)
[docs] @typecheck
def pipeline(
self,
name: str,
description: Optional[str] = None,
) -> "Client":
"""Creates a named sub-pipeline"""
_args = [
Arg("name", name),
Arg("description", description, None),
]
_ctx = self._select("pipeline", _args)
return Client(_ctx)
[docs] @typecheck
def project(self, name: str) -> Project:
"""Look up a project by name"""
_args = [
Arg("name", name),
]
_ctx = self._select("project", _args)
return Project(_ctx)
[docs] @typecheck
def secret(self, id: SecretID) -> "Secret":
"""Loads a secret from its ID."""
_args = [
Arg("id", id),
]
_ctx = self._select("secret", _args)
return Secret(_ctx)
[docs] @typecheck
def socket(self, id: Optional[SocketID] = None) -> "Socket":
"""Loads a socket by its ID."""
_args = [
Arg("id", id, None),
]
_ctx = self._select("socket", _args)
return Socket(_ctx)
[docs]class Secret(Type):
"""A reference to a secret value, which can be handled more safely
than the value itself."""
[docs] @typecheck
async def id(self) -> SecretID:
"""The identifier for this secret.
Note
----
This is lazyly evaluated, no operation is actually run.
Returns
-------
SecretID
A unique identifier for a secret.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(SecretID)
[docs] @typecheck
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.
"""
_args: list[Arg] = []
_ctx = self._select("plaintext", _args)
return await _ctx.execute(str)
[docs]class Socket(Type):
[docs] @typecheck
async def id(self) -> SocketID:
"""The content-addressed identifier of the socket.
Note
----
This is lazyly evaluated, no operation is actually run.
Returns
-------
SocketID
A content-addressed socket identifier.
"""
_args: list[Arg] = []
_ctx = self._select("id", _args)
return await _ctx.execute(SocketID)
__all__ = [
"CacheID",
"ContainerID",
"DirectoryID",
"FileID",
"Platform",
"SecretID",
"SocketID",
"CacheSharingMode",
"BuildArg",
"CacheVolume",
"Container",
"Directory",
"EnvVariable",
"File",
"GitRef",
"GitRepository",
"Host",
"HostVariable",
"Label",
"Project",
"Client",
"Secret",
"Socket",
]