Updated documentation.

README.rst

@@ -8,9 +8,9 @@ It is written in Python and CoffeeScript.
 Is it ready yet?
 ================
 
-Yes, as long as you stick to the provided API. Kaylee is currently
-in early development, but we're looking forward to stick with the
-API, especially the *Projects* part of it.
+**No!** Absolutely not. The Kaylee promise is that each tagged version 
+is self-contained and working fine, but the API is not stable yet and 
+there might be dramatic changes in future.
 
 
 Where are the docs?

TODO.rst

@@ -1,15 +1,20 @@
-* Better error/exceptions mechanism on client
+vX.Y <-- Very far future
 * Client: operations timeout (e.g. project import timeout)
+* Sleepy loops
+
 
 v0.4 <-- Far future
 ----
 * Google App Engine support
 
+
 v0.3 <-- Future
 ----
+* Default config
 * Kaylee Console API
 * Uploading projects through Console API
 
+
 v0.2 <-- dev
 ----
 
@@ -31,4 +36,3 @@ v0.2 <-- dev
 Interesting links:
 # http://www.andromedaproject.org/#!/home
 # http://lenta.ru/news/2012/12/10/helpandromeda/
-

demo/demo_config.py

@@ -112,4 +112,5 @@
 
 # APPLICATIONS = [app_human_ocr_1]
 # APPLICATIONS = [app_hash_cracker_1]
-APPLICATIONS = [app_hash_cracker_2]
+# APPLICATIONS = [app_hash_cracker_2]
+

doc/src/clientapi.rst

@@ -105,7 +105,7 @@ Core
 
    Kaylee client config received from the server after the node has been
    registered. For full configuration description see
-   :class:`kaylee.core.Config`.
+   :ref:`configuration`.
 
 .. js:function:: kl.error(message)
 

doc/src/config.rst → doc/src/configuration.rst

@@ -1,18 +1,33 @@
-.. _config:
+.. _configuration:
 
 Configuration Options
 =====================
 
 .. module:: kaylee
 
 This section describes Kaylee configuration options.
-For information on setting up Kaylee, see :ref:`loading`.
+For information on various methods of configuring and
+setting up Kaylee, see :ref:`loading`.
+
+.. config:: AUTO_GET_ACTION
+
+AUTO_GET_ACTION
+---------------
+
+**Default value:** ``True``.
+
+A flag which indicates whether Kaylee will return a next action when a result
+is accepted from the node.
+
 
 .. config:: APPLICATIONS
 
 APPLICATIONS
 ------------
 
+**Default value:** ``[]``.
+
+
 A list which contains the applications' configurations loaded
 by Kaylee. The format is:
 
@@ -57,6 +72,7 @@ which is passed as ``**kwargs`` during class initialization.
   'config' : {
       'opt1' : 'val1',
       'opt2' : 10,
+
   }
 
 .. config:: PROJECTS_DIR
@@ -67,7 +83,9 @@ PROJECTS_DIR
 Defines a directory in which Kaylee searches for user projects, for
 example:
 
-``/home/user/.kaylee/projects/``.
+.. code-block:: none
+
+  ``/home/user/.kaylee/projects/``
 
 
 .. config:: REGISTRY
@@ -94,8 +112,9 @@ SESSION_DATA_MANAGER
 
 **Optional**. Defines the session data manager.
 
-.. note:: If the option is not defined the loader loads the deafult :class:`
-          Phony <kaylee.session.PhonySessionDataManager>` manager.
+.. note:: If the option is not defined the 
+          default :class:`Phony <kaylee.session.PhonySessionDataManager>`
+          session data manager is loaded.
 
 Format::
 

doc/src/contents.rst.inc

@@ -32,7 +32,7 @@ method, this part of the documentation is for you.
 .. toctree::
    :maxdepth: 1
 
-   config
+   configuration
 
 Additional Notes
 ----------------

doc/src/loading.rst

@@ -12,8 +12,9 @@ prepared and how Kaylee object is loaded.
 
 Configuration
 -------------
-Kaylee configuration is an object which holds some :ref:`config <config>`
-parameters like the applications, worker script URI etc.
+Kaylee configuration is an object which holds certain
+:ref:`configuration <configuration>` parameters like the applications,
+worker script URI etc.
 
 There are several ways of defining Kaylee configuration:
 
@@ -56,4 +57,3 @@ from any part of the code::
   setup('/path/to/config/file.py') # setup accepts any valid config object
 
   # at this point the `kl` proxy refers to the Kaylee object.
-

doc/src/serverapi.rst

@@ -43,12 +43,6 @@ Kaylee Object
    .. :inherited-members:
 
 
-Config Object
-.............
-
-.. autoclass:: kaylee.core.Config
-
-
 Applications Object
 ...................
 

kaylee/core.py

@@ -81,7 +81,7 @@ def __init__(self, registry, session_data_manager = None,
                  applications = None, **kwargs):
         #: An instance of :class:`kaylee.core.Config` which maintains
         #: the configuration initially parsed from ``**kwargs**.
-        self.config = Config(**kwargs)
+        self._config = Config(**kwargs)
 
         #: Active nodes registry (an instance of :class:`NodesRegistry`).
         self.registry = registry
@@ -98,7 +98,7 @@ def register(self, remote_host):
         JSON-formatted data with the following fields:
 
         * node_id - node id (hex-formatted string)
-        * config  - client configuration (see :class:`kaylee.core.Config`).
+        * config  - client configuration (see :ref:`configuration`).
         * applications - a list of Kaylee applications' names.
 
         :param remote_host: the IP address of the remote host
@@ -107,13 +107,13 @@ def register(self, remote_host):
         node = Node(NodeID.for_host(remote_host))
         self.registry.add(node)
         return json.dumps ({ 'node_id' : str(node.id),
-                             'config' : self.config.to_dict(),
+                             'config' : self._config.to_dict(),
                              'applications' : self._applications.names } )
 
     @json_error_handler
     def unregister(self, node_id):
-        """Remove the node from Kaylee. Kaylee will reject any further
-        requests from the node unless it registers again.
+        """Removes the node from the nodes registry. Practically this means
+        that the remote host (browser) disconnects from Kaylee server.
 
         :param node_id: a valid node id
         :type node_id: string
@@ -122,7 +122,7 @@ def unregister(self, node_id):
 
     @json_error_handler
     def subscribe(self, node_id, application):
-        """Subscribes a node to an application. After successful subscribtion
+        """Subscribes a node to an application. After a successful subscription
         the node receives a client-side application configuration and invokes
         client-side project initialization routines.
 
@@ -195,9 +195,8 @@ def get_action(self, node_id):
     @json_error_handler
     def accept_result(self, node_id, result):
         """Accepts the results from the node. Returns the next action if
-        :py:attr:`self.config.AUTO_GET_ACTION <Config.AUTO_GET_ACTION>`
-        is True. Otherwise returns the "nop" (no operatiotion) action.
-
+        :config:`AUTO_GET_ACTION` configuration option is True. Otherwise
+        returns the "nop" (no operatiotion) action.
 
         :param node_id: a valid node id
         :param result: the result returned by the node.
@@ -222,7 +221,7 @@ def accept_result(self, node_id, result):
             self.unsubscribe(node)
             raise e
 
-        if self.config.AUTO_GET_ACTION:
+        if self._config.AUTO_GET_ACTION:
             return self.get_action(node.id)
         return self._json_action(ACTION_NOP)
 
@@ -241,18 +240,17 @@ def _restore_session_data(self, node, result):
 
     @property
     def applications(self):
-        """Available applications container (:class:`
-        kaylee.core.Applications` object)"""
+        """Available applications container (
+        :class:`kaylee.core.Applications` object)"""
         return self._applications
 
     def _json_action(self, action, data = ''):
         return json.dumps( { 'action' : action, 'data' : data } )
 
 
 class Config(object):
-    """Kaylee Configuration repository.
-
-    TODOC.
+    """The ``Config`` object maintains the run-time Kaylee
+    configuration options (see :ref:`configuration` for full description).
     """
     serialized_attributes = [
         'AUTO_GET_ACTION',
@@ -263,10 +261,17 @@ def __init__(self, **kwargs):
         self._dirty = True
         self._cached_dict = {}
 
+        # first, set the options with default values
         self.AUTO_GET_ACTION = kwargs.get('AUTO_GET_ACTION', True)
-        self.WORKER_SCRIPT_URL = kwargs.get('WORKER_SCRIPT_URL', None)
         self.SECRET_KEY = kwargs.get('SECRET_KEY', None)
 
+        # next, set the options with required values
+        try:
+            self.WORKER_SCRIPT_URL = kwargs.get('WORKER_SCRIPT_URL', None)
+        except KeyError as e:
+            raise KeyError('The required config option is missing: {}'
+                           .format(e.args[0]))
+
     def __setattr__(self, name, value):
         if name != '_dirty':
             self.__dict__[name] = value
@@ -283,7 +288,7 @@ def to_dict(self):
 
 
 class Applications(object):
-    """A container for active Kaylee applications.
+    """A readonly dict-like container for active Kaylee applications.
 
     :param controllers: A list of :class:`Controller` objects.
     """

kaylee/node.py

@@ -30,8 +30,7 @@
 
 class Node(object):
     """
-    A Node object contains information about a node which was registered
-    by :class:`Kaylee`.
+    A Node object contains the information about a registered `Kaylee Node`.
 
     :param node_id: an instance of :class:`NodeID` or a string parsable by
                     :class:`NodeID`
@@ -97,7 +96,7 @@ def controller(self):
 
     @property
     def session_data(self):
-        """Binary session data stored in ``str``."""
+        """Binary session data (:class:`str`)"""
         return self._session_data
 
     @session_data.setter
@@ -134,8 +133,8 @@ def __hash__(self):
 
 class NodeID(object):
     """
-    NodeID is a 10-bytes long ID generated from current UNIX time,
-    remote host identifier and internal incremental counter.
+    NodeID is a 10-bytes long ID generated from the current UNIX time,
+    the remote host identifier and the internal incremental counter.
     The format is::
 
     [UNIX time (4)][counter (2)][remote host identifier hash (4)]
@@ -272,14 +271,14 @@ def binary(self):
 
     @property
     def timestamp(self):
-        """A timezone-aware :class:`datetime.datetime` instance representing
+        """A :class:`datetime.datetime` instance representing
         the current NodeID's generation time. It is precise to a second.
         """
         t = struct.unpack(">i", self._id[0:4])[0]
         return datetime.fromtimestamp(t)
 
     def __str__(self):
-        """Hex representation of the  NodeID"""
+        """Hex representation of the NodeID"""
         return binascii.hexlify(self._id).decode()
 
     def __repr__(self):
@@ -310,7 +309,7 @@ def __ge__(self, other):
         return self._id >= other._id
 
     def __hash__(self):
-        """NodeID's hash"""
+        """Python ``hash()`` of the internal id representation."""
         return hash(self._id)
 
 

kaylee/session.py

@@ -64,7 +64,7 @@ def remove_session_data_from_task(self, session_data_keys, task):
 
 
 class PhonySessionDataManager(SessionDataManager):
-    """The default session data manager which throws a :class:`KayleeError`
+    """The default session data manager which throws :class:`KayleeError`
     if any session variables are encountered in an outgoing task."""
     def store(self, node, task):
         session_data = self.get_session_data(task)
@@ -81,8 +81,8 @@ def restore(self, node, result):
 
 
 class NodeSessionDataManager(SessionDataManager):
-    """A session data manager, which utilizes :attr:`Node.session_data`
-    property."""
+    """A session data manager, which keeps the data in
+    :attr:`Node.session_data`."""
     def store(self, node, task):
         session_data = self.get_session_data(task)
         if session_data == {}:
@@ -220,6 +220,3 @@ def _decrypt_attr(data, decryptor):
     attr, val = tdata.split('=', 1)
     val = pickle.loads(val)
     return attr, val
-
-
-