Connection

dagger.connection(config: Config | None = None)

Connect to a Dagger Engine using the global client.

This is similar to dagger.Connection but uses a global client (dagger.dag) so there’s no need to pass around a client instance with this.

Example:

import dagger
from dagger import dag


async def main():
    async with dagger.connection():
        ctr = dag.container().from_("alpine")

    # Connection is closed when leaving the context manager's scope.

You can stream the logs from the engine to see progress:

import sys
import anyio
import dagger
from dagger import dag


async def main():
    cfg = dagger.Config(log_output=sys.stderr)

    async with dagger.connection(cfg):
        ctr = dag.container().from_("python:3.11.1-alpine")
        version = await ctr.with_exec(["python", "-V"]).stdout()

    print(version)
    # Output: Python 3.11.1


anyio.run(main)

class dagger.Connection(config: Config | None = None)

Connect to a Dagger Engine with an isolated client (legacy).

This is an older version of dagger.connection() that uses an isolated client instance. Should no longer be used in newer projects unless there’s a specific reason to do so.

Example:

import dagger


async def main():
    async with dagger.Connection() as client:
        ctr = client.container().from_("alpine")

You can stream the logs from the engine to see progress:

import sys
import anyio
import dagger


async def main():
    cfg = dagger.Config(log_output=sys.stderr)

    async with dagger.Connection(cfg) as client:
        ctr = client.container().from_("python:3.11.1-alpine")
        version = await ctr.with_exec(["python", "-V"]).stdout()

    print(version)
    # Output: Python 3.11.1


anyio.run(main)

class dagger.Config(*, timeout: ~dagger.Timeout | None = <factory>, retry: ~dagger.Retry | None = <factory>, workdir: ~os.PathLike[str] | str = '', config_path: ~os.PathLike[str] | str = '', log_output: ~typing.TextIO | None = None, execute_timeout: ~typing.Any = <object object>)

Options for connecting to the Dagger engine.

Parameters:

• timeout (dagger.Timeout | None) – The maximum time in seconds for establishing a connection to the server, or None to disable. Defaults to 10 seconds.

• retry (dagger.Retry | None) – Retry parameters for connecting to the Dagger API server.

• workdir (os.PathLike[str] | str) – The host workdir loaded into dagger.

• config_path (os.PathLike[str] | str) – Project config file.

• log_output (TextIO | None) – A TextIO object to send the logs from the engine.

• execute_timeout (Any) – The maximum time in seconds for the execution of a request before an ExecuteTimeoutError is raised. Passing None results in waiting forever for a response (default).

class dagger.Timeout(timeout: float | None | ~typing.Tuple[float | None, float | None, float | None, float | None] | ~httpx.Timeout | ~httpx._config.UnsetType = <httpx._config.UnsetType object>, *, connect: None | float | ~httpx._config.UnsetType = <httpx._config.UnsetType object>, read: None | float | ~httpx._config.UnsetType = <httpx._config.UnsetType object>, write: None | float | ~httpx._config.UnsetType = <httpx._config.UnsetType object>, pool: None | float | ~httpx._config.UnsetType = <httpx._config.UnsetType object>)

Timeout configuration.

Examples:

Timeout(None)  # No timeouts.
Timeout(5.0)  # 5s timeout on all operations.
Timeout(None, connect=5.0)  # 5s timeout on connect, no other timeouts.
Timeout(5.0, connect=10.0)  # 10s timeout on connect. 5s timeout elsewhere.
Timeout(5.0, pool=None)  # No timeout on acquiring connection from pool.

class dagger.Retry(*, connect: bool | Callable[[_CallableT], _CallableT] = True, execute: bool | Callable[[_CallableT], _CallableT] = True)

Retry parameters for connecting to the Dagger API server.