duck.cli.commands.sync.sync

Orchestrates a full duck sync run: load config, detect the environment, diff installed vs required dependencies, then install what is missing.

Module Contents

Classes

DuckSync

Reads a project’s duck.toml and brings the local environment in line with it.

SyncReport

Summary of what a sync run found and did.

API

class duck.cli.commands.sync.sync.DuckSync(config_path: pathlib.Path | None = None, include_dev: bool = False, dev_only: bool = False, dry_run: bool = False, python_extra_args: list[str] | None = None, system_extra_args: list[str] | None = None, use_sudo: bool | None = None, force_backend: str | None = None)[source]

Reads a project’s duck.toml and brings the local environment in line with it.

Parameters:

  • config_path – Explicit duck.toml path, auto discovered when omitted.

  • include_dev – Whether to also sync the [development] group.

  • dev_only – Whether to also sync the [development] group.

  • dry_run – When True, prints planned actions without installing.

  • python_extra_args – Extra CLI args appended on top of duck.toml’s python_args, useful for one-off runs (e.g. –extra-index-url).

  • system_extra_args – Extra CLI args appended on top of duck.toml’s system_args.

  • use_sudo – Whether system installs should be prefixed with sudo. None defers to duck.toml’s [sync] setting, which itself defaults to auto-detect (skip sudo when already root).

  • force_backend – Override auto-detection with a specific backend. Accepts any value recognised by :func:~duck_sync.backends.get_backend: a known identifier ("apt", "brew", "pacman" …) or a raw shell-style install command ("some_command -i"). When omitted, the backend is detected from the host platform.

Initialization

active_groups() → list[duck.cli.commands.sync.config.DependencyGroup][source]
Returns:

The active dependency groups based on the selected mode.

collect_targets() → tuple[list[str], list[str]][source]

Flattens the active groups’ python and system package lists.

Returns:

A (python_packages, system_packages) tuple with duplicates removed.

on_install_failed(package: str, reason: str) → None[source]

Called when a dependency fails to install.

Parameters:

  • package – The package that failed.

  • reason – Human-readable failure reason.

on_install_finished(package: str) → None[source]

Called after a dependency has been installed successfully.

Parameters:

package – The package that was installed.

on_install_started(package: str) → None[source]

Called immediately before a dependency installation begins.

Parameters:

package – The package about to be installed.

python_args_for(package: str) → list[str][source]

Builds the full extra-args list for one python package install.

Order is duck.toml group args, then that package’s own override, then CLI-supplied args, so CLI flags always win last.

Parameters:

package – Python package name.

Returns:

The merged list of extra CLI args to pass to pip/uv.

resolve_use_sudo(use_sudo: bool | None) → bool[source]

Decides whether sudo should prefix system install commands.

Precedence: an explicit use_sudo argument wins, then duck.toml’s [sync] use_sudo setting, then auto-detection based on the current user.

Parameters:

use_sudo – The explicit override passed to DuckSync, if any.

Returns:

True if install commands should be prefixed with sudo.

run() → duck.cli.commands.sync.sync.SyncReport[source]

Executes the full sync: system packages, then python packages, then requirements files.

Returns:

A SyncReport describing what happened.

sync_python_package(package: str, report: duck.cli.commands.sync.sync.SyncReport) → None[source]

Ensures a single python package is installed, updating report in place.

Parameters:

  • package – Python package name.

  • report – Report accumulator for this sync run.

sync_requirements_file(group: duck.cli.commands.sync.config.DependencyGroup, report: duck.cli.commands.sync.sync.SyncReport) → None[source]

Installs a group’s requirements.txt, if one is declared.

pip/uv already skip packages that satisfy pinned versions, so this always runs rather than pre-checking each line individually.

Parameters:

  • group – The dependency group that may declare a requirements file.

  • report – Report accumulator for this sync run.

sync_system_package(generic_name: str, report: duck.cli.commands.sync.sync.SyncReport) → None[source]

Ensures a single system package is installed, updating report in place.

Parameters:

  • generic_name – Name as written in duck.toml, e.g. “gdal”.

  • report – Report accumulator for this sync run.

system_args_for(generic_name: str) → list[str][source]

Builds the full extra-args list for one system package install.

Parameters:

generic_name – Name as written in duck.toml, e.g. “gdal”.

Returns:

The merged list of extra CLI args to pass to the OS package manager.

class duck.cli.commands.sync.sync.SyncReport[source]

Summary of what a sync run found and did.

Parameters:

  • already_satisfied – Dependencies that were already installed.

  • installed – Dependencies successfully installed this run.

  • failed – Mapping of dependency name to failure reason.

already_satisfied: list[str]

‘field(…)’

failed: dict[str, str]

‘field(…)’

installed: list[str]

‘field(…)’

ok() → bool[source]
Returns:

True when nothing failed to install.