Permalink
Browse files

Improved documentation

  • Loading branch information...
1 parent 2bf3615 commit 1c7103f0a2426298ad85dbdf91ead5fad9080016 @hgrecco committed Nov 25, 2012
Showing with 171 additions and 6 deletions.
  1. +1 −1 README
  2. +18 −0 docs/api.rst
  3. +3 −0 docs/basic.rst
  4. +2 −2 docs/commandline.rst
  5. +6 −2 docs/conf.py
  6. +3 −1 docs/index.rst
  7. +77 −0 docs/internals.rst
  8. +28 −0 examples/README
  9. +12 −0 examples/common.py
  10. +21 −0 examples/future.py
View
2 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.
View
18 docs/api.rst
@@ -0,0 +1,18 @@
+
+API
+===
+
+.. module:: pizco
+
+.. autoclass:: Agent
+ :members:
+
+
+
+.. autoclass:: Proxy
+ :members:
+
+
+
+.. autoclass:: Server
+ :members:
View
3 docs/basic.rst
@@ -1,4 +1,7 @@
+Getting Started
+===============
+
Installing
----------
View
4 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::
View
8 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'
View
4 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
View
77 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.
View
28 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.
View
12 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)
+
View
21 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())
+

0 comments on commit 1c7103f

Please sign in to comment.