apigen
Easily create a CLI and JSON-RPC interface from a common API definition.
Installation
pip install apigen
Example API definition
I simple example application with an add command.
# from examples/basic.py
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.
@apigen.command()
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__":
apigen.run(Calculator) # 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/arguments.py
import apigen
class ArgumentsExample(apigen.Definition):
def __init__(self, quiet=False, config_path="default/path.json"):
self.quiet = quiet
self.config_path = config_path
@apigen.command()
def show_args(self, first, second, optional="Default"):
if not self.quiet:
print("noise")
return { 'first': first, 'second': second, 'optional': optional }
if __name__ == "__main__":
apigen.run(ArgumentsExample)Generated CLI interface (uses argparse)
Generated CLI interface.
# Program, command and arguments order. $ python program.py [program arguments] <command> [command arguments] # Argument format. $ python program.py positional_argument_value --optional_argument=value --flag
Showing the generated help.
# Show programm help text. $ python examples/basic.py --help # Show command help text $ python examples/basic.py 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/basic.py add 1 2 3 $ python examples/basic.py add 1.1 2.2 3.3000000000000003 $ python examples/basic.py add "foo" "bar" "foobar" $ python examples/basic.py add "[1,2,3]" "[4,5,6]" [ 1, 2, 3, 4, 5, 6 ]
Client side json-rpc usage with python-jsonrpc.
Starting the jsonrpc server from the command line.
$ python examples/basic.py 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)
3
>>> rpc.add(1.1, 2.2)
3.3000000000000003
>>> rpc.add("foo", "bar")
u'foobar'
>>> rpc.add([1,2,3], [4,5,6])
[1, 2, 3, 4, 5, 6]Client side exception handeling.
# from examples/exceptions.py
import json
import pyjsonrpc
rpc = pyjsonrpc.HttpClient(url="http://localhost:8080")
try:
print rpc.add(1, "str")
except pyjsonrpc.rpcerror.JsonRpcError as e:
print e.code # see http://www.jsonrpc.org/specification#error_object
# 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(e.data)
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 presentStarting the jsonrpc service from within python.
import basic
api = basic.Calculator()
api.startserver()Getting a pyjsonrpc.HttpRequestHandler for further use.
import basic
api = basic.Calculator()
api.get_http_request_handler()Client side json-rpc usage with javascript
// from examples/node.js
// https://www.npmjs.com/package/node-json-rpc
// npm install node-json-rpc
var rpc = require('node-json-rpc');
var client = new rpc.Client({
port: 8080,
host: '127.0.0.1',
path: '/',
});
client.call({
"jsonrpc": "2.0",
"method": "add",
"params": {
a: 1,
b: 3
},
"id": 0
},
function(err, res) {
if (err) {
console.log("Error add");
console.log(err);
} else {
console.log("Success add");
console.log(res);
}
}
);$ node examples/node.js
Success add
{ jsonrpc: '2.0', id: 0, result: 4 }
