cayu.environments.docker_toolchains

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`DOCKER_CODING_COMMAND_AUTHORITY_SCHEMA`

from cayu.environments import DOCKER_CODING_COMMAND_AUTHORITY_SCHEMA

DOCKER_CODING_COMMAND_AUTHORITY_SCHEMA = 'cayu.docker_coding_command_authority.v1'

Release source · Runtime guarantees · Capability guides

`DOCKER_CODING_TOOLCHAIN_PROFILE_SCHEMA`

from cayu.environments import DOCKER_CODING_TOOLCHAIN_PROFILE_SCHEMA

DOCKER_CODING_TOOLCHAIN_PROFILE_SCHEMA = 'cayu.docker_coding_toolchain_profile.v1'

Release source · Runtime guarantees · Capability guides

`DockerCodingAdmissionProbe`

from cayu.environments import DockerCodingAdmissionProbe

One bounded implementation-owned probe against the exact final container.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`probe_id`	`str`	`Field(max_length=128)`
`argv`	`tuple[str, ...]`	`Field(min_length=1, max_length=32)`
`expected_exit_codes`	`tuple[StrictInt, ...]`	`(0,)`
`stdout_sha256`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`timeout_seconds`	`StrictInt`	`Field(default=10, ge=1, le=60)`
`max_output_bytes`	`StrictInt`	`Field(default=16 * 1024, ge=1, le=64 * 1024)`

validate_probe_id (method)

DockerCodingAdmissionProbe.validate_probe_id(value: str) -> str

validate_argv (method)

DockerCodingAdmissionProbe.validate_argv(value: tuple[str, ...]) -> tuple[str, ...]

validate_expected_exit_codes (method)

DockerCodingAdmissionProbe.validate_expected_exit_codes(value: tuple[int, ...]) -> tuple[int, ...]

Release source · Runtime guarantees · Capability guides

`DockerCodingCommandAuthority`

from cayu.environments import DockerCodingCommandAuthority

Closed application-owned authority for one named check or structured command.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal['cayu.docker_coding_command_authority.v1']`	`Field(default=DOCKER_CODING_COMMAND_AUTHORITY_SCHEMA, alias='schema')`
`selector`	`str`	`Field(max_length=128)`
`revision`	`str`	`Field(max_length=128)`
`description`	`str`	`Field(max_length=4096)`
`exposure`	`Literal['named_check', 'structured_command']`	`required`
`executable`	`str`	`Field(max_length=4096)`
`fixed_arguments`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=32)`
`suffix_arguments`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=16)`
`allowed_flags`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=64)`
`required_flags`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=32)`
`flags_with_values`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=32)`
`path_value_flags`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=32)`
`allowed_literals`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=64)`
`allow_positional_arguments`	`StrictBool`	`False`
`positional_arguments_are_paths`	`StrictBool`	`False`
`positional_path_prefixes`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=32)`
`positional_path_suffixes`	`tuple[str, ...]`	`Field(default_factory=tuple, max_length=32)`
`allow_pytest_node_ids`	`StrictBool`	`False`
`min_arguments`	`StrictInt`	`Field(default=0, ge=0, le=MAX_STRUCTURED_COMMAND_ARGS)`
`max_arguments`	`StrictInt`	`Field(default=16, ge=0, le=MAX_STRUCTURED_COMMAND_ARGS)`
`max_argument_bytes`	`StrictInt`	`Field(default=1024, ge=1, le=MAX_STRUCTURED_COMMAND_ARG_BYTES)`
`max_total_argument_bytes`	`StrictInt`	`Field(default=8 * 1024, ge=1, le=MAX_STRUCTURED_COMMAND_TOTAL_ARG_BYTES)`
`default_working_directory`	`str`	`'.'`
`allowed_working_directories`	`tuple[str, ...]`	`('.',)`
`fixed_environment`	`tuple[DockerCodingFixedEnvironmentVariable, ...]`	`()`
`timeout_seconds`	`StrictInt`	`Field(default=60, ge=1, le=600)`
`max_output_bytes`	`StrictInt`	`Field(default=50000, ge=1, le=200000)`
`max_model_output_bytes`	`StrictInt`	`Field(default=16000, ge=256, le=50000)`
`allowed_exit_codes`	`tuple[StrictInt, ...]`	`(0,)`
`effect`	`Literal['read_only', 'workspace_mutating']`	`'read_only'`
`parallel_safe`	`StrictBool`	`False`
`idempotent`	`StrictBool`	`False`
`mutation_path_prefixes`	`tuple[str, ...]`	`()`
`dependency_sensitive`	`StrictBool`	`True`
`approval`	`Literal['ordinary', 'required']`	`'ordinary'`
`approval_expires_in_seconds`	`StrictInt \| None`	`Field(default=None, ge=1, le=86400)`

validate_selector (method)

DockerCodingCommandAuthority.validate_selector(value: str) -> str

validate_revision (method)

DockerCodingCommandAuthority.validate_revision(value: str) -> str

validate_description (method)

DockerCodingCommandAuthority.validate_description(value: str) -> str

validate_executable (method)

DockerCodingCommandAuthority.validate_executable(value: str) -> str

validate_owned_arguments (method)

DockerCodingCommandAuthority.validate_owned_arguments(value: tuple[str, ...], info) -> tuple[str, ...]

validate_flags (method)

DockerCodingCommandAuthority.validate_flags(value: tuple[str, ...], info) -> tuple[str, ...]

validate_literals (method)

DockerCodingCommandAuthority.validate_literals(value: tuple[str, ...]) -> tuple[str, ...]

validate_path_prefixes (method)

DockerCodingCommandAuthority.validate_path_prefixes(value: tuple[str, ...], info) -> tuple[str, ...]

validate_path_suffixes (method)

DockerCodingCommandAuthority.validate_path_suffixes(value: tuple[str, ...]) -> tuple[str, ...]

validate_default_working_directory (method)

DockerCodingCommandAuthority.validate_default_working_directory(value: str) -> str

validate_allowed_working_directories (method)

DockerCodingCommandAuthority.validate_allowed_working_directories(value: tuple[str, ...]) -> tuple[str, ...]

validate_fixed_environment (method)

DockerCodingCommandAuthority.validate_fixed_environment(value: tuple[DockerCodingFixedEnvironmentVariable, ...]) -> tuple[DockerCodingFixedEnvironmentVariable, ...]

validate_allowed_exit_codes (method)

DockerCodingCommandAuthority.validate_allowed_exit_codes(value: tuple[int, ...]) -> tuple[int, ...]

validate_relationships (method)

DockerCodingCommandAuthority.validate_relationships() -> DockerCodingCommandAuthority

fingerprint (property)

DockerCodingCommandAuthority.fingerprint() -> str

environment (property)

DockerCodingCommandAuthority.environment() -> dict[str, str] | None

command_argv (method)

DockerCodingCommandAuthority.command_argv(arguments: tuple[str, ...]=()) -> tuple[str, ...]

validate_model_arguments (method)

DockerCodingCommandAuthority.validate_model_arguments(arguments: tuple[str, ...]) -> tuple[str, ...]

validate_working_directory (method)

DockerCodingCommandAuthority.validate_working_directory(value: str | None) -> str

Release source · Runtime guarantees · Capability guides

`DockerCodingDependencyInput`

from cayu.environments import DockerCodingDependencyInput

One source input whose exact bytes determine toolchain freshness.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`path`	`str`	`Field(max_length=4096)`
`content_sha256`	`str`	`Field(pattern='^sha256:[0-9a-f]{64}$')`
`max_bytes`	`StrictInt`	`Field(default=MAX_DOCKER_CODING_DEPENDENCY_INPUT_BYTES, ge=1, le=MAX_DOCKER_CODING_DEPENDENCY_INPUT_BYTES)`

validate_path (method)

DockerCodingDependencyInput.validate_path(value: str) -> str

Release source · Runtime guarantees · Capability guides

`DockerCodingFixedEnvironmentVariable`

from cayu.environments import DockerCodingFixedEnvironmentVariable

One non-secret implementation-owned environment value.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`name`	`str`	`Field(max_length=128)`
`value`	`str`	`Field(max_length=4096)`

validate_name (method)

DockerCodingFixedEnvironmentVariable.validate_name(value: str) -> str

validate_value (method)

DockerCodingFixedEnvironmentVariable.validate_value(value: str) -> str

Release source · Runtime guarantees · Capability guides

`DockerCodingToolchainError`

from cayu.environments import DockerCodingToolchainError

A typed safe failure at the toolchain profile boundary.

Bases: RuntimeError.

init (method)

DockerCodingToolchainError.__init__(code: str, message: str, *, paths: tuple[str, ...]=()) -> None

path_count (property)

DockerCodingToolchainError.path_count() -> int

Return the number of affected private source paths.

paths_fingerprint (property)

DockerCodingToolchainError.paths_fingerprint() -> str

Return a stable identity without publishing repository paths.

Release source · Runtime guarantees · Capability guides

`DockerCodingToolchainProfile`

from cayu.environments import DockerCodingToolchainProfile

Versioned reconstructable authority for one exact Docker coding environment.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal['cayu.docker_coding_toolchain_profile.v1']`	`Field(default=DOCKER_CODING_TOOLCHAIN_PROFILE_SCHEMA, alias='schema')`
`profile_id`	`str`	`Field(max_length=128)`
`revision`	`str`	`Field(max_length=128)`
`image_identity`	`DockerImageIdentity`	`required`
`platform_os`	`Literal['linux']`	`'linux'`
`platform_architecture`	`Literal['amd64', 'arm64']`	`required`
`runtime_user`	`str`	`Field(default='1000:1000', max_length=64)`
`working_directory`	`str`	`'/workspace'`
`workspace_path`	`str`	`'/workspace'`
`read_only_support_paths`	`tuple[str, ...]`	`()`
`restrictions`	`DockerWorkloadRestrictions`	`Field(default_factory=DockerWorkloadRestrictions)`
`command_authorities`	`tuple[DockerCodingCommandAuthority, ...]`	`Field(default_factory=tuple, max_length=MAX_DOCKER_CODING_PROFILE_COMMANDS)`
`dependency_inputs`	`tuple[DockerCodingDependencyInput, ...]`	`Field(default_factory=tuple, max_length=MAX_DOCKER_CODING_PROFILE_DEPENDENCY_INPUTS)`
`trusted_build_context_sha256`	`str \| None`	`Field(default=None, pattern='^sha256:[0-9a-f]{64}$')`
`application_dependency_identity`	`str \| None`	`Field(default=None, max_length=256)`
`admission_probes`	`tuple[DockerCodingAdmissionProbe, ...]`	`Field(default_factory=tuple, max_length=MAX_DOCKER_CODING_PROFILE_PROBES)`
`prohibited_capabilities`	`tuple[str, ...]`	`tuple(sorted(_REQUIRED_PROHIBITED_CAPABILITIES))`
`result_publication_max_bytes`	`StrictInt`	`Field(default=50000, ge=256, le=200000)`
`redaction_behavior_version`	`str`	`'1'`
`adoption_behavior_version`	`str`	`'1'`

validate_profile_id (method)

DockerCodingToolchainProfile.validate_profile_id(value: str) -> str

validate_version (method)

DockerCodingToolchainProfile.validate_version(value: str, info) -> str

validate_application_dependency_identity (method)

DockerCodingToolchainProfile.validate_application_dependency_identity(value: str | None) -> str | None

validate_runtime_user (method)

DockerCodingToolchainProfile.validate_runtime_user(value: str) -> str

validate_absolute_workspace_path (method)

DockerCodingToolchainProfile.validate_absolute_workspace_path(value: str, info) -> str

validate_read_only_support_paths (method)

DockerCodingToolchainProfile.validate_read_only_support_paths(value: tuple[str, ...]) -> tuple[str, ...]

validate_command_authorities (method)

DockerCodingToolchainProfile.validate_command_authorities(value: tuple[DockerCodingCommandAuthority, ...]) -> tuple[DockerCodingCommandAuthority, ...]

validate_dependency_inputs (method)

DockerCodingToolchainProfile.validate_dependency_inputs(value: tuple[DockerCodingDependencyInput, ...]) -> tuple[DockerCodingDependencyInput, ...]

validate_admission_probes (method)

DockerCodingToolchainProfile.validate_admission_probes(value: tuple[DockerCodingAdmissionProbe, ...]) -> tuple[DockerCodingAdmissionProbe, ...]

validate_prohibited_capabilities (method)

DockerCodingToolchainProfile.validate_prohibited_capabilities(value: tuple[str, ...]) -> tuple[str, ...]

validate_profile_relationships (method)

DockerCodingToolchainProfile.validate_profile_relationships() -> DockerCodingToolchainProfile

fingerprint (property)

DockerCodingToolchainProfile.fingerprint() -> str

dependency_identity (property)

DockerCodingToolchainProfile.dependency_identity() -> str

required_executables (property)

DockerCodingToolchainProfile.required_executables() -> tuple[str, ...]

named_check_authorities (property)

DockerCodingToolchainProfile.named_check_authorities() -> tuple[DockerCodingCommandAuthority, ...]

structured_command_authorities (property)

DockerCodingToolchainProfile.structured_command_authorities() -> tuple[DockerCodingCommandAuthority, ...]

command_authority (method)

DockerCodingToolchainProfile.command_authority(selector: str, *, exposure: Literal['named_check', 'structured_command'] | None=None) -> DockerCodingCommandAuthority | None

evidence (method)

DockerCodingToolchainProfile.evidence() -> dict[str, object]

Return the bounded non-secret identity included in runtime receipts.

Release source · Runtime guarantees · Capability guides

`verify_docker_coding_toolchain_dependencies`

from cayu.environments import verify_docker_coding_toolchain_dependencies

Fail before dispatch when the active workspace no longer matches the profile.

async verify_docker_coding_toolchain_dependencies(profile: DockerCodingToolchainProfile, workspace: _DependencyWorkspace) -> None

Release source · Runtime guarantees · Capability guides

`verify_local_docker_coding_toolchain_dependencies`

from cayu.environments import verify_local_docker_coding_toolchain_dependencies

Verify source dependency inputs without allocating Docker resources.

verify_local_docker_coding_toolchain_dependencies(profile: DockerCodingToolchainProfile, root: Path) -> None

Release source · Runtime guarantees · Capability guides