agrifoodpy.pipeline
===================

.. py:module:: agrifoodpy.pipeline

.. autoapi-nested-parse::

   This module provides methods to build a pipeline for the AgriFoodPy package.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/agrifoodpy/pipeline/cli/index
   /autoapi/agrifoodpy/pipeline/pipeline/index


Classes
-------

.. autoapisummary::

   agrifoodpy.pipeline.Pipeline


Functions
---------

.. autoapisummary::

   agrifoodpy.pipeline.get_dict
   agrifoodpy.pipeline.set_dict
   agrifoodpy.pipeline.standalone
   agrifoodpy.pipeline.pipeline_node


Package Contents
----------------

.. py:function:: get_dict(datablock, keys)

   Returns an element from a dictionary using a key or tuple of keys used
   to describe a path of keys

   :param datablock: The input dictionary
   :type datablock: dict
   :param keys: Dictionary key, or tuple of keys
   :type keys: str or tuple


.. py:function:: set_dict(datablock, keys, object, create_missing=True)

   Sets an element in a dictionary using a key or tuple of keys used to
   describe a path of keys

   :param datablock: The input dictionary
   :type datablock: dict
   :param keys: Dictionary key, or tuple of keys
   :type keys: str or tuple
   :param object: The object to set in the dictionary
   :type object: any
   :param create_missing: If True, creates missing keys in the dictionary. Defaults to True.
   :type create_missing: bool, optional

   :raises KeyError: If a key in the path does not exist and create_missing is False.


.. py:class:: Pipeline(datablock=None)

   Class for constructing and running pipelines of functions with
   individual sets of parameters.


   .. py:attribute:: nodes
      :value: []



   .. py:attribute:: params
      :value: []



   .. py:attribute:: names
      :value: []



   .. py:method:: read(filename)
      :classmethod:


      Read a pipeline configuration from a YAML file

      :param filename: The name of the configuration file.
      :type filename: str

      :returns: **pipeline** -- The pipeline object.
      :rtype: Pipeline



   .. py:method:: datablock_write(path, value)

      Writes a single value to the datablock at the specified path.

      :param path: The datablock path to the value to be written.
      :type path: list
      :param value: The value to be written.
      :type value: any



   .. py:method:: add_node(node, params=None, name=None, index=None)

      Adds a node to the pipeline, including its function and execution
      parameters.

      :param node: The function to be executed on this node.
      :type node: function
      :param params: The parameters to be passed to the node function.
      :type params: dict, optional
      :param name: The name of the node. If not provided, a generic name will be
                   assigned.
      :type name: str, optional
      :param index: Index of the enw node. If None, the new node is appended at the
                    end of the node list.
      :type index: int, optional



   .. py:method:: remove_node(node)

      Remove a node from the pipeline by index or name.

      :param node: Index of the node to remove, or its name.
      :type node: int or str



   .. py:method:: run(from_node=0, to_node=None, skip=None, timing=False)

      Runs the pipeline

      :param from_node: The index of the first node to be executed. Defaults to 0.
      :type from_node: int, optional
      :param to_node: The index of the last node to be executed. If not provided, all
                      nodes will be executed
      :type to_node: int, optional
      :param skip: List of node indices to skip during execution. Defaults to None.
      :type skip: list of int, optional
      :param timing: If True, the execution time of each node will be printed. Defaults
                     to False.
      :type timing: bool, optional



   .. py:method:: print_nodes(show_params=True)

      Prints the list of nodes associated with a Pipeline instance.

      :param show_params: If True, displays the parameters associated with each node.
      :type show_params: bool, optional



.. py:function:: standalone(input_keys, return_keys)

   Decorator to make a pipeline node available as a standalone function

   If datablock is not passed as a kwarg, and datasets are passed directly
   instead of datablock keys, a temporary datablock is created and the
   datasets associated with the arguments in input_keys are added to it.
   The function then returns the specified datasets in return_keys.

   :param input_keys: List of dataset keys to be added to the temporary datablock
   :type input_keys: list of strings
   :param return_keys: List of keys to datablock datasets to be returned by the decorated
                       function.
   :type return_keys: list of strings

   :returns: **wrapper** -- The decorated function
   :rtype: function


.. py:function:: pipeline_node(input_keys=None)

   Decorator to make a function compatible with pipeline execution

   If a datablock is passed as a kwarg, the function will be executed in
   pipeline mode, and the values of the parameters named in input_keys will
   be interpreted as datablock lookup keys. The corresponding objects will be
   extracted from the datablock and passed to the function. Unregistered
   keyword arguments will be passed directly to the function. The decorated
   function takes a "return_key" kwarg to specify the key under which the
   function output will be stored in the datablock. If not provided, the
   function name will be used as the return key.

   :param input_keys: List of decorated function parameter names whose values will be used as
                      datablock lookup keys in pipeline mode.
   :type input_keys: string or list of strings, optional

   :returns: **wrapper** -- The decorated function
   :rtype: function