Actions

Queue-based argparse extensions for ordered task execution.

This module provides custom argparse actions that accumulate parsed arguments into a shared queue dictionary and allow defining execution boundaries via task actions.

It enables building command-line interfaces where arguments are grouped and processed incrementally instead of being stored statically in a namespace.

Queue

Bases: Action

              flowchart TD
              src.qargparse.action.Queue[Queue]

              

              click src.qargparse.action.Queue href "" "src.qargparse.action.Queue"
            

Argparse action that stores parsed arguments into a shared queue dictionary.

This action writes each parsed argument value into a dictionary stored on the argparse namespace under the attribute defined by Q_KWARGS.

The destination name (self.dest) is used as the key and the parsed value is stored as the corresponding value.

This action does not preserve call order. It overwrites previously stored values for the same destination key.

Source code in src/qargparse/action.py

class Queue(argparse.Action):
    """Argparse action that stores parsed arguments into a shared queue dictionary.

    This action writes each parsed argument value into a dictionary stored
    on the argparse namespace under the attribute defined by ``Q_KWARGS``.

    The destination name (``self.dest``) is used as the key and the parsed
    value is stored as the corresponding value.

    This action does not preserve call order. It overwrites previously stored
    values for the same destination key.
    """
    def __call__(self, parser, namespace, values, option_string=None):
        q_kwargs = getattr(namespace, Q_KWARGS)
        q_kwargs[self.dest] = values
        setattr(namespace, Q_KWARGS, q_kwargs)

QueueTrue

Bases: _QueueDeterministic

              flowchart TD
              src.qargparse.action.QueueTrue[QueueTrue]
              src.qargparse.action._QueueDeterministic[_QueueDeterministic]
              src.qargparse.action.Queue[Queue]

                              src.qargparse.action._QueueDeterministic --> src.qargparse.action.QueueTrue
                                src.qargparse.action.Queue --> src.qargparse.action._QueueDeterministic
                



              click src.qargparse.action.QueueTrue href "" "src.qargparse.action.QueueTrue"
              click src.qargparse.action._QueueDeterministic href "" "src.qargparse.action._QueueDeterministic"
              click src.qargparse.action.Queue href "" "src.qargparse.action.Queue"
            

Boolean queue action that stores True.

This action behaves similarly to argparse's store_true action, but stores the value inside the shared queue dictionary defined by Q_KWARGS instead of directly on the namespace.

Source code in src/qargparse/action.py

class QueueTrue(_QueueDeterministic):
    """Boolean queue action that stores ``True``.

    This action behaves similarly to ``argparse``'s ``store_true`` action,
    but stores the value inside the shared queue dictionary defined by
    ``Q_KWARGS`` instead of directly on the namespace.
    """
    def _set_value(self) -> None:
        self._value = True

QueueFalse

Bases: _QueueDeterministic

              flowchart TD
              src.qargparse.action.QueueFalse[QueueFalse]
              src.qargparse.action._QueueDeterministic[_QueueDeterministic]
              src.qargparse.action.Queue[Queue]

                              src.qargparse.action._QueueDeterministic --> src.qargparse.action.QueueFalse
                                src.qargparse.action.Queue --> src.qargparse.action._QueueDeterministic
                



              click src.qargparse.action.QueueFalse href "" "src.qargparse.action.QueueFalse"
              click src.qargparse.action._QueueDeterministic href "" "src.qargparse.action._QueueDeterministic"
              click src.qargparse.action.Queue href "" "src.qargparse.action.Queue"
            

Boolean queue action that stores False.

This action behaves similarly to argparse's store_false action, but stores the value inside the shared queue dictionary defined by Q_KWARGS instead of directly on the namespace.

Source code in src/qargparse/action.py

class QueueFalse(_QueueDeterministic):
    """Boolean queue action that stores ``False``.

    This action behaves similarly to ``argparse``'s ``store_false`` action,
    but stores the value inside the shared queue dictionary defined by
    ``Q_KWARGS`` instead of directly on the namespace.
    """
    def _set_value(self) -> None:
        self._value = False

Task

Bases: _QueueDeterministic

              flowchart TD
              src.qargparse.action.Task[Task]
              src.qargparse.action._QueueDeterministic[_QueueDeterministic]
              src.qargparse.action.Queue[Queue]

                              src.qargparse.action._QueueDeterministic --> src.qargparse.action.Task
                                src.qargparse.action.Queue --> src.qargparse.action._QueueDeterministic
                



              click src.qargparse.action.Task href "" "src.qargparse.action.Task"
              click src.qargparse.action._QueueDeterministic href "" "src.qargparse.action._QueueDeterministic"
              click src.qargparse.action.Queue href "" "src.qargparse.action.Queue"
            

Special queue action that creates and registers a task boundary.

This action treats the current queue state as a completed task.

When invoked, it:

• Creates a new task entry structured as: {task_name: collected_arguments}.
• Appends this task entry to the task list stored under Q_TASKS.
• Resets the queue dictionary to an empty state.

This enables CLI patterns such as:

tool.py --a foo --b bar --run --c baz --run

Where each --run marks a boundary and triggers collection of the previously accumulated arguments as a separate task.

Source code in src/qargparse/action.py

class Task(_QueueDeterministic):
    """Special queue action that creates and registers a task boundary.

    This action treats the current queue state as a completed task.

    When invoked, it:

    - Creates a new task entry structured as:
       ``{task_name: collected_arguments}``.
    - Appends this task entry to the task list stored under ``Q_TASKS``.
    - Resets the queue dictionary to an empty state.

    This enables CLI patterns such as:

        tool.py --a foo --b bar --run --c baz --run

    Where each ``--run`` marks a boundary and triggers collection of
    the previously accumulated arguments as a separate task.
    """

    def _set_value(self) -> None:
        self._value = None

    def __call__(self, parser, namespace, values, option_string=None):
        self._check_values(values)
        setattr(namespace, Q_TASKS, getattr(namespace, Q_TASKS)+[(self.dest, getattr(namespace, Q_KWARGS))])
        setattr(namespace, Q_KWARGS, {})