The Components
==============

.. _the-components:


.. _components-introduction:

Introduction
------------

This is a module to hold classes that (loosely) implement the `Composite Pattern <http://en.wikipedia.org/wiki/Composite_pattern>`_. See the :ref:`Ape Plugin <ape-plugin>` for how the Composites are being used in the `ape` (it is implemented in the `product` property).



.. _component-module-diagram:
Module Diagram
--------------

This is an auto-generated graph of the classes in this module.

.. <<name='module_graph', echo=False, results='sphinx'>>=
.. if DOCUMENT_THIS:
..     this_file = os.path.join(os.getcwd(), 'component.py')
..     module_diagram_file = module_diagram(module=this_file, project='composite')
..     print ".. image:: {0}".format(module_diagram_file)
.. 


.. _component-class:

The Component Class
-------------------

This is the base-class which the other classes will inherit from. All :ref:`Plugin products <base-plugin-product>` should look like this (it doesn't do much but every method is called at some point by the Composites so all plugin products should implement it).

.. '

.. uml::

   Component -|> BaseClass
   Component : __call__()
   Component : check_rep()
   Component : close()

.. currentmodule:: ape.components.component
.. autosummary::
   :toctree: api

   Component
   Component.__call__
   Component.check_rep
   Component.close




This is an autogenerated version of the class-diagram.

.. <<name='class_diagram', echo=False, results='sphinx'>>=
.. if DOCUMENT_THIS:
..     class_diagram_file = class_diagram(class_name="Component",
..                                        filter='OTHER',
..                                        module=this_file)
..     print ".. image:: {0}".format(class_diagram_file)
.. 

.. _composite-class:

The Composite
-------------

.. uml::

   Composite -|> Component

.. autosummary::
   :toctree: api

   Composite
   Composite.components
   Composite.add
   Composite.remove
   Composite.__call__
   Composite.__iter__
   Composite.__len__
   Composite.__getitem__
   Composite.one_call
   Composite.check_rep
   Composite.close
   Composite.time_remains

The `Composite` was created to be a generalization of the `Hortator`, `Operator` and `Operations`. By specifying the error that it will catch, the error message it will display if there is one, its components, and the component-category of its components, you specify what type of composite it is. It can also act as a regular composite to contain other parts, but this was the original use-case -- to create the infrastructure for the APE.

 * Each component call is wrapped by the :ref:`try_except decorator <try-except-decorator>` which catches the Exception in self.error

 * The default for ``self.time_remains`` is a :ref:`TimeTracker <ape-parts-countdown-timetracker>` but can also be a :ref:`CountdownTimer <ape-parts-countdown-countdowntimer>`



.. <<name='composite_class_diagram', echo=False, results='sphinx'>>=
.. if DOCUMENT_THIS:
..     class_diagram_file = class_diagram(class_name="Composite",
..                                        filter='OTHER',
..                                        module=this_file)
..     print ".. image:: {0}".format(class_diagram_file)
..