.. _quickstart:

Quickstart Guide
================

*Collectors* was originally developed to monitor `SimPy
<http://simpy.sourceforge.net/SimPyDocs/SimPy_Overview.html>`_ processes, but it
can be used to monitor any types of objects or variables. Thus, these first,
simple examples demonstrate the usage of *Collectors* with ordinary Python
objects; *SimPy* is dedicated an own :doc:`section <simpy>`.


Monitor an object’s attributes
------------------------------

Simply monitoring an objects values is really easy::

    >>> from collectors import Collector, get
    >>> class Spam(object):
    ...     a = 1
    ...     b = 2
    ...
    >>> spam = Spam()
    >>> col = Collector(get(spam, 'a', 'b'))
    >>> col()
    >>> spam.a, spam.b = 3, 4
    >>> col()
    >>> col
    ([1, 3], [2, 4])
    >>> col.a
    [1, 3]
    >>> col.b == col[1]
    True

When you create a new :class:`~collectors.core.Collector` instance, you need to
tell it which objects and which attributes to monitor. This can e.g. be done by
using the shortcut function :func:`~collectors.shortcuts.get`.

To save the current state of the the monitored objects, just make a call to the
collector instance (if you don’t like this, there is also a
:meth:`~collectors.core.Collector.collect` method that does the same).

:class:`~collectors.core.Collector` inherits :class:`tuple` and stores each
series for the monitored objects as an entry. It also creates an object
attribute for each series based on its name, so you can access each series
either by name or by index and handle the collector itself as a simple tuple.


Iterating over a collector
--------------------------

Since a collector is basically just a tuple, you can easily iterate over its
series as well as of the the values of all series. If you imagine your collector
as a table with a column for each monitored attribute, the first loop iterates
over each column while the second one iterates over each row::

    >>> for series in col:
    ...     print series
    [1, 3]
    [2, 4]
    >>> for a, b in zip(*col):
    ...     print 'a: %d | b: %d' % (a, b)
    a: 1 | b: 2
    a: 3 | b: 4


What’s next?
------------

You now know how to use *Collectors* for simple tasks. The next section will
describe in detail, how :class:`~collectors.core.Collector` works and which
shortcuts we have to make defining a collector easier.
