From f3d126a0f9f982f213160f4520216cd7012825fd Mon Sep 17 00:00:00 2001 From: David Martinez Marti Date: Mon, 6 Jun 2011 17:14:25 +0200 Subject: [PATCH] Documentation updated --- bjsonrpc/connection.py | 4 +-- bjsonrpc/exceptions.py | 6 ++-- bjsonrpc/handlers.py | 44 +++++++++++++++++++++++--- bjsonrpc/proxies.py | 4 ++- doc/source/api/bjsonrpc-exceptions.rst | 3 ++ doc/source/api/bjsonrpc-handlers.rst | 6 ++-- doc/source/api/bjsonrpc-jsonlib.rst | 6 ++++ doc/source/api/bjsonrpc-proxies.rst | 5 +++ doc/source/api/index.rst | 7 ++-- 9 files changed, 69 insertions(+), 16 deletions(-) diff --git a/bjsonrpc/connection.py b/bjsonrpc/connection.py index 2794eb1..d2fc3fc 100644 --- a/bjsonrpc/connection.py +++ b/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: diff --git a/bjsonrpc/exceptions.py b/bjsonrpc/exceptions.py index 3d01f68..7f29bcf 100644 --- a/bjsonrpc/exceptions.py +++ b/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 \ No newline at end of file diff --git a/bjsonrpc/handlers.py b/bjsonrpc/handlers.py index eefe874..1921868 100644 --- a/bjsonrpc/handlers.py +++ b/bjsonrpc/handlers.py @@ -51,6 +51,18 @@ 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+$' @@ -58,12 +70,34 @@ def getcount(self): return c 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 = {} diff --git a/bjsonrpc/proxies.py b/bjsonrpc/proxies.py index 95dcc67..db8a55a 100644 --- a/bjsonrpc/proxies.py +++ b/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): diff --git a/doc/source/api/bjsonrpc-exceptions.rst b/doc/source/api/bjsonrpc-exceptions.rst index f021971..fe7ac96 100644 --- a/doc/source/api/bjsonrpc-exceptions.rst +++ b/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 diff --git a/doc/source/api/bjsonrpc-handlers.rst b/doc/source/api/bjsonrpc-handlers.rst index 6388309..1fc786b 100644 --- a/doc/source/api/bjsonrpc-handlers.rst +++ b/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: \ No newline at end of file + \ No newline at end of file diff --git a/doc/source/api/bjsonrpc-jsonlib.rst b/doc/source/api/bjsonrpc-jsonlib.rst index 734cd32..77a78c6 100644 --- a/doc/source/api/bjsonrpc-jsonlib.rst +++ b/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 diff --git a/doc/source/api/bjsonrpc-proxies.rst b/doc/source/api/bjsonrpc-proxies.rst index 1fb49a5..e3e50f6 100644 --- a/doc/source/api/bjsonrpc-proxies.rst +++ b/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: diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 10af75f..6502ff2 100644 --- a/doc/source/api/index.rst +++ b/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