Documentation updated

bjsonrpc/connection.py

@@ -662,10 +662,10 @@ def close(self):
 
     def write_line(self, data):
         """
-            Write a line *data* to socket. It appends a `\\n` at
+            Write a line *data* to socket. It appends a **newline** at
             the end of the *data* before sending it.
             
-            The string MUST NOT contain `\\n` otherwise an AssertionError will
+            The string MUST NOT contain **newline** otherwise an AssertionError will
             raise.
             
             Parameters:

bjsonrpc/exceptions.py

@@ -34,13 +34,15 @@
 class ServerError(Exception):
     """
         Exception raised whenever an error occurs in the other end handling 
-        your request.
+        your request. You may create your own versions of this class to send
+        custom exceptions through RPC.
     """
     pass
 
 class EofError(Exception):
     """
         End-of-file error raised whenever the socket reaches the 
-        end of the sream.
+        end of the sream. In normal operation, this error never is sent to the
+        developer. If you get this error, it may be a bug.
     """
     pass    

bjsonrpc/handlers.py

@@ -51,19 +51,53 @@ def echo(self,text):
                     self.c += 1
                     
                 def getcount(self): return c
+        
+        Other members:
+        
+        **public_methods_pattern**
+            RegEx string that returns True if the method name is suitable for
+            publishing. Defaults to r'^[a-z]\w+$'
+        
+        **nonpublic_methods**
+            List of string containing names that shouldn't be published (even 
+            if they are in the format required by the RegEx). Defaults to
+            ["close","_factory","add_method","get_method"]
+            
     """
 
     public_methods_pattern = r'^[a-z]\w+$'
     # Pattern to know which methods should be automatically published
 
     nonpublic_methods = [
         "close",
+        "_factory",
         "add_method",
         "get_method",
         ] 
     # List of method names that never should be published    
-
-    def __init__(self, connection):
+
+    @classmethod
+    def _factory(cls, *args, **kwargs):
+        """
+            *New in bjsonrpc v0.2.1*
+            
+            Classmethod aimed to create flavoured instances of BaseHandler.
+            When you create a new connection you may want to give the constructor
+            a set of specific arguments. Use this classmethod to do that:
+            
+                conn = bjsonrpc.connect(handler_factory=MyHandler._factory("my flavoured one"))
+                
+            Later, whenever the class is instantiated, the BaseHandler.setup 
+            method will receive the arguments passed to factory.
+            
+            The original idea for this feature is from Paul Pietkiewicz *(pawel.pietkiewicz (at) gmail.com)*
+        """
+        def handler_factory(connection):
+            handler = cls(connection, *args, **kwargs)
+            return handler
+        return handler_factory
+
+    def __init__(self, connection, *args, **kwargs):
         self._conn = connection
 
         if hasattr(self._conn,"connection"): 
@@ -78,9 +112,9 @@ def __init__(self, connection):
                 if isinstance(function, MethodType):
                     self.add_method(function)
 
-        self._setup()
+        self._setup(*args,**kwargs)
 
-    def _setup(self):
+    def _setup(self,*args,**kwargs):
         """
             Empty method to ease inheritance. Overload it with your needs, it
             will be called after __init__.
@@ -97,7 +131,7 @@ def _shutdown(self):
 
     def close(self):
         """
-            Cleans some variables before the object is freed. _close is called
+            Cleans some variables before the object is freed. close is called
             manually from connection whenever a handler is going to be deleted.
         """
         self._methods = {}

bjsonrpc/proxies.py

@@ -13,6 +13,7 @@
 class Proxy(object):
     """
     Object that forwards calls to the remote.
+    This class is intended to be instantiated from Connection class.
     
     Parameters:
     
@@ -23,7 +24,8 @@ class Proxy(object):
         synchronization type. 0-synchronous. 1-asynchronous. 2-notification.
         
     **obj** = None
-        optional. Object name to call their functions, (used to proxy functions of *RemoteObject*
+        optional. Object name to call their functions, (used to proxy 
+        functions of *RemoteObject*)
         
     """
     def __init__(self, conn, sync_type, obj = None):

doc/source/api/bjsonrpc-exceptions.rst

@@ -2,5 +2,8 @@
 
 Module bjsonrpc.exceptions
 --------------------------    
+These area the exceptions defined by bjsonrpc. You can create your own exceptions
+by creating a child class of bjsonrpc.exceptions.ServerError.
+
 .. autoexception:: bjsonrpc.exceptions.EofError
 .. autoexception:: bjsonrpc.exceptions.ServerError

doc/source/api/bjsonrpc-handlers.rst

@@ -3,11 +3,9 @@
 Module bjsonrpc.handlers 
 ---------------------------
 .. autoclass:: bjsonrpc.handlers.BaseHandler
-    :members: _setup
-    :undoc-members: 
-    :inherited-members:
+    :members: _setup, _shutdown, _factory, add_method, get_method, close
 
 .. autoclass:: bjsonrpc.handlers.NullHandler
     :members:
     :undoc-members: 
-    :inherited-members:
+

doc/source/api/bjsonrpc-jsonlib.rst

@@ -3,6 +3,12 @@
 
 Module bjsonrpc.jsonlib 
 ------------------------    
+
+This module wraps a json library and maps their import/export methods to dumps
+and loads. First it tries to load *simplejson* and if it fails it tries *json* (the
+internal JSON library for python2.6 or newer)
+
+
 .. autofunction:: bjsonrpc.jsonlib.dumps
 
 .. autofunction:: bjsonrpc.jsonlib.loads

doc/source/api/bjsonrpc-proxies.rst

@@ -2,6 +2,11 @@
 
 Module bjsonrpc.proxies
 -------------------------    
+
+This module contains only one Proxy, and it is intended for internal use. 
+Generally you should access to proxies using *Connections* and *RemoteObject* 
+classes.
+
 .. autoclass:: bjsonrpc.proxies.Proxy
     :members:
     :undoc-members: 

doc/source/api/index.rst

@@ -34,6 +34,11 @@ for server requests.
 bjsonrpc provides two helper functions to easily create 
 a server or a connection, linked to a socket:
 
+.. autofunction:: bjsonrpc.createserver
+
+.. autofunction:: bjsonrpc.connect
+
+Other module attributes:
 
 .. attribute:: bjsonrpc.__version__
 
@@ -51,6 +56,4 @@ a server or a connection, linked to a socket:
     **threaded**
         (Default: False) When is set to True, threads will be created for handling 
         each incoming item.
-.. autofunction:: bjsonrpc.createserver
 
-.. autofunction:: bjsonrpc.connect