Protocollo JSON-RPC per Python3

Ho pubblicato su Google code un protocollo simile a JSON-RPC che ho sviluppato per Python3. Segue una breve descrizione del progetto che trovate qui: https://github.com/kronwiz/krpc.

INTRODUZIONE

Il protocollo krpc è stato scritto per Python3. L'idea che sta alla base è quella di avere un protocollo che sia facile da usare anche tramite un'interfaccia web, così è stato naturale scegliere qualcosa basato sulle richieste POST e su JSON come formato di comunicazione. Che io sappia, ad ora non c'è qualcosa di analogo per Python3 per cui ne ho scritto uno da zero. Il protocollo krpc è basato sulle specifiche di JSON-RPC ma differisce per alcuni aspetti:

• supporta upload di file;
• per supportare l'upload di file utilizza una richiesta POST standard per chiamare i metodi: l'invocazione del metodo utilizza la sintassi JSON per il passaggio dei parametri e i file da caricare sono contenuti nelle varie parti di un messaggio di tipo multipart;
• non è supportata l'invocazione di più metodi in una sola richiesta.

INSTALLAZIONE e LICENZA

Tutta l'implementazione è contenuta in un solo file che, quindi, è possibile includere facilmente nei propri progetti. Tuttavia nel pacchetto c'è il solito script setup.py che può essere utilizzato per installare il file nei site-packages.

La libreria è sotto la licenza GNU LESSER GENERAL PUBLIC LICENSE Version 3. Per maggiori informazioni il documento da consultare è http://www.gnu.org/copyleft/lesser.html.

ESEMPI

Prima di addentrarci nei dettagli occorre notare che se usate Python anche per il client il funzionamento è completamente nascosto e chiamare un metodo remoto è del tutto simile a chiamare un metodo su un oggetto locale.
Iniziamo con il solito esempio "hello world". Questo è un semplice 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 ()

Potete connettervi al server creando un'istanza della classe KRPCClient specificando host e porta del server:

  c = KRPCClient ( "localhost", 8080 )

I metodi remoti si invocano come se fossero metodi dell'istanza di KRPCClient che avete creato:

  result = c.echo ( "hello world" )

Se qualcosa va storto viene sollevata una eccezione di classe KRPCClientException che contiene in alcuni attributi il codice di errore, la descrizione e (se presenti) ulteriori informazioni sull'errore.
Se uno dei parametri passati al metodo è un oggetto di tipo file allora il protocollo si occupa dietro le quinte di trasferire il file al server, cosicché lato server il metodo riceve come parametro un oggetto file che punta al file appena caricato. Non ci sono limiti alla dimensione dei file che possono essere trasferiti.

Questo è tutto quello che serve sapere per quanto riguarda il client. E per quanto riguarda il server? Quello che segue è il server che implementa il metodo "echo" richiamato dal nostro client di esempio:

  #!/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 ()

Per creare un server occorre creare un'istanza della classe KRPCServer specificando l'host e la porta su cui il server rimane in attesa delle richieste:

  server = KRPCServer ( "localhost", 8080 )

Il server pubblica tutti i metodi contenuti nell'oggetto che viene passato al metodo register_instance :

  server.register_instance ( class_instance )

Nell'esempio precedente l'oggetto passato è un'istanza di TestClass contenente soltanto il metodo "echo" che restituisce esattamente il valore che gli viene passato (non è molto utile come metodo ma è semplice da capire).
Il server si avvia chiamando il suo metodo serve_forever oppure, se è necessario svolgere delle operazioni tra una richiesta e l'altra, scrivendo un ciclo in cui viene chiamato il metodo handle_request che attende e gestisce una sola richiesta.
A proposito: il protocollo crea un nuovo processo per ogni richiesta che riceve, quindi le richieste sono gestite in parallelo.
Maggiore documentazione è contenuta nella directory "docs" del progetto.