Observable
##########

Subcription
***********

The final target of an *Observable*, be it directly or after operations have
been applied to it is that a subscription takes place. A subscription is
performed by an *Observer*.

Ideally an *Observer* would be an instance of a class defining these 3
methods.

.. code-block:: python

    class Observer:

        def on_next(self, value):
           '''Called with each value generated by the Observable'''

        def on_completed(self):
           '''Called when the Observable can no longer produce values'''

        def on_error(self, error):
           '''Called when an error has occurred in the chain'''

.. note:: A class with the 3 methods is offered inside *AnPyLar*, where the
          needed methods can be overridden by the end user

In practice the following suffices

.. code-block:: python

    class Observer:

        def on_next(self, value):
            # Receive the next value generated by the Observable and do something
            pass

or a simple *callable*

.. code-block:: python

    def observer(value):
        # Receive the next value generated by the Observable and do something
        pass


**Subscribing**:

  - ``ObservableSource.subscribe(on_next, on_completed=None, on_error=None, observer=None)``


or

  - with chained operations::

      ObservableSource \
          .op1() \
          .op2() \
          .subscribe(on_next, on_completed=None, on_error=None, observer=None)

The parameters work as follows:

  - If ``observer`` is not ``None``, it will be taken as the target for the
    values. It is assumed it will be an object with the following methods

    - ``on_next``, ``on_completed``, ``on_error``

    .. note:: In this case and because ``on_next`` has no default value in the
              signature, anything can be passed, including ``None``

  - If ``observer`` is ``None``

    - If ``on_completed`` is ``None``, it will then be sought as an attribute
      of ``on_next``

    - If ``on_error`` is ``None``, it will then be sought as an attribute
      of ``on_next``

    - ``on_next`` will be scanned for an attribute called ``on_next``. If found
      it will be taken, else the passed value will be used.

The pattern which one will usually apply::

  observable.subscribe(callable)

A practical example::

  Observable.from_(3).map(lambda x: x * 2).subscribe(print)

which prints::

  6


Sources
*******
.. currentmodule:: anpylar.obs_src

The following methods create an *Observable* using the provided parameters.

from\_
======
.. autofunction:: from_

of
===
.. autofunction:: of

range
=====
.. autofunction:: range

throw\_ (source)
================
.. autofunction:: throw_


Operators
*********
.. currentmodule:: anpylar.obs_ops

The following operators can be applied to *Observables*. They can be chained.

all
===
.. autofunction:: all

catch_exception
===============
.. autofunction:: catch_exception

debounce
========
.. autofunction:: debounce


defval
======
.. autofunction:: defval

delay
=====
.. autofunction:: distinct

distinct
========
.. autofunction:: distinct

distinct_until_changed
======================
.. autofunction:: distinct_until_changed

do_action
=========
.. autofunction:: do_action

filter
======
.. autofunction:: filter

first
=====
.. autofunction:: first

first_or_default
================
.. autofunction:: first_or_default

map
===
.. autofunction:: map

nop
===
.. autofunction:: nop

publish
=======
.. autofunction:: publish

switch_map
==========
.. autofunction:: switch_map

take
====
.. autofunction:: take

throw\_ (operator)
==================
.. autofunction:: throw_