Dockerfile builders - Nebius Token Factory documentation

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 AddKeyword`

class contree_sdk.docker.AddKeyword(sources, dest, chown, chmod, from_stage)

Attributes

ClassVar[str]

str

tuple[str, ...]

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> AddKeyword

required

AddKeyword

AddKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class ArgKeyword`

class contree_sdk.docker.ArgKeyword(name, default)

Attributes

ClassVar[str]

str | None

str

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> ArgKeyword

required

ArgKeyword

ArgKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class AsyncBuildContext`

class contree_sdk.docker.AsyncBuildContext(client, store, local, http_fetch_async, session_factory, directive_executor, session_id, session, build_args, declared_args, arg_defaults, env, workdir, user, parent_hash, stages, stage_images, current_stage_alias, pending, no_cache, timeout, last_cache_hit, on_event, progress, upload_cache_ttl, upload_concurrency)

Attributes

str

Callable[[DockerKeyword, AsyncBuildContext], Awaitable[None]] | None

Callable[[DockerKeyword, AsyncBuildContext], Awaitable[None]] | None

AsyncFileSources

AsyncFileSources

bool

str

bool

Callable[[BuildEvent], object] | None

Callable[[BuildEvent], object] | None

str

ContreeAsyncSession | None

ContreeAsyncSession | None

alias of ContreeAsyncSession

str

int

float

int

str

ContreeAsyncClient

AsyncStore

AsyncStore

LocalContext

LocalContext

dict[str, str]

set[str]

dict[str, str]

list[str]

list[PendingFile]

list[PendingFile]

BuildProgress

Methods

`arg_values()`

def arg_values() -> dict[str, str]

dict[str, str]

`cache_namespace()`

def cache_namespace(namespace) -> str

required

str

`chain()`

def chain(contribution) -> str

required

str

`commit_layer()`

async def commit_layer(branch_name, image_uuid, *, kind, title, operation_uuid) -> None

required

default:"''"

None

`create_session()`

def create_session(client, *, session_id, store, image, node_id) -> ContreeAsyncSession

Return a session from the configured factory.

required

default:"None"

ContreeAsyncSession

ContreeAsyncSessionThe configured session implementation.

`emit_event()`

async def emit_event(event_type, *, data, error) -> None

Deliver one notification through the configured build callback.

required

default:"b''"

default:"None"

None

`execute_directive()`

async def execute_directive(directive) -> None

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

required

None

`http_fetch_async()`

async def http_fetch_async(method, headers) -> tuple[int, Iterable[tuple[str, str]], AsyncIterable[bytes]]

required

tuple[int, Iterable[tuple[str, str]], AsyncIterable[bytes]]

`pending_files_payload()`

def pending_files_payload() -> dict[str, str | Path | bytes | UploadFileSpec]

dict[str, str | Path | bytes | UploadFileSpec]

dict[str, str | Path | bytes | UploadFileSpec]

`pending_repr()`

def pending_repr() -> str

str

`run_operation()`

async def run_operation(request, *, branch) -> InstanceResult

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

required

InstanceResult

The terminal process result, including nonzero exits.

DockerBuildError – No FROM session is active.

`state_repr()`

def state_repr() -> str

str

`substitute()`

def substitute(text) -> str

required

str

`try_cache_hit()`

async def try_cache_hit(branch_name, *, kind) -> str | None

required

default:"'run'"

str | None

`class BuildContext`

class contree_sdk.docker.BuildContext(client, store, local, http_fetch, session_factory, directive_executor, session_id, session, build_args, declared_args, arg_defaults, env, workdir, user, parent_hash, stages, stage_images, current_stage_alias, pending, no_cache, timeout, last_cache_hit, on_event, progress, upload_cache_ttl, upload_concurrency)

Attributes

str

Callable[[DockerKeyword, BuildContext], None] | None

Callable[[DockerKeyword, BuildContext], None] | None

SyncFileSources

SyncFileSources

bool

str

bool

Callable[[BuildEvent], None] | None

Callable[[BuildEvent], None] | None

str

ContreeSession | None

ContreeSession | None

alias of ContreeSession

str

int

float

int

str

ContreeSyncClient

SyncStore

SyncStore

LocalContext

LocalContext

dict[str, str]

set[str]

dict[str, str]

list[str]

list[PendingFile]

list[PendingFile]

BuildProgress

Methods

`arg_values()`

def arg_values() -> dict[str, str]

dict[str, str]

`cache_namespace()`

def cache_namespace(namespace) -> str

required

str

`chain()`

def chain(contribution) -> str

required

str

`commit_layer()`

def commit_layer(branch_name, image_uuid, *, kind, title, operation_uuid) -> None

required

default:"''"

None

`create_session()`

def create_session(client, *, session_id, store, image, node_id) -> ContreeSession

Return a session from the configured factory.

required

default:"None"

ContreeSession

ContreeSessionThe configured session implementation.

`emit_event()`

def emit_event(event_type, *, data, error) -> None

Deliver one notification through the configured build callback.

required

default:"b''"

default:"None"

None

`execute_directive()`

def execute_directive(directive) -> None

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

required

None

`http_fetch()`

def http_fetch(method, headers) -> tuple[int, Iterable[tuple[str, str]], Iterable[bytes]]

required

tuple[int, Iterable[tuple[str, str]], Iterable[bytes]]

`pending_files_payload()`

def pending_files_payload() -> dict[str, str | Path | bytes | UploadFileSpec]

dict[str, str | Path | bytes | UploadFileSpec]

dict[str, str | Path | bytes | UploadFileSpec]

`pending_repr()`

def pending_repr() -> str

str

`run_operation()`

def run_operation(request, *, branch) -> InstanceResult

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

required

InstanceResult

The terminal process result, including nonzero exits.

DockerBuildError – No FROM session is active.

`state_repr()`

def state_repr() -> str

str

`substitute()`

def substitute(text) -> str

required

str

`try_cache_hit()`

def try_cache_hit(branch_name, *, kind) -> str | None

required

default:"'run'"

str | None

`class BuildEvent`

class contree_sdk.docker.BuildEvent(*, type, step, operation_uuid, image_before, image_after, duration, data, result, error)

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.

Attributes

bytes

float

BaseException | None

str | None

InstanceResult | None

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

BuildStep

BuildStep

`class BuildRequest`

class contree_sdk.docker.BuildRequest(*, context_dir, dockerfile_path, session_id, build_args, no_cache, timeout)

Resolved local inputs and options for one build context.

Attributes

bool

int

Path

str

dict[str, str]

`class BuildStep`

class contree_sdk.docker.BuildStep(id, keyword, index, parent_id)

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.

Attributes

int | None

int

str

`class BuildStepEvent`

class contree_sdk.docker.BuildStepEvent(index, keyword, cache_hit, image_before, image_after, duration, error)

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

Attributes

BaseException | None

int

str

bool

str | None

float

`class ContreeAsyncDockerBuilder`

class contree_sdk.docker.ContreeAsyncDockerBuilder(client, *, store, http_fetch_async, parser, session_factory)

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

Attributes

alias of AsyncBuildContext

ContreeAsyncSession | None

ContreeAsyncSession | None

Methods

`build()`

async def build(context, *, dockerfile, tag, build_args, no_cache, timeout, session_id, on_event, on_step) -> str

required

default:"None"

default:"False"

default:"600"

default:"None"

str

`create_context()`

async def create_context(request) -> AsyncBuildContext

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

required

AsyncBuildContext

AsyncBuildContextA context owned by this build invocation.

`execute_directive()`

async def execute_directive(directive, context) -> None

Execute one directive. Override for policy checks or instrumentation.

required

None

`finalize()`

async def finalize(context) -> None

Commit pending file attachments through the same directive execution hook.

required

None

`parse()`

def parse(text) -> list[DockerKeyword]

Return build directives through the configured parser.

required

list[DockerKeyword]

list[DockerKeyword]The parsed directives in source order.

`run_step()`

async def run_step(directive, context, *, index) -> None

Report one directive execution, including nested and synthetic steps.

required

default:"None"

None

`class ContreeDockerBuilder`

class contree_sdk.docker.ContreeDockerBuilder(client, *, store, http_fetch, parser, session_factory)

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

Attributes

alias of BuildContext

ContreeSession | None

ContreeSession | None

Methods

`build()`

def build(context, *, dockerfile, tag, build_args, no_cache, timeout, session_id, on_event, on_step) -> str

required

default:"None"

default:"False"

default:"600"

default:"None"

str

`create_context()`

def create_context(request) -> BuildContext

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

required

BuildContext

BuildContextA context owned by this build invocation.

`execute_directive()`

def execute_directive(directive, context) -> None

Execute one directive. Override for policy checks or instrumentation.

required

None

`finalize()`

def finalize(context) -> None

Commit pending file attachments through the same directive execution hook.

required

None

`parse()`

def parse(text) -> list[DockerKeyword]

Return build directives through the configured parser.

required

list[DockerKeyword]

list[DockerKeyword]The parsed directives in source order.

`run_step()`

def run_step(directive, context, *, index) -> None

Report one directive execution, including nested and synthetic steps.

required

default:"None"

None

`class CopyKeyword`

class contree_sdk.docker.CopyKeyword(sources, dest, chown, chmod, from_stage)

Attributes

ClassVar[str]

str

tuple[str, ...]

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> CopyKeyword

required

CopyKeyword

CopyKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class DockerKeyword`

class contree_sdk.docker.DockerKeyword()

Base class. Subclasses implement parse, serialize, execute.

Attributes

ClassVar[str]

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> DockerKeyword

required

DockerKeyword

DockerKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class DockerfileParser`

class contree_sdk.docker.DockerfileParser(*, keywords, skipped)

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

Methods

`parse()`

def parse(text) -> list[DockerKeyword]

Return directives using this parser’s registry.

required

list[DockerKeyword]

list[DockerKeyword]The parsed directives in source order.

ValueError – A directive is unknown or has invalid arguments.

`register()`

def register(keyword) -> None

required

None

`class DockerignoreRule`

class contree_sdk.docker.DockerignoreRule(negate, regex, raw)

One compiled .dockerignore line.

Attributes

bool

Pattern[str]

str

`class EnvKeyword`

class contree_sdk.docker.EnvKeyword(pairs)

Attributes

ClassVar[str]

tuple[tuple[str, str], ...]

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> EnvKeyword

required

EnvKeyword

EnvKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class FromKeyword`

class contree_sdk.docker.FromKeyword(image_ref, alias)

Attributes

ClassVar[str]

str

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> FromKeyword

required

FromKeyword

FromKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class LocalContext`

class contree_sdk.docker.LocalContext(root, dockerignore)

Read-only handle for the local build context directory.

Attributes

Path

tuple[DockerignoreRule, ...]

tuple[DockerignoreRule, …]

Methods

`collect()`

def collect(sources, dest, *, uid, gid, mode_override) -> list[MappedFile]

required

list[MappedFile]

`from_dir()`

@classmethod
def from_dir(root) -> LocalContext

required

LocalContext

LocalContext

`is_ignored()`

def is_ignored(rel_path) -> bool

required

bool

`walk()`

def walk(host_path, dest, sources, uid, gid, mode_override) -> list[MappedFile]

required

list[MappedFile]

`walk_dir()`

def walk_dir(host_path, dest, uid, gid, mode_override) -> list[MappedFile]

required

list[MappedFile]

`walk_file()`

def walk_file(host_path, dest, sources, uid, gid, mode_override) -> list[MappedFile]

required

list[MappedFile]

`class PendingFile`

class contree_sdk.docker.PendingFile(instance_path, file_uuid, sha256, uid, gid, mode)

Attributes

str

int

str

`class RunKeyword`

class contree_sdk.docker.RunKeyword(parts, shell_form)

Attributes

ClassVar[str]

bool

tuple[str, ...]

Methods

`build_request()`

def build_request(ctx) -> RunRequest

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

required

RunRequest

RunRequestA non-disposable request with the current build state and attachments.

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> RunKeyword

required

RunKeyword

RunKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class SkippedKeyword`

class contree_sdk.docker.SkippedKeyword(name, raw)

Attributes

ClassVar[str]

str

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`of()`

@classmethod
def of(name, raw) -> SkippedKeyword

required

SkippedKeyword

SkippedKeyword

`parse()`

@classmethod
def parse(args_text) -> DockerKeyword

required

DockerKeyword

DockerKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class UserKeyword`

class contree_sdk.docker.UserKeyword(spec)

Attributes

ClassVar[str]

str

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> UserKeyword

required

UserKeyword

UserKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`class WorkdirKeyword`

class contree_sdk.docker.WorkdirKeyword(path)

Attributes

ClassVar[str]

str

Methods

`execute()`

def execute(ctx) -> None

required

None

`execute_async()`

async def execute_async(ctx) -> None

required

None

`parse()`

@classmethod
def parse(args_text) -> WorkdirKeyword

required

WorkdirKeyword

WorkdirKeyword

`serialize()`

def serialize() -> str

Stable text used for layer hashing.

str

`is_ignored()`

def contree_sdk.docker.is_ignored(rel_path, rules) -> bool

required

bool

`parse_dockerfile()`

def contree_sdk.docker.parse_dockerfile(text) -> list[DockerKeyword]

required

list[DockerKeyword]

list[DockerKeyword]

`parse_dockerignore()`

def contree_sdk.docker.parse_dockerignore(context_dir) -> tuple[DockerignoreRule, ...]

required

tuple[DockerignoreRule, ...]

tuple[DockerignoreRule, …]

`substitute()`

def contree_sdk.docker.substitute(text, env) -> str

required

str

​class AddKeyword

​Attributes

​Methods

​execute()

​execute_async()

​parse()

​serialize()

​class ArgKeyword

​Attributes

​Methods

​execute()

​execute_async()

​parse()

​serialize()

​class AsyncBuildContext

​Attributes

​Methods

​arg_values()

​cache_namespace()

​chain()

​commit_layer()

​create_session()

​emit_event()

​execute_directive()

​http_fetch_async()

​pending_files_payload()

​pending_repr()

​run_operation()

​state_repr()

​substitute()

​try_cache_hit()

​class BuildContext

​Attributes

​Methods

​arg_values()

​cache_namespace()

​chain()

​commit_layer()

​create_session()

​emit_event()

​execute_directive()

​http_fetch()

​pending_files_payload()

​pending_repr()

​run_operation()

​state_repr()

​substitute()

​try_cache_hit()

​class BuildEvent

​Attributes

​class BuildRequest

​Attributes

​class BuildStep

​Attributes

​class BuildStepEvent

​Attributes

​class ContreeAsyncDockerBuilder

​Attributes

​Methods

​build()

​create_context()

​execute_directive()

​finalize()

​parse()

​run_step()

​class ContreeDockerBuilder

​Attributes

​Methods

​build()

​create_context()

​execute_directive()

​finalize()

​parse()

​run_step()

​class CopyKeyword

​Attributes

​Methods

​execute()

​execute_async()

​parse()

`class AddKeyword`

Attributes

Methods

`execute()`

`execute_async()`

`parse()`

`serialize()`

`class ArgKeyword`

Attributes

Methods

`execute()`

`execute_async()`

`parse()`

`serialize()`

`class AsyncBuildContext`

Attributes

Methods

`arg_values()`

`cache_namespace()`

`chain()`

`commit_layer()`

`create_session()`

`emit_event()`

`execute_directive()`

`http_fetch_async()`

`pending_files_payload()`

`pending_repr()`

`run_operation()`

`state_repr()`

`substitute()`

`try_cache_hit()`

`class BuildContext`

Attributes

Methods

`arg_values()`

`cache_namespace()`

`chain()`

`commit_layer()`

`create_session()`

`emit_event()`

`execute_directive()`

`http_fetch()`

`pending_files_payload()`

`pending_repr()`

`run_operation()`

`state_repr()`

`substitute()`

`try_cache_hit()`

`class BuildEvent`

Attributes

`class BuildRequest`

Attributes

`class BuildStep`

Attributes

`class BuildStepEvent`

Attributes

`class ContreeAsyncDockerBuilder`

Attributes

Methods

`build()`

`create_context()`

`execute_directive()`

`finalize()`

`parse()`

`run_step()`

`class ContreeDockerBuilder`

Attributes

Methods

`build()`

`create_context()`

`execute_directive()`

`finalize()`

`parse()`

`run_step()`

`class CopyKeyword`

Attributes

Methods

`execute()`

`execute_async()`

`parse()`