Dockerfile builders¶

See Build a Docker image for setup, supported instructions, and differences from Docker. See Advanced usage for callbacks, cache lifetimes, and manual assembly. See Customize the SDK for parser and factory hooks.

Dockerfile parser and keyword interpreters.

Each Dockerfile directive is a DockerKeyword subclass living in its own module. parse_dockerfile returns a list of directives ready to be executed against a BuildContext/AsyncBuildContext.

class contree_sdk.docker.AddKeyword(sources=<factory>, dest='', chown='', chmod='', from_stage='')[source]¶

NAME: ClassVar[str] = 'ADD'¶

chmod: str = ''¶

chown: str = ''¶

dest: str = ''¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

from_stage: str = ''¶

classmethod parse(args_text)[source]¶

Return type:: AddKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

sources: tuple[str, ...]¶

class contree_sdk.docker.ArgKeyword(name='', default=None)[source]¶

NAME: ClassVar[str] = 'ARG'¶

default: str | None = None¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

name: str = ''¶

classmethod parse(args_text)[source]¶

Return type:: ArgKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

class contree_sdk.docker.AsyncBuildContext(client, store, local, http_fetch_async=<function http_fetch_async>, session_factory=<class 'contree_sdk.session.asyncio.ContreeAsyncSession'>, directive_executor=None, session_id='', session=None, build_args=<factory>, declared_args=<factory>, arg_defaults=<factory>, env=<factory>, workdir='/', user='', parent_hash='', stages=<factory>, stage_images=<factory>, current_stage_alias='', pending=<factory>, no_cache=False, timeout=600, last_cache_hit=False, on_event=None, progress=<factory>, upload_cache_ttl=7776000, upload_concurrency=4)[source]¶

arg_values()[source]¶

Return type:: dict[str, str]

cache_namespace(namespace)[source]¶

Return type:: str

chain(contribution)[source]¶

Return type:: str

async commit_layer(branch_name, image_uuid, *, kind, title, operation_uuid='')[source]¶

Return type:: None

create_session(client, *, session_id, store, image, node_id=None)[source]¶

Return a session from the configured factory.

Return type:: ContreeAsyncSession
Returns:: The configured session implementation.

current_stage_alias: str = ''¶

directive_executor: Callable[[DockerKeyword, AsyncBuildContext], Awaitable[None]] | None = None¶

async emit_event(event_type, *, data=b'', error=None)[source]¶

Deliver one notification through the configured build callback.

Return type:: None

async execute_directive(directive)[source]¶

Run a nested directive through the builder’s policy when configured.

Return type:: None

property file_sources: AsyncFileSources¶

async http_fetch_async(method, headers)¶

Return type:: tuple[int, Iterable[tuple[str, str]], AsyncIterable[bytes]]

last_cache_hit: bool = False¶

property last_image: str¶

no_cache: bool = False¶

on_event: Callable[[BuildEvent], object] | None = None¶

parent_hash: str = ''¶

pending_files_payload()[source]¶

Return type:: dict[str, str | Path | bytes | UploadFileSpec]

pending_repr()[source]¶

Return type:: str

async run_operation(request, *, branch)[source]¶

Stream and commit one RUN operation through the session’s public lifecycle.

Return type:: InstanceResult
Returns:: The terminal process result, including nonzero exits.
Raises:: DockerBuildError – No FROM session is active.

session: ContreeAsyncSession | None = None¶

session_factory¶: alias of ContreeAsyncSession

session_id: str = ''¶

state_repr()[source]¶

Return type:: str

substitute(text)[source]¶

Return type:: str

timeout: int = 600¶

async try_cache_hit(branch_name, *, kind='run')[source]¶

Return type:: str | None

upload_cache_ttl: float = 7776000¶

upload_concurrency: int = 4¶

user: str = ''¶

workdir: str = '/'¶

client: ContreeAsyncClient¶

store: AsyncStore¶

local: LocalContext¶

build_args: dict[str, str]¶

declared_args: set[str]¶

arg_defaults: dict[str, str]¶

env: dict[str, str]¶

stages: dict[str, str]¶

stage_images: list[str]¶

pending: list[PendingFile]¶

progress: BuildProgress¶

class contree_sdk.docker.BuildContext(client, store, local, http_fetch=<function http_fetch>, session_factory=<class 'contree_sdk.session.sync.ContreeSession'>, directive_executor=None, session_id='', session=None, build_args=<factory>, declared_args=<factory>, arg_defaults=<factory>, env=<factory>, workdir='/', user='', parent_hash='', stages=<factory>, stage_images=<factory>, current_stage_alias='', pending=<factory>, no_cache=False, timeout=600, last_cache_hit=False, on_event=None, progress=<factory>, upload_cache_ttl=7776000, upload_concurrency=4)[source]¶

arg_values()[source]¶

Return type:: dict[str, str]

cache_namespace(namespace)[source]¶

Return type:: str

chain(contribution)[source]¶

Return type:: str

commit_layer(branch_name, image_uuid, *, kind, title, operation_uuid='')[source]¶

Return type:: None

create_session(client, *, session_id, store, image, node_id=None)[source]¶

Return a session from the configured factory.

Return type:: ContreeSession
Returns:: The configured session implementation.

current_stage_alias: str = ''¶

directive_executor: Callable[[DockerKeyword, BuildContext], None] | None = None¶

emit_event(event_type, *, data=b'', error=None)[source]¶

Deliver one notification through the configured build callback.

Return type:: None

execute_directive(directive)[source]¶

Run a nested directive through the builder’s policy when configured.

Return type:: None

property file_sources: SyncFileSources¶

http_fetch(method, headers)¶

Return type:: tuple[int, Iterable[tuple[str, str]], Iterable[bytes]]

last_cache_hit: bool = False¶

property last_image: str¶

no_cache: bool = False¶

on_event: Callable[[BuildEvent], None] | None = None¶

parent_hash: str = ''¶

pending_files_payload()[source]¶

Return type:: dict[str, str | Path | bytes | UploadFileSpec]

pending_repr()[source]¶

Return type:: str

run_operation(request, *, branch)[source]¶

Stream and commit one RUN operation through the session’s public lifecycle.

Return type:: InstanceResult
Returns:: The terminal process result, including nonzero exits.
Raises:: DockerBuildError – No FROM session is active.

session: ContreeSession | None = None¶

session_factory¶: alias of ContreeSession

session_id: str = ''¶

state_repr()[source]¶

Return type:: str

substitute(text)[source]¶

Return type:: str

timeout: int = 600¶

try_cache_hit(branch_name, *, kind='run')[source]¶

Return type:: str | None

upload_cache_ttl: float = 7776000¶

upload_concurrency: int = 4¶

user: str = ''¶

workdir: str = '/'¶

client: ContreeSyncClient¶

store: SyncStore¶

local: LocalContext¶

build_args: dict[str, str]¶

declared_args: set[str]¶

arg_defaults: dict[str, str]¶

env: dict[str, str]¶

stages: dict[str, str]¶

stage_images: list[str]¶

pending: list[PendingFile]¶

progress: BuildProgress¶

class contree_sdk.docker.BuildEvent(*, type, step, operation_uuid=None, image_before=None, image_after=None, duration=0.0, data=b'', result=None, error=None)[source]¶

A build notification with raw output bytes and the current operation identity.

result is available after the operation finishes, including nonzero exits. Errors retain their original exception object. Output is never decoded or formatted.

data: bytes = b''¶

duration: float = 0.0¶

error: BaseException | None = None¶

image_after: str | None = None¶

image_before: str | None = None¶

operation_uuid: str | None = None¶

result: InstanceResult | None = None¶

type: Literal['step_started', 'operation_started', 'stdout', 'stderr', 'cache_hit', 'step_completed', 'step_failed']¶

step: BuildStep¶

class contree_sdk.docker.BuildRequest(*, context_dir, dockerfile_path, session_id, build_args=<factory>, no_cache=False, timeout=600)[source]¶

Resolved local inputs and options for one build context.

no_cache: bool = False¶

timeout: int = 600¶

context_dir: Path¶

dockerfile_path: Path¶

session_id: str¶

build_args: dict[str, str]¶

class contree_sdk.docker.BuildStep(id, keyword, index=None, parent_id=None)[source]¶

One directive execution; IDs start at zero within each build.

index is the parsed Dockerfile position, or None for a synthetic step. parent_id identifies the enclosing directive for nested execution.

index: int | None = None¶

parent_id: int | None = None¶

id: int¶

keyword: str¶

class contree_sdk.docker.BuildStepEvent(index, keyword, cache_hit, image_before, image_after, duration, error=None)[source]¶

Reported to on_step around each directive’s execute()/execute_async() call.

error: BaseException | None = None¶

index: int¶

keyword: str¶

cache_hit: bool¶

image_before: str | None¶

image_after: str | None¶

duration: float¶

class contree_sdk.docker.ContreeAsyncDockerBuilder(client, *, store=None, http_fetch_async=None, parser=None, session_factory=None)[source]¶

Build a Dockerfile from context.

Applies each directive against a content-addressed layer cache keyed by the build’s session.

async build(context, *, dockerfile=None, tag=None, build_args=None, no_cache=False, timeout=600, session_id=None, on_event=None, on_step=None)[source]¶

Return type:: str

context_class¶: alias of AsyncBuildContext

async create_context(request)[source]¶

Construct per-build state using the public context and session factories.

Return type:: AsyncBuildContext
Returns:: A context owned by this build invocation.

async execute_directive(directive, context)[source]¶

Execute one directive. Override for policy checks or instrumentation.

Return type:: None

async finalize(context)[source]¶

Commit pending file attachments through the same directive execution hook.

Return type:: None

parse(text)[source]¶

Return build directives through the configured parser.

Return type:: list[DockerKeyword]
Returns:: The parsed directives in source order.

async run_step(directive, context, *, index=None)[source]¶

Report one directive execution, including nested and synthetic steps.

Return type:: None

property session: ContreeAsyncSession | None¶

class contree_sdk.docker.ContreeDockerBuilder(client, *, store=None, http_fetch=None, parser=None, session_factory=None)[source]¶

Build a Dockerfile from context.

Applies each directive against a content-addressed layer cache keyed by the build’s session.

build(context, *, dockerfile=None, tag=None, build_args=None, no_cache=False, timeout=600, session_id=None, on_event=None, on_step=None)[source]¶

Return type:: str

context_class¶: alias of BuildContext

create_context(request)[source]¶

Construct per-build state using the public context and session factories.

Return type:: BuildContext
Returns:: A context owned by this build invocation.

execute_directive(directive, context)[source]¶

Execute one directive. Override for policy checks or instrumentation.

Return type:: None

finalize(context)[source]¶

Commit pending file attachments through the same directive execution hook.

Return type:: None

parse(text)[source]¶

Return build directives through the configured parser.

Return type:: list[DockerKeyword]
Returns:: The parsed directives in source order.

run_step(directive, context, *, index=None)[source]¶

Report one directive execution, including nested and synthetic steps.

Return type:: None

property session: ContreeSession | None¶

class contree_sdk.docker.CopyKeyword(sources=<factory>, dest='', chown='', chmod='', from_stage='')[source]¶

NAME: ClassVar[str] = 'COPY'¶

chmod: str = ''¶

chown: str = ''¶

dest: str = ''¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

from_stage: str = ''¶

classmethod parse(args_text)[source]¶

Return type:: CopyKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

sources: tuple[str, ...]¶

class contree_sdk.docker.DockerKeyword[source]¶

Base class. Subclasses implement parse, serialize, execute.

NAME: ClassVar[str] = ''¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

classmethod parse(args_text)[source]¶

Return type:: DockerKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

class contree_sdk.docker.DockerfileParser(*, keywords=None, skipped=None)[source]¶

A per-instance directive registry. Subclass or register custom DockerKeyword classes.

parse(text)[source]¶

Return directives using this parser’s registry.

Return type:: list[DockerKeyword]
Returns:: The parsed directives in source order.
Raises:: ValueError – A directive is unknown or has invalid arguments.

register(keyword)[source]¶

Return type:: None

class contree_sdk.docker.DockerignoreRule(negate, regex, raw)[source]¶

One compiled .dockerignore line.

negate: bool¶

regex: Pattern[str]¶

raw: str¶

class contree_sdk.docker.EnvKeyword(pairs=<factory>)[source]¶

NAME: ClassVar[str] = 'ENV'¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

classmethod parse(args_text)[source]¶

Return type:: EnvKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

pairs: tuple[tuple[str, str], ...]¶

class contree_sdk.docker.FromKeyword(image_ref='', alias='')[source]¶

NAME: ClassVar[str] = 'FROM'¶

alias: str = ''¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

image_ref: str = ''¶

classmethod parse(args_text)[source]¶

Return type:: FromKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

class contree_sdk.docker.LocalContext(root, dockerignore=<factory>)[source]¶

Read-only handle for the local build context directory.

collect(sources, dest, *, uid, gid, mode_override)[source]¶

Return type:: list[MappedFile]

classmethod from_dir(root)[source]¶

Return type:: LocalContext

is_ignored(rel_path)[source]¶

Return type:: bool

walk(host_path, dest, sources, uid, gid, mode_override)[source]¶

Return type:: list[MappedFile]

walk_dir(host_path, dest, uid, gid, mode_override)[source]¶

Return type:: list[MappedFile]

walk_file(host_path, dest, sources, uid, gid, mode_override)[source]¶

Return type:: list[MappedFile]

root: Path¶

dockerignore: tuple[DockerignoreRule, ...]¶

class contree_sdk.docker.PendingFile(instance_path, file_uuid, sha256, uid, gid, mode)[source]¶

instance_path: str¶

file_uuid: str¶

sha256: str¶

uid: int¶

gid: int¶

mode: str¶

class contree_sdk.docker.RunKeyword(parts=<factory>, shell_form=True)[source]¶

NAME: ClassVar[str] = 'RUN'¶

build_request(ctx)[source]¶

Prepare the command for the context’s operation execution hook.

Return type:: RunRequest
Returns:: A non-disposable request with the current build state and attachments.

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

classmethod parse(args_text)[source]¶

Return type:: RunKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

shell_form: bool = True¶

parts: tuple[str, ...]¶

class contree_sdk.docker.SkippedKeyword(name='', raw='')[source]¶

NAME: ClassVar[str] = ''¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

name: str = ''¶

classmethod of(name, raw)[source]¶

Return type:: SkippedKeyword

classmethod parse(args_text)¶

Return type:: DockerKeyword

raw: str = ''¶

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

class contree_sdk.docker.UserKeyword(spec='')[source]¶

NAME: ClassVar[str] = 'USER'¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

classmethod parse(args_text)[source]¶

Return type:: UserKeyword

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

spec: str = ''¶

class contree_sdk.docker.WorkdirKeyword(path='')[source]¶

NAME: ClassVar[str] = 'WORKDIR'¶

execute(ctx)[source]¶

Return type:: None

async execute_async(ctx)[source]¶

Return type:: None

classmethod parse(args_text)[source]¶

Return type:: WorkdirKeyword

path: str = ''¶

serialize()[source]¶

Stable text used for layer hashing.

Return type:: str

contree_sdk.docker.is_ignored(rel_path, rules)[source]¶

Return type:: bool

contree_sdk.docker.parse_dockerfile(text)[source]¶

Return type:: list[DockerKeyword]

contree_sdk.docker.parse_dockerignore(context_dir)[source]¶

Return type:: tuple[DockerignoreRule, ...]

contree_sdk.docker.substitute(text, env)[source]¶

Return type:: str