Improved documentation

README

@@ -5,7 +5,7 @@ Pizco is Python module/package that allows python objects to communicate.
 Objects can be exposed to other process in the same computer or over the network,
 allowing clear separation of concerns, resources and permissions.
 
-Pizco not only support calling methods from remote objects but also
+Pizco supports calling methods from remote objects and also
 accessing their attributes, dictionary attributes and properties. Most importantly,
 using a Qt-like (and Qt compatible!) signal and slot mechanism you can easily
 register notifications.

docs/api.rst

@@ -0,0 +1,18 @@
+
+API
+===
+
+.. module:: pizco
+
+.. autoclass:: Agent
+   :members:
+
+
+
+.. autoclass:: Proxy
+   :members:
+
+
+
+.. autoclass:: Server
+   :members:

docs/basic.rst

@@ -1,4 +1,7 @@
 
+Getting Started
+===============
+
 Installing
 ----------
 

docs/commandline.rst

@@ -1,6 +1,6 @@
 
-Command line tools
-------------------
+Command line tool
+=================
 
 You can start a server from the command line calling `pizco.py`. For example::
 

docs/conf.py

@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +25,9 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.intersphinx',
+              'sphinx.ext.autodoc'
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -289,3 +291,5 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/3': None}
+
+autodoc_member_order = 'groupwise'

docs/index.rst

@@ -10,7 +10,7 @@ Pizco is Python module/package that allows python objects to communicate.
 Objects can be exposed to other process in the same computer or over the network,
 allowing clear separation of concerns, resources and permissions.
 
-Pizco not only support calling methods from remote objects but also
+Pizco supports calling methods from remote objects and also
 accessing their attributes, dictionary attributes and properties. Most importantly,
 using a Qt-like (and Qt compatible!) signal and slot mechanism you can easily
 register notifications.
@@ -121,6 +121,8 @@ Contents
    signals
    serve_in_process
    commandline
+   internals
+   api
 
 
 Indices and tables

docs/internals.rst

@@ -0,0 +1,77 @@
+
+.. module:: pizco
+
+Internals
+=========
+
+Agent
+-----
+
+The base of both :class:`Proxy` and :class:`Server` is the :class:`Agent`.
+Each Agent has ZMQ sockets to communicate:
+
+- a `REP` socket to receive requests. This is the main endpoint of the Agent.
+- a `PUB` to emit notifications to other Agents.
+- one `SUB` to subscribe to notifications from other Agents.
+- one `REQ` per each Agent that it has to talk to (stored in self.connections)
+
+The `REP` and `PUB` endpoint can be specified when the Agent is instantiated.
+If no endpoint is given, the sockets will bind to a random tcp port.
+
+Protocol
+--------
+
+Messages are multipart ZMQ messages. The conten
+
+**FRAME 0:** Header (utf-8 encoded str)
+
+Used for identification and filtering. It contains 3 string concatenated with a
+`+` (plus sign).
+
+1. The protocol version (currently PZC00).
+2. A unique identifier for the sender.
+3. A string specifying the topic of the message.
+
+*example:* PZC00+urn:uuid:ad2d9eb0-c5f8-4bfb-a37d-6b7903b041f3+value_changed
+
+**FRAME 1:** Serialization (utf-8 encoded str)
+
+Indicates the serialization protocol used in FRAME 2. Current valid values are:
+
+- 'pickle': use the highest version available of the pickle format (default).
+- 'pickleN': use the N version of the pickle format.
+- 'json': use json format.
+
+**FRAME 2:** Content (binary blob)
+
+The actual content of the message.
+
+**FRAME 3:** Message ID (utf-8 encoded str)
+
+A unique identifier for the message.
+
+*example:* urn:uuid:b711f2b8-277d-40df-a283-6269331db251
+
+**FRAME 4:** Signature (bytes)
+
+HMAC sha1 signature of FRAME 0:4 concatenated with Agent.hmac_key
+
+
+By default, Agents use an empty signature key (no signature) and
+the `pickle` serializer. The simplest way to change these defaults is
+by using the environmental variables `PZC_KEY` and `PZC_SER`.
+You might want to change the serializer when running different agents
+on different versions of Python as not all pickle versions are supported
+in all python versions.
+
+You can also change the protocol settings for an specific Agent by
+passing a Protocol object when the Agent is created.
+
+
+Proxy-Server Protocol
+---------------------
+
+Between the Proxy and the Server, the content of the message (Frame 2)
+is a tuple of three elements, being the first utf-8 str defining the
+subprotocol ('PSMessage'). The second and third elements specify the
+action and the options for that action.

examples/README

@@ -0,0 +1,28 @@
+
+Running Pizco House Examples
+============================
+
+Server
+------
+
+Run `house_server.py` to start serving an instance of House.
+The House class is defined in `common.py`
+
+Clients
+-------
+
+These should be run in parallel with the Server:
+
+- `simple_client.py`: send instructions to the House object.
+- `exception_handling.py`: select a new color for the house,
+  (but only certain colors are allowed!).
+- `observing_client.py`: while running `simple_client.py`, see
+  how this client is notified.
+- `gui_client.py`: See bidirectional communication (instructions
+   and notifications) in action. (Requires PyQt)
+
+
+All in one
+----------
+
+remote_start_server.py:  shows how to start a detached process to serve an object.

examples/common.py

@@ -3,9 +3,12 @@
 import time
 import logging
 
+from concurrent import futures
 
 from pizco import Signal
 
+
+
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.DEBUG)
 ch = logging.StreamHandler()
@@ -26,6 +29,8 @@ def __init__(self):
 
         self.color_changed = Signal()
 
+        self._pool = futures.ThreadPoolExecutor(max_workers=1)
+
     @property
     def door_open(self):
         logger.info('Getting door_open')
@@ -66,4 +71,11 @@ def paint(self, color):
         self.color_changed.emit(color)
         logger.info('Painted: {}'.format(color))
 
+    def _changing_roof(self):
+        time.sleep(1)
+        return 'You have a new roof'
+
+    def change_roof(self):
+        return self._pool.submit(self._changing_roof)
+
 

examples/future.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+import sys
+import time
+
+if sys.version_info < (3,0):
+    input = raw_input
+
+from pizco import Proxy
+
+proxy = Proxy('tcp://127.0.0.1:8000')
+
+while True:
+    input('Press enter to run ...\n')
+    fut = proxy.change_roof()
+    print('I am doing something while changing the roof')
+    print('The door is open?: {}'.format(proxy.door_open))
+    print('The lights are on?: {}'.format(proxy.lights_on))
+    print('I have finished doing this and now I will wait for the result')
+    print(fut.result())
+