:py:mod:`dissect.target.tools.utils.cli`
========================================

.. py:module:: dissect.target.tools.utils.cli




Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.tools.utils.cli.configure_generic_arguments
   dissect.target.tools.utils.cli.process_generic_arguments
   dissect.target.tools.utils.cli.configure_plugin_arguments
   dissect.target.tools.utils.cli.process_plugin_arguments
   dissect.target.tools.utils.cli.open_target
   dissect.target.tools.utils.cli.open_targets
   dissect.target.tools.utils.cli.list_plugins
   dissect.target.tools.utils.cli.list_children
   dissect.target.tools.utils.cli.generate_argparse_for_method
   dissect.target.tools.utils.cli.generate_argparse_for_plugin_class
   dissect.target.tools.utils.cli.generate_argparse_for_plugin
   dissect.target.tools.utils.cli.execute_function_on_target
   dissect.target.tools.utils.cli.plugin_function_with_argparser
   dissect.target.tools.utils.cli.persist_execution_report
   dissect.target.tools.utils.cli.catch_sigpipe
   dissect.target.tools.utils.cli.args_to_uri
   dissect.target.tools.utils.cli.find_and_filter_plugins
   dissect.target.tools.utils.cli.escape_str



Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.tools.utils.cli.USAGE_FORMAT_TMPL


.. py:data:: USAGE_FORMAT_TMPL
   :value: '{prog} -f {name}{usage}'


.. py:function:: configure_generic_arguments(parser: argparse.ArgumentParser) -> None

.. py:function:: process_generic_arguments(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None

.. py:function:: configure_plugin_arguments(parser: argparse.ArgumentParser) -> None

.. py:function:: process_plugin_arguments(parser: argparse.ArgumentParser, args: argparse.Namespace, rest: list[str]) -> set

   Processes the arguments concerting plugin functions (``-f``, ``--function``) and
   exclusion list (``-xf``, ``--exclude-funciton``).

   It puts the excluded function paths inside ``args.excluded_functions`` as a side effect.

   :returns: ``True`` if there are multiple output types detected, false otherwise.


.. py:function:: open_target(args: argparse.Namespace, *, apply: bool = True) -> dissect.target.target.Target

.. py:function:: open_targets(args: argparse.Namespace, *, apply: bool = True) -> collections.abc.Iterator[dissect.target.target.Target]

.. py:function:: list_plugins(targets: list[str] | None = None, patterns: str = '', include_children: bool = False, json: bool = False) -> None

.. py:function:: list_children(args: argparse.Namespace) -> None

   Pretty print children of targets (recursively).


.. py:function:: generate_argparse_for_method(method: collections.abc.Callable, usage_tmpl: str | None = None) -> argparse.ArgumentParser

   Generate an ``argparse.ArgumentParser`` for a bound or unbound ``Plugin`` class method.


.. py:function:: generate_argparse_for_plugin_class(plugin_cls: type[dissect.target.plugin.Plugin], usage_tmpl: str | None = None) -> argparse.ArgumentParser

   Generate an ``argparse.ArgumentParser`` for a ``Plugin`` class.


.. py:function:: generate_argparse_for_plugin(plugin_instance: dissect.target.plugin.Plugin, usage_tmpl: str | None = None) -> argparse.ArgumentParser

   Generate an ``argparse.ArgumentParser`` for a ``Plugin`` instance.


.. py:function:: execute_function_on_target(target: dissect.target.target.Target, func: dissect.target.plugin.FunctionDescriptor, args: list[str] | None = None) -> tuple[str, Any]

   Execute function on provided target with optional provided arguments.

   If no explicit arguments are provided, they will be parsed from ``sys.argv``.


.. py:function:: plugin_function_with_argparser(target_attr: dissect.target.plugin.Plugin | collections.abc.Callable) -> tuple[collections.abc.Callable | None, argparse.ArgumentParser | None]

   Resolves which plugin function to execute, and creates the argument parser for said plugin.


.. py:function:: persist_execution_report(output_dir: pathlib.Path, report_data: dict, timestamp: datetime.datetime) -> pathlib.Path

.. py:function:: catch_sigpipe(func: collections.abc.Callable) -> collections.abc.Callable

   Catches ``KeyboardInterrupt`` and ``BrokenPipeError`` (``OSError 22`` on Windows).


.. py:function:: args_to_uri(targets: list[str], loader_name: str, args: list[str] | None = None) -> list[str]

   Converts argument-style ``-L`` to URI-style.

   Turns:
       ``target-query /evtxs/* -L log --log-hint="evtx" -f evtx``
   into:
       ``target-query "log:///evtxs/*?hint=evtx" -f evtx``

   For loaders providing ``@arg()`` arguments.


.. py:function:: find_and_filter_plugins(functions: str, target: dissect.target.target.Target, excluded_func_paths: set[str] | None = None) -> collections.abc.Iterator[dissect.target.plugin.FunctionDescriptor]

.. py:function:: escape_str(value: str) -> str

   Escape non-ASCII, unicode characters and bytes to a printable form.