.. _quickstart:

=======================
Quickstart and Tutorial
=======================

.. currentmodule:: PyroMP

Installation
------------

Use easy_install

.. code-block:: console

    easy-install PyroMP
    
or pip

.. code-block:: console

    pip PyroMP


Or get the code directly from the repo on `bitbucket`_.

.. _bitbucket: https://bitbucket.org/pbrimmers/pyromp/



.. _warehouse_example:

Warehouse example
-----------------

.. hint:: All code of this part of the tutorial can be found in the ``examples/warehouse`` directory.

You'll build a simple warehouse that stores items, and that everyone can visit.
Visitors can store items and retrieve other items from the warehouse (if they've been stored there).

In this tutorial you'll first write a normal Python program that more or less implements the complete warehouse system,
but in vanilla Python code.
After that you'll add PyroMP support to it, to make it a distributed warehouse system,
where you can visit the central warehouse from many different processes.

.. note:: This example is adapted from `Pyro4 tutorial`_.

.. _Pyro4 tutorial: http://pythonhosted.org/Pyro4/tutorials.html


Phase 1: the prototype
----------------------

To start with, write the vanilla Python code for the warehouse and its visitors.
This prototype is fully working but everything is running in a single process.
It contains no PyroMP code at all, but shows what the system is going to look like later on.


The ``Warehouse`` object simply stores an array of items which we can query,
and allows for a person to take an item or to store an item (``warehouse.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase1/warehouse.py
   :linenos:

Then there is a ``Person`` that can visit the warehouse.
The person has a name and deposit and retrieve actions on a particular warehouse
(``person.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase1/person.py
   :linenos:

Finally you need a the ``main`` function that actually runs the code.
It creates the warehouse and two visitors, and makes the visitors perform
their actions in the warehouse (``visit.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase1/visit.py
   :linenos:

Run ``visit.py``. The output should look like:

.. code-block:: none

    This is Janet.
    The warehouse contains: [u'chair', u'bike', u'flashlight', u'laptop', u'couch']
    Type a thing you want to store (or empty): car              <-- typed in
    Janet stored the car.
    The warehouse contains: [u'chair', u'bike', u'flashlight', u'laptop', u'couch', 'car']
    Type something you want to take (or empty): bike            <-- typed in
    Janet took the bike.
    Thank you, come again!
    This is Henry.
    The warehouse contains: [u'chair', u'flashlight', u'laptop', u'couch', 'car']
    Type a thing you want to store (or empty): computer         <-- typed in
    Henry stored the computer.
    The warehouse contains: [u'chair', u'flashlight', u'laptop', u'couch', 'car', 'computer']
    Type something you want to take (or empty): laptop          <-- typed in
    Henry took the laptop.
    Thank you, come again!


Phase 2: first PyroMP version
-----------------------------

The first step is importing PyroMP.
Futhermore the built-in :mod:`logging` module is not
capable of multiprocess logging in an appropriate way,
but ``Pyro4.log_server`` (see :ref:`logging`), so we need to replace it.


To start the ``Warehouse`` in a separate process, we have to derive it from :class:`Service`.
There must be two lines changed and one added to perform this.
Furthermore we use the :func:`~Service.get_logger` function to use a PyroMP logger.
The modified lines are highlighted in the code (``warehouse.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase2/warehouse.py
   :linenos:
   :emphasize-lines: 10, 13, 15, 16, 18

The implementation of ``Person`` is not changed.
In the ``main`` function we need to start the :class:`NameServer` and :class:`~PyroMP.log_server.LogServer`.
Afterwards we set the logging level to ``INFO``.
The warehouse service is started using the with statement and stopped after
the with-block (``visit.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase2/visit.py
   :linenos:
   :emphasize-lines: 13, 14, 20-22

Run ``visit.py``.
It will take a short while until all processes have been started.
The output should look like:

.. code-block:: none

    This is Janet.
    The warehouse contains: [u'chair', u'bike', u'flashlight', u'laptop', u'couch']
    Type a thing you want to store (or empty): car           <-- typed in
    2014-02-03 17:07:45,368 - LogServer.WAREHOUSE            - INFO     - Janet stored the car.
    The warehouse contains: [u'chair', u'bike', u'flashlight', u'laptop', u'couch', 'car']
    Type something you want to take (or empty): bike         <-- typed in
    2014-02-03 17:07:49,144 - LogServer.WAREHOUSE            - INFO     - Janet took the bike.
    Thank you, come again!
    This is Henry.
    The warehouse contains: [u'chair', u'flashlight', u'laptop', u'couch', 'car']
    Type a thing you want to store (or empty): computer      <-- typed in
    2014-02-03 17:07:53,871 - LogServer.WAREHOUSE            - INFO     - Henry stored the computer.
    The warehouse contains: [u'chair', u'flashlight', u'laptop', u'couch', 'car', 'computer']
    Type something you want to take (or empty): laptop       <-- typed in
    2014-02-03 17:08:04,869 - LogServer.WAREHOUSE            - INFO     - Henry took the laptop.
    Thank you, come again!


Phase 3: access from another process
------------------------------------

To have access to the ``Warehouse`` object the service must be running.
We add a line where the main process will wait until enter is pressed
and the service is not stopped (``visit.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase3/visit.py
   :linenos:
   :emphasize-lines: 13, 32

We get access to the ``Warehouse`` :class:`~PyroMP.Service` by importing it and using the same syntax as before.
The service is neither started again before nor stopped after the with-block,
because it is already running and was started from another process (``another_visit.py``):

.. literalinclude:: ../../PyroMP/examples/warehouse/phase3/another_visit.py
   :linenos:

First run ``visit.py``, then run ``another_visit.py``,
while the former waits for enter.
The output of ``visit.py`` should look like:

.. code-block:: none

    This is Janet.
    The warehouse contains: [u'chair', u'bike', u'flashlight', u'laptop', u'couch']
    Type a thing you want to store (or empty): car           <-- typed in
    2014-02-03 17:33:00,352 - LogServer.WAREHOUSE            - INFO     - Janet stored the car.
    The warehouse contains: [u'chair', u'bike', u'flashlight', u'laptop', u'couch', 'car']
    Type something you want to take (or empty): bike         <-- typed in
    2014-02-03 17:33:01,805 - LogServer.WAREHOUSE            - INFO     - Janet took the bike.
    Thank you, come again!
    This is Henry.
    The warehouse contains: [u'chair', u'flashlight', u'laptop', u'couch', 'car']
    Type a thing you want to store (or empty): computer      <-- typed in
    2014-02-03 17:33:03,506 - LogServer.WAREHOUSE            - INFO     - Henry stored the computer.
    The warehouse contains: [u'chair', u'flashlight', u'laptop', u'couch', 'car', 'computer']
    Type something you want to take (or empty): laptop       <-- typed in
    2014-02-03 17:33:08,217 - LogServer.WAREHOUSE            - INFO     - Henry took the laptop.
    Thank you, come again!
    Press enter to exit:2014-02-03 17:33:31,789 - LogServer.WAREHOUSE            - INFO     - Josephine stored the football.
    2014-02-03 17:33:34,191 - LogServer.WAREHOUSE            - INFO     - Josephine took the car.
    2014-02-03 17:33:42,367 - LogServer.WAREHOUSE            - INFO     - Peter stored the baseball.
    2014-02-03 17:33:45,019 - LogServer.WAREHOUSE            - INFO     - Peter took the couch.

The output of ``another_visit.py`` should look like:

.. code-block:: none

    This is Josephine.
    The warehouse contains: [u'chair', u'flashlight', u'couch', 'car', 'computer']
    Type a thing you want to store (or empty): football       <-- typed in
    The warehouse contains: [u'chair', u'flashlight', u'couch', 'car', 'computer', 'football']
    Type something you want to take (or empty): car           <-- typed in
    Thank you, come again!
    This is Peter.
    The warehouse contains: [u'chair', u'flashlight', u'couch', 'computer', 'football']
    Type a thing you want to store (or empty): baseball       <-- typed in
    The warehouse contains: [u'chair', u'flashlight', u'couch', 'computer', 'football', 'baseball']
    Type something you want to take (or empty): couch         <-- typed in
    Thank you, come again!