Permalink
Browse files

Updated documentation.

  • Loading branch information...
BasicWolf committed Dec 12, 2012
1 parent 0f4e99f commit 65b28aa86d33ae2d5febce69768ba9983798e184
View
@@ -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?
View
@@ -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/
-
View
@@ -112,4 +112,5 @@
# APPLICATIONS = [app_human_ocr_1]
# APPLICATIONS = [app_hash_cracker_1]
-APPLICATIONS = [app_hash_cracker_2]
+# APPLICATIONS = [app_hash_cracker_2]
+
View
@@ -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)
@@ -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::
View
@@ -32,7 +32,7 @@ method, this part of the documentation is for you.
.. toctree::
:maxdepth: 1
- config
+ configuration
Additional Notes
----------------
View
@@ -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.
-
View
@@ -43,12 +43,6 @@ Kaylee Object
.. :inherited-members:
-Config Object
-.............
-
-.. autoclass:: kaylee.core.Config
-
-
Applications Object
...................
View
@@ -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.
"""
View
@@ -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)
View
@@ -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
-
-
-

0 comments on commit 65b28aa

Please sign in to comment.