JSON-RPC like protocol for Python 3

I published on Google code a JSON-RPC like protocol I developed for Python3. This is a brief description of the project that you can find here: https://github.com/kronwiz/krpc.

INTRODUCTION

The krpc protocol has been written for the Python3 language. The idea was to have a protocol that was easy to be used also from a web frontend, so it was natural to choose something based on a POST request and on JSON. For Python3 there isn't, as far as I know, a similar thing, so I wrote one from scratch. The krpc protocol is based on the JSON-RPC specification but it differs in some respects:

• it supports file uploads;
• to support file uploads it uses a standard POST request to call a method: the method invocation uses the JSON syntax and is contained in a JSON parameter; the files to be uploaded are contained in the following parts of a multipart message;
• multiple method invocations in the same request are not supported.

INSTALLATION and LICENSE

The whole implementation is contained in only one file, so you can include it in your projects. However in the package there's the usual setup.py script that installs the file system wide.

The library is under the GNU LESSER GENERAL PUBLIC LICENSE Version 3. For more information about using/distributing the library see http://www.gnu.org/copyleft/lesser.html.

EXAMPLES

Before delving into details it's important to say that if you use Python then all the inner workings are hidden and you call a remote method the same way you call a standard method.

Let's start with the standard "hello world" example. This is a simple client:

  #!/usr/bin/env python3
  # -*- coding: utf8 -*-

  from krpc import KRPCClient, KRPCClientException

  def main ():
          c = KRPCClient ( "localhost", 8080 )

          try:
                  result = c.echo ( "hello world" )
                  print ( result )

          except KRPCClientException as e:
                  print ( "error: %s\nmessage: %s\ndata: %s\n" % ( e.code, e.message, e.info ) )

  main ()

You connect to a server by creating an instance of the KRPCClient class and specifying the server host and port:

  c = KRPCClient ( "localhost", 8080 )

The remote methods are called as methods of the KRPCClient instance:

  result = c.echo ( "hello world" )

If something goes wrong the KRPCClientException is raised. Its args attribute contains the error code, the error message and some additional info (if any).

If one of the method arguments is a file object then the protocol handles the upload to the server in a transparent way and on the server side "appears" a file object pointing to the contents of the uploaded file. There's no limit to the size of the files that can be transferred.

This is all you need to know as far as the client is concerned. And what about the server? This is the server implementing the "echo" method we called in the client:

  #!/usr/bin/env python3
  # -*- coding: utf8 -*-

  from krpc import KRPCServer

  class TestClass ( object ):
          def echo ( self, msg ):
                  return msg

  def main ():
          server = KRPCServer ( "localhost", 8080 )

          test_instance = TestClass ()
          server.register_instance ( test_instance )

          print ( 'Starting server, use <Ctrl-C> to stop' )
          #server.serve_forever ()

          quit = False
          while not quit:
                  server.handle_request ()


  main ()

To create a server you have to create an instance of the KRPCServer class specifying the host and the port to which clients should connect:

  server = KRPCServer ( "localhost", 8080 )

The server publishes all the methods contained in the object that is passed to the server register_instance method:

  server.register_instance ( class_instance )

In the example above the object is an instance of TestClass and this class contains only one method named "echo": this method returns the value passed in the "msg" parameter (well, it's not that useful but it's simple).

The server is started by calling the serve_forever method or, if you need more control, by writing a loop in which you call the handle_requestmethod that waits until a request is received and handles it. By the way: when a request arrives the server forks a new process to handle it, so requests are handled in parallel.

More documentation is contained in the "docs" directory of the project.