Skip to content
This repository
Browse code

Documentation updated

  • Loading branch information...
commit f3d126a0f9f982f213160f4520216cd7012825fd 1 parent d22f4b9
David Martínez Martí authored June 06, 2011
4  bjsonrpc/connection.py
@@ -662,10 +662,10 @@ def close(self):
662 662
     
663 663
     def write_line(self, data):
664 664
         """
665  
-            Write a line *data* to socket. It appends a `\\n` at
  665
+            Write a line *data* to socket. It appends a **newline** at
666 666
             the end of the *data* before sending it.
667 667
             
668  
-            The string MUST NOT contain `\\n` otherwise an AssertionError will
  668
+            The string MUST NOT contain **newline** otherwise an AssertionError will
669 669
             raise.
670 670
             
671 671
             Parameters:
6  bjsonrpc/exceptions.py
@@ -34,13 +34,15 @@
34 34
 class ServerError(Exception):
35 35
     """
36 36
         Exception raised whenever an error occurs in the other end handling 
37  
-        your request.
  37
+        your request. You may create your own versions of this class to send
  38
+        custom exceptions through RPC.
38 39
     """
39 40
     pass
40 41
 
41 42
 class EofError(Exception):
42 43
     """
43 44
         End-of-file error raised whenever the socket reaches the 
44  
-        end of the sream.
  45
+        end of the sream. In normal operation, this error never is sent to the
  46
+        developer. If you get this error, it may be a bug.
45 47
     """
46 48
     pass    
44  bjsonrpc/handlers.py
@@ -51,6 +51,18 @@ def echo(self,text):
51 51
                     self.c += 1
52 52
                     
53 53
                 def getcount(self): return c
  54
+        
  55
+        Other members:
  56
+        
  57
+        **public_methods_pattern**
  58
+            RegEx string that returns True if the method name is suitable for
  59
+            publishing. Defaults to r'^[a-z]\w+$'
  60
+        
  61
+        **nonpublic_methods**
  62
+            List of string containing names that shouldn't be published (even 
  63
+            if they are in the format required by the RegEx). Defaults to
  64
+            ["close","_factory","add_method","get_method"]
  65
+            
54 66
     """
55 67
     
56 68
     public_methods_pattern = r'^[a-z]\w+$'
@@ -58,12 +70,34 @@ def getcount(self): return c
58 70
     
59 71
     nonpublic_methods = [
60 72
         "close",
  73
+        "_factory",
61 74
         "add_method",
62 75
         "get_method",
63 76
         ] 
64 77
     # List of method names that never should be published    
65  
-        
66  
-    def __init__(self, connection):
  78
+    
  79
+    @classmethod
  80
+    def _factory(cls, *args, **kwargs):
  81
+        """
  82
+            *New in bjsonrpc v0.2.1*
  83
+            
  84
+            Classmethod aimed to create flavoured instances of BaseHandler.
  85
+            When you create a new connection you may want to give the constructor
  86
+            a set of specific arguments. Use this classmethod to do that:
  87
+            
  88
+                conn = bjsonrpc.connect(handler_factory=MyHandler._factory("my flavoured one"))
  89
+                
  90
+            Later, whenever the class is instantiated, the BaseHandler.setup 
  91
+            method will receive the arguments passed to factory.
  92
+            
  93
+            The original idea for this feature is from Paul Pietkiewicz *(pawel.pietkiewicz (at) gmail.com)*
  94
+        """
  95
+        def handler_factory(connection):
  96
+            handler = cls(connection, *args, **kwargs)
  97
+            return handler
  98
+        return handler_factory
  99
+    
  100
+    def __init__(self, connection, *args, **kwargs):
67 101
         self._conn = connection
68 102
         
69 103
         if hasattr(self._conn,"connection"): 
@@ -78,9 +112,9 @@ def __init__(self, connection):
78 112
                 if isinstance(function, MethodType):
79 113
                     self.add_method(function)
80 114
             
81  
-        self._setup()
  115
+        self._setup(*args,**kwargs)
82 116
         
83  
-    def _setup(self):
  117
+    def _setup(self,*args,**kwargs):
84 118
         """
85 119
             Empty method to ease inheritance. Overload it with your needs, it
86 120
             will be called after __init__.
@@ -97,7 +131,7 @@ def _shutdown(self):
97 131
         
98 132
     def close(self):
99 133
         """
100  
-            Cleans some variables before the object is freed. _close is called
  134
+            Cleans some variables before the object is freed. close is called
101 135
             manually from connection whenever a handler is going to be deleted.
102 136
         """
103 137
         self._methods = {}
4  bjsonrpc/proxies.py
@@ -13,6 +13,7 @@
13 13
 class Proxy(object):
14 14
     """
15 15
     Object that forwards calls to the remote.
  16
+    This class is intended to be instantiated from Connection class.
16 17
     
17 18
     Parameters:
18 19
     
@@ -23,7 +24,8 @@ class Proxy(object):
23 24
         synchronization type. 0-synchronous. 1-asynchronous. 2-notification.
24 25
         
25 26
     **obj** = None
26  
-        optional. Object name to call their functions, (used to proxy functions of *RemoteObject*
  27
+        optional. Object name to call their functions, (used to proxy 
  28
+        functions of *RemoteObject*)
27 29
         
28 30
     """
29 31
     def __init__(self, conn, sync_type, obj = None):
3  doc/source/api/bjsonrpc-exceptions.rst
Source Rendered
@@ -2,5 +2,8 @@
2 2
 
3 3
 Module bjsonrpc.exceptions
4 4
 --------------------------    
  5
+These area the exceptions defined by bjsonrpc. You can create your own exceptions
  6
+by creating a child class of bjsonrpc.exceptions.ServerError.
  7
+
5 8
 .. autoexception:: bjsonrpc.exceptions.EofError
6 9
 .. autoexception:: bjsonrpc.exceptions.ServerError
6  doc/source/api/bjsonrpc-handlers.rst
Source Rendered
@@ -3,11 +3,9 @@
3 3
 Module bjsonrpc.handlers 
4 4
 ---------------------------
5 5
 .. autoclass:: bjsonrpc.handlers.BaseHandler
6  
-    :members: _setup
7  
-    :undoc-members: 
8  
-    :inherited-members:
  6
+    :members: _setup, _shutdown, _factory, add_method, get_method, close
9 7
     
10 8
 .. autoclass:: bjsonrpc.handlers.NullHandler
11 9
     :members:
12 10
     :undoc-members: 
13  
-    :inherited-members:
  11
+    
6  doc/source/api/bjsonrpc-jsonlib.rst
Source Rendered
@@ -3,6 +3,12 @@
3 3
     
4 4
 Module bjsonrpc.jsonlib 
5 5
 ------------------------    
  6
+
  7
+This module wraps a json library and maps their import/export methods to dumps
  8
+and loads. First it tries to load *simplejson* and if it fails it tries *json* (the
  9
+internal JSON library for python2.6 or newer)
  10
+
  11
+
6 12
 .. autofunction:: bjsonrpc.jsonlib.dumps
7 13
     
8 14
 .. autofunction:: bjsonrpc.jsonlib.loads
5  doc/source/api/bjsonrpc-proxies.rst
Source Rendered
@@ -2,6 +2,11 @@
2 2
 
3 3
 Module bjsonrpc.proxies
4 4
 -------------------------    
  5
+
  6
+This module contains only one Proxy, and it is intended for internal use. 
  7
+Generally you should access to proxies using *Connections* and *RemoteObject* 
  8
+classes.
  9
+
5 10
 .. autoclass:: bjsonrpc.proxies.Proxy
6 11
     :members:
7 12
     :undoc-members: 
7  doc/source/api/index.rst
Source Rendered
@@ -34,6 +34,11 @@ for server requests.
34 34
 bjsonrpc provides two helper functions to easily create 
35 35
 a server or a connection, linked to a socket:
36 36
 
  37
+.. autofunction:: bjsonrpc.createserver
  38
+
  39
+.. autofunction:: bjsonrpc.connect
  40
+
  41
+Other module attributes:
37 42
     
38 43
 .. attribute:: bjsonrpc.__version__
39 44
 
@@ -51,6 +56,4 @@ a server or a connection, linked to a socket:
51 56
     **threaded**
52 57
         (Default: False) When is set to True, threads will be created for handling 
53 58
         each incoming item.
54  
-.. autofunction:: bjsonrpc.createserver
55 59
 
56  
-.. autofunction:: bjsonrpc.connect

0 notes on commit f3d126a

Please sign in to comment.
Something went wrong with that request. Please try again.