Updated documentation according to README

docs/class_translation.rst

@@ -3,25 +3,26 @@
 Class Translation
 *****************
 
-I've recently added "automatic" class translation support, although it is
-turned off by default. This can be devastatingly slow if improperly used, so
-the following is just a short list of things to keep in mind when using it.
+The library supports an *"automatic"* class translation process, although it
+is turned off by default.
+This can be devastatingly slow if improperly used, so the following is just a
+short list of things to keep in mind when using it.
 
-* Keep It (the object) Simple Stupid. (for exceptions, keep reading.)
+* Keep It (the object) Simple Stupid. (for exceptions, keep reading)
 * Do not require init params (for exceptions, keep reading)
 * Getter properties without setters could be dangerous (read: not tested)
 
-If any of the above are issues, use the _serialize method. (see usage below)
-The server and client must BOTH have use_jsonclass configuration item on and
-they must both have access to the same libraries used by the objects for
-this to work.
+If any of the above are issues, use the ``_serialize`` method. (see usage below)
+The server and client must **BOTH** have ``use_jsonclass`` configuration
+item on and they must both have access to the same libraries used by the
+objects for this to work.
 
 If you have excessively nested arguments, it would be better to turn off the
 translation and manually invoke it on specific objects using
 ``jsonrpclib.jsonclass.dump`` / ``jsonrpclib.jsonclass.load`` (since the default
 behavior recursively goes through attributes and lists / dicts / tuples).
 
- Sample file: *test_obj.py*
+* Sample file: ``test_obj.py``
 
 .. code-block:: python
 
@@ -40,7 +41,7 @@ behavior recursively goes through attributes and lists / dicts / tuples).
        def _serialize(self):
            return (self.args, {'foo':self.foo,})
 
-* Sample usage
+* Sample usage:
 
 .. code-block:: python
 
@@ -66,12 +67,14 @@ behavior recursively goes through attributes and lists / dicts / tuples).
    {"id": "7805f1f9-9abd-49c6-81dc-dbd47229fe13", "jsonrpc": "2.0",
     "result": {"__jsonclass__": ["test_obj.TestSerial", []], "foo": "bar"}}
 
-This behavior is turned by default. To deactivate it, just set the
-``use_jsonclass`` member of a server ``Config`` to False.
+This behavior is turned on by default.
+To deactivate it, just set the ``use_jsonclass`` member of a server ``Config``
+to ``False``.
 If you want to use a per-class serialization method, set its name in the
 ``serialize_method`` member of a server ``Config``.
 Finally, if you are using classes that you have defined in the implementation
-(as in, not a separate library), you'll need to add those (on BOTH the server
-and the client) using the ``config.classes.add()`` method.
+(as in, not a separate library), you'll need to add those
+(on **BOTH** the server and the client) using the ``config.classes.add()``
+method.
 
 Feedback on this "feature" is very, VERY much appreciated.

docs/client.rst

@@ -73,6 +73,50 @@ compatibility, and ``notify`` if it's a request that you want to be a
 notification.
 
 Additionally, the ``loads`` method does not return the params and method like
-``xmlrpclib``, but instead a.) parses for errors, raising ProtocolErrors, and
+``xmlrpclib``, but instead
+a.) parses for errors, raising ProtocolErrors, and
 b.) returns the entire structure of the request / response for manual parsing.
 
+Unix Socket
+===========
+
+To connect a JSON-RPC server over a Unix socket, you have to use a specific
+protocol: ``unix+http``.
+
+When connecting to a Unix socket in the current working directory, you can use
+the following syntax: ``unix+http://my.socket``
+
+When you need to give an absolute path you must use the path part of the URL,
+the host part will be ignored. For example, you can use this URL to indicate a
+Unix socket in ``/var/lib/daemon.socket``:
+``unix+http://./var/lib/daemon.socket``
+
+**Note:** Currently, only HTTP is supported over a Unix socket.
+If you want HTTPS support to be implemented, please create an
+`issue on GitHub <https://github.com/tcalmant/jsonrpclib/issues>`_.
+
+
+Additional headers
+==================
+
+If your remote service requires custom headers in request, you can pass them
+as as a ``headers`` keyword argument, when creating the ``ServerProxy``:
+
+.. code-block:: python
+
+   >>> import jsonrpclib
+   >>> server = jsonrpclib.ServerProxy("http://localhost:8080",
+                                       headers={'X-Test' : 'Test'})
+
+You can also put additional request headers only for certain method invocation:
+
+.. code-block:: python
+
+   >>> import jsonrpclib
+   >>> server = jsonrpclib.ServerProxy("http://localhost:8080")
+   >>> with server._additional_headers({'X-Test' : 'Test'}) as test_server:
+   ...     test_server.ping(42)
+   ...
+   >>> # X-Test header will be no longer sent in requests
+
+Of course ``_additional_headers`` contexts can be nested as well.

docs/index.rst

@@ -1,13 +1,24 @@
 Welcome to JSONRPClib-pelix
 ###########################
 
-This library is an implementation of the JSON-RPC specification.
-It supports both the original 1.0 specification, as well as the
-new (proposed) 2.0 specification, which includes batch submission, keyword
-arguments, etc.
+This library implements the JSON-RPC 2.0 proposed specification in pure Python.
+It is designed to be as compatible with the syntax of ``xmlrpclib`` as possible
+(it extends where possible), so that projects using ``xmlrpclib`` could easily
+be modified to use JSON and experiment with the differences.
 
-It is licensed under the
-`Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0.html>`_.
+It is backwards-compatible with the 1.0 specification, and supports all of the
+new proposed features of 2.0, including:
+
+* Batch submission (via the ``MultiCall`` class)
+* Keyword arguments
+* Notifications (both in a batch and *normal*)
+* Class translation using the ``__jsonclass__`` key.
+
+A ``SimpleJSONRPCServer`` class has been added. It is intended to emulate the
+``SimpleXMLRPCServer`` from the default Python distribution.
+
+This library is licensed under the terms of the
+`Apache Software License 2.0 <http://www.apache.org/licenses/LICENSE-2.0.html>`_.
 
 .. toctree::
    :maxdepth: 2
@@ -68,7 +79,6 @@ Services, but it is **not** a Pelix specific implementation.
 
     * Custom headers can be sent with request and associated tests
 
-* The support for Unix sockets has been removed, as it is not trivial to convert
-  to Python 3 (and I don't use them)
+* Since version 0.4, this package added back the support of Unix sockets.
 * This version cannot be installed with the original ``jsonrpclib``, as it uses
   the same package name.

docs/installation.rst

@@ -7,10 +7,10 @@ Requirements
 ************
 
 It supports ``cjson`` and ``simplejson``, and looks for the parsers in that
-order (searching first for ``cjson``, then for the *built-in* ``json`` in 2.7,
+order (searching first for ``cjson``, then for the *built-in* ``json`` in 2.7+,
 and then the ``simplejson`` external library).
 One of these must be installed to use this library, although if you have a
-standard distribution of 2.7, you should already have one.
+standard distribution of 2.7+, you should already have one.
 Keep in mind that ``cjson`` is supposed to be the quickest, I believe, so if
 you are going for full-on optimization you may want to pick it up.
 
@@ -22,8 +22,12 @@ You can install the latest stable version from PyPI with the following command:
 
 .. code-block:: console
 
+   # Global installation
    pip install jsonrpclib-pelix
 
+   # Local installation
+   pip install --user jsonrpclib-pelix
+
 Alternatively, you can install the latest development version:
 
 .. code-block:: console

docs/server.rst

@@ -3,12 +3,13 @@
 Simple JSON-RPC Server
 **********************
 
-This is identical in usage (or should be) to the SimpleXMLRPCServer in the
+This is identical in usage (or should be) to the ``SimpleXMLRPCServer`` in the
 Python standard library. Some of the differences in features are that it
 obviously supports notification, batch calls, class translation (if left on),
 etc.
-Note: The import line is slightly different from the regular SimpleXMLRPCServer,
-since the SimpleJSONRPCServer is distributed within the ``jsonrpclib`` library.
+Note: The import line is slightly different from the regular
+``SimpleXMLRPCServer``, since the ``SimpleJSONRPCServer`` is provided by the
+``jsonrpclib`` library.
 
 .. code-block:: python
 
@@ -115,28 +116,44 @@ with a request pool doesn't have a notification pool.
        nofif_pool.stop()
        server.set_notification_pool(None)
 
+Unix Socket
+===========
 
-Additional headers
-==================
-
-If your remote service requires custom headers in request, you can pass them
-as as a ``headers`` keyword argument, when creating the ``ServerProxy``:
+To start a server listening on a Unix socket, you will have to use the
+following snippet:
 
 .. code-block:: python
 
-   >>> import jsonrpclib
-   >>> server = jsonrpclib.ServerProxy("http://localhost:8080",
-                                       headers={'X-Test' : 'Test'})
+   from jsonrpclib.SimpleJSONRPCServer import SimpleJSONRPCServer
+   import os
+   import socket
 
-You can also put additional request headers only for certain method invocation:
+   # Set the path to the socket file
+   socket_name = "/tmp/my_socket.socket"
 
-.. code-block:: python
+   # Ensure that the file doesn't exist yet (or an error will be raised)
+   if os.path.exists(socket_name):
+      os.remove(socket_name)
+
+   try:
+      # Start the server, indicating the socket family
+      # The server will force some flags when in Unix socket mode
+      # (no log request, no reuse address, ...)
+      srv = SimpleJSONRPCServer(socket_name, address_family=socket.AF_UNIX)
+
+      # ... register methods to the server
+      # Run the server
+      srv.serve_forever()
+   except KeyboardInterrupt:
+      # Shutdown the server gracefully
+      srv.shutdown()
+      srv.server_close()
+   finally:
+      # You should clean up after the server stopped
+      os.remove(socket_name)
 
-   >>> import jsonrpclib
-   >>> server = jsonrpclib.Server("http://localhost:8080")
-   >>> with server._additional_headers({'X-Test' : 'Test'}) as test_server:
-   ...     test_server.ping(42)
-   ...
-   >>> # X-Test header will be no longer sent in requests
+This feature is tested on Linux during Travis-CI builds. It also has
+been tested on Windows Subsystem for Linux (WSL) on Windows 10 1809.
 
-Of course ``_additional_headers`` contexts can be nested as well.
+This feature is not available on "pure" Windows, as it doesn't provide
+the ``AF_UNIX`` address family.