Tasks

Structured task and keyword argument containers.

This module defines immutable data structures used to represent parsed task execution blocks and their associated keyword arguments.

The classes encapsulate:

• Task name
• Collected keyword arguments
• Default value resolution logic
• Iterable access to multiple tasks

They are returned by qargparse.ArgumentParser.parse_args().

TaskKwargs dataclass

Immutable representation of a single task invocation.

A TaskKwargs instance represents one parsed task execution block, containing:

• The task name
• The collected keyword arguments for that invocation
• Remaining unresolved default mappings

During initialization, task-specific default values are injected into kwargs if not already explicitly provided.

Attributes:

Name	Type	Description
name	str	Name of the task.
kwargs	Dict[str, Any]	Keyword arguments resolved for this task invocation.
defaults	Dict[str, Dict[str, Any]]	Remaining default mappings that were not applied during initialization. Keys are parameter names, and values are dictionaries mapping task aliases to default values.

Source code in src/qargparse/tasks.py

@dataclass(frozen=True, slots=True, repr=True, init=False)
class TaskKwargs:
    """Immutable representation of a single task invocation.

    A TaskKwargs instance represents one parsed task execution block,
    containing:

    - The task name
    - The collected keyword arguments for that invocation
    - Remaining unresolved default mappings

    During initialization, task-specific default values are injected
    into ``kwargs`` if not already explicitly provided.

    Attributes:
        name (str):
            Name of the task.

        kwargs (Dict[str, Any]):
            Keyword arguments resolved for this task invocation.

        defaults (Dict[str, Dict[str, Any]]):
            Remaining default mappings that were not applied during
            initialization. Keys are parameter names, and values are
            dictionaries mapping task aliases to default values.
    """
    name: str
    kwargs: Dict[str, Any]
    defaults: Dict[str, Dict[str, Any]]

    def __init__(self, name: str, kwargs: Dict[str, Any], defaults: Dict[str, Dict[str, Any]]) -> None:
        """Initialize a TaskKwargs instance and resolve defaults.

        For each parameter in ``defaults``:

        - If the parameter is missing from ``kwargs`` and a default
          exists for this task name, the default is injected.
        - Otherwise, the parameter remains in ``defaults`` for
          potential later resolution.

        Args:
            name:
                The task name.
            kwargs:
                Explicit keyword arguments provided for this task.
            defaults:
                Mapping of parameter names to task-specific default
                dictionaries.
        """
        # Add this task defaults if they are missing from kwargs
        kwargs = dict(kwargs)
        task_defaults = {}
        for param, task_to_default in defaults.items():
            if param not in kwargs:
                if name in task_to_default:
                    kwargs[param] = task_to_default[name]
                else:
                    task_defaults[param] = task_to_default
        object.__setattr__(self, "name", name)
        object.__setattr__(self, "kwargs", kwargs)
        object.__setattr__(self, "defaults", task_defaults)

    def set_defaults(self, params: str | List[str], alias: str=''):
        """Resolve remaining defaults for selected parameters.

        This method applies default values to the specified parameters
        if they are not already present in ``kwargs``.

        Default resolution order:
            1. Alias-specific default (if provided)
            2. Global default (empty alias key "")
            3. None

        Args:
            params:
                Parameter name or list of parameter names to resolve.
            alias:
                Optional alias used to select task-specific defaults.

        Returns:
            TaskKwargs:
                A new instance with resolved defaults injected into
                ``kwargs`` and cleared ``defaults``.
        """
        if isinstance(params, str):
            params = [params]
        return replace(self, kwargs=self.kwargs | {k: v[alias] if alias in v else v[''] if '' in v else None for k, v in self.defaults.items() if k in params and k not in self.kwargs}, defaults={})

__init__(name, kwargs, defaults)

Initialize a TaskKwargs instance and resolve defaults.

For each parameter in defaults:

• If the parameter is missing from kwargs and a default exists for this task name, the default is injected.
• Otherwise, the parameter remains in defaults for potential later resolution.

Parameters:

Name	Type	Description	Default
name	str	The task name.	required
kwargs	Dict[str, Any]	Explicit keyword arguments provided for this task.	required
defaults	Dict[str, Dict[str, Any]]	Mapping of parameter names to task-specific default dictionaries.	required

Source code in src/qargparse/tasks.py

def __init__(self, name: str, kwargs: Dict[str, Any], defaults: Dict[str, Dict[str, Any]]) -> None:
    """Initialize a TaskKwargs instance and resolve defaults.

    For each parameter in ``defaults``:

    - If the parameter is missing from ``kwargs`` and a default
      exists for this task name, the default is injected.
    - Otherwise, the parameter remains in ``defaults`` for
      potential later resolution.

    Args:
        name:
            The task name.
        kwargs:
            Explicit keyword arguments provided for this task.
        defaults:
            Mapping of parameter names to task-specific default
            dictionaries.
    """
    # Add this task defaults if they are missing from kwargs
    kwargs = dict(kwargs)
    task_defaults = {}
    for param, task_to_default in defaults.items():
        if param not in kwargs:
            if name in task_to_default:
                kwargs[param] = task_to_default[name]
            else:
                task_defaults[param] = task_to_default
    object.__setattr__(self, "name", name)
    object.__setattr__(self, "kwargs", kwargs)
    object.__setattr__(self, "defaults", task_defaults)

set_defaults(params, alias='')

Resolve remaining defaults for selected parameters.

This method applies default values to the specified parameters if they are not already present in kwargs.

Default resolution order

1. Alias-specific default (if provided)
2. Global default (empty alias key "")
3. None

Parameters:

Name	Type	Description	Default
params	str | List[str]	Parameter name or list of parameter names to resolve.	required
alias	str	Optional alias used to select task-specific defaults.	''

Returns:

Name	Type	Description
TaskKwargs		A new instance with resolved defaults injected into kwargs and cleared defaults.

Source code in src/qargparse/tasks.py

def set_defaults(self, params: str | List[str], alias: str=''):
    """Resolve remaining defaults for selected parameters.

    This method applies default values to the specified parameters
    if they are not already present in ``kwargs``.

    Default resolution order:
        1. Alias-specific default (if provided)
        2. Global default (empty alias key "")
        3. None

    Args:
        params:
            Parameter name or list of parameter names to resolve.
        alias:
            Optional alias used to select task-specific defaults.

    Returns:
        TaskKwargs:
            A new instance with resolved defaults injected into
            ``kwargs`` and cleared ``defaults``.
    """
    if isinstance(params, str):
        params = [params]
    return replace(self, kwargs=self.kwargs | {k: v[alias] if alias in v else v[''] if '' in v else None for k, v in self.defaults.items() if k in params and k not in self.kwargs}, defaults={})

TasksKwargs dataclass

Immutable container for multiple task invocations.

This class wraps the list of parsed task blocks returned by qargparse.ArgumentParser.parse_args().

It provides:

• Iterable access to TaskKwargs objects
• Indexed access to individual tasks
• Shared default resolution logic across tasks

Attributes:

Name	Type	Description
tasks	List[Tuple[str, Dict[str, Any]]]	Raw list of (task_name, kwargs) pairs.
defaults	Dict[str, Dict[str, Any]]	Global default mappings applied to all tasks.

Source code in src/qargparse/tasks.py

@dataclass(frozen=True, slots=True, repr=True, kw_only=True)
class TasksKwargs:
    """Immutable container for multiple task invocations.

    This class wraps the list of parsed task blocks returned by
    qargparse.ArgumentParser.parse_args().

    It provides:

    - Iterable access to TaskKwargs objects
    - Indexed access to individual tasks
    - Shared default resolution logic across tasks

    Attributes:
        tasks (List[Tuple[str, Dict[str, Any]]]):
            Raw list of (task_name, kwargs) pairs.

        defaults (Dict[str, Dict[str, Any]]):
            Global default mappings applied to all tasks.
    """
    tasks: List[Tuple[str, Dict[str, Any]]] = field(default_factory=list)
    defaults: Dict[str, Dict[str, Any]] = field(default_factory=dict)

    def __iter__(self):
        return iter([self[i] for i in range(len(self))])

    def __getitem__(self, i):
        return TaskKwargs(*self.tasks[i], defaults=self.defaults)

    def __len__(self):
        return len(self.tasks)