Skip to main content

Easily create a CLI and JSON-RPC interface from a common API definition.

Project description

Easily create a CLI and JSON-RPC interface from a common API definition.


pip install apigen

Example API definition

I simple example application with an add command.

# from examples/
import apigen

# automatically added verison command will use module version if present
# rpc exceptions will also include module version if persent
__version__ = "1.0.0"

class Calculator(apigen.Definition):  # Programm name taken from class name.
    """Example Programm"""  # Programm help text taken from class doc string.

    def add(self, a, b):  # Command name and args taken from method.
        """adds two items"""  # Help text taken from method doc string.
        return a + b  # Returned rpc/cli output (must be JSON serializable).

if __name__ == "__main__":  # Run CLI interface.

The created CLI/RPC interface behaves as you would expect from a python class.

  • Programm arguments are taken from the __init__ method.
  • Command arguments are taken from the respective command methods.
  • Manditory and optional arguments work just like you would expect in python.
  • In addition arguments with the default value False are flags in the CLI.
# from examples/
import apigen

class ArgumentsExample(apigen.Definition):

    def __init__(self, quiet=False, config_path="default/path.json"):
        self.quiet = quiet
        self.config_path = config_path

    def show_args(self, first, second, optional="Default"):
        if not self.quiet:
        return { 'first': first, 'second': second, 'optional': optional }

if __name__ == "__main__":

Generated CLI interface (uses argparse)

Generated CLI interface.

# Program, command and arguments order.
$ python [program arguments] <command> [command arguments]

# Argument format.
$ python positional_argument_value --optional_argument=value --flag

Showing the generated help.

# Show programm help text.
$ python examples/ --help

# Show command help text
$ python examples/ startserver --help

CLI arguments must be given as json data.The json data automatically is unmarshalled before calling the command function and the returned result is automatically marshalled.

$ python examples/ add 1 2

$ python examples/ add 1.1 2.2

$ python examples/ add "foo" "bar"

$ python examples/ add "[1,2,3]" "[4,5,6]"

Client side json-rpc usage with python-jsonrpc.

Starting the jsonrpc server from the command line.

$ python examples/ startserver
Starting Calculator json-rpc service at http://localhost:8080

RPC arguments must be given as json serializable data. The arguments will automatically be marshalled and unmarshalled.

>>> import pyjsonrpc

>>> rpc = pyjsonrpc.HttpClient(url = "http://localhost:8080")

>>> rpc.add(1, 2)

>>> rpc.add(1.1, 2.2)

>>> rpc.add("foo", "bar")

>>> rpc.add([1,2,3], [4,5,6])
[1, 2, 3, 4, 5, 6]

Client side exception handeling.

# from examples/
import json
import pyjsonrpc

rpc = pyjsonrpc.HttpClient(url="http://localhost:8080")
    print rpc.add(1, "str")
except pyjsonrpc.rpcerror.JsonRpcError as e:
    print e.code  # see

    # Server error if an exception is raised during the call.
    if e.code <= -32000 and e.code >= -32099:
        print e.message  # source exception message
        data = json.loads(
        print data["classname"]  # source exception class name
        print data["repr"]  # source exception repr string
        print data["traceback"]  # source exception traceback
        print data["version"]  # source module version if present

Starting the jsonrpc service from within python.

import basic
api = basic.Calculator()

Getting a pyjsonrpc.HttpRequestHandler for further use.

import basic
api = basic.Calculator()

Client side json-rpc usage with javascript

// from examples/node.js

// npm install node-json-rpc
var rpc = require('node-json-rpc');

var client = new rpc.Client({
      port: 8080,
      host: '',
      path: '/',
    "jsonrpc": "2.0",
    "method": "add",
    "params": {
      a: 1,
      b: 3
    "id": 0
  function(err, res) {
    if (err) {
      console.log("Error add");
    } else {
      console.log("Success add");
$ node examples/node.js
Success add
{ jsonrpc: '2.0', id: 0, result: 4 }

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
apigen-1.5.0-py2-none-any.whl (9.5 kB) Copy SHA256 hash SHA256 Wheel 2.7

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page