Django-modern-rpc

A powerful RPC framework for Django applications

v2.0a3
Get Started

Introduction

Django-modern-rpc is a Django library that helps you enable JSON and XML-RPC servers in your application. It is easy to install and configure, and highly customizable. This website shows the library in action.

Source code Documentation Library on PyPi
Remote procedures

Here is the full list of procedures exposed by this demo application. You can read documentation for each one and copy/paste the command to test it by yourself.

You can try the library right now. Simply make RPC calls using your preferred client to the address:

errors.custom()

Raise a custom RPC exception.

:raises RPCException: Always raised with a custom error code and message.

Parameters:
This procedure has no arguments documentation
Returns:
No documentation on return types available yet 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>errors.custom</methodName>
        <params>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 2997,
      "method": "errors.custom",
      "params": []
    }'

errors.unserializable_result()

Return a value that cannot be serialized by the RPC transport.

Specifically, this procedure returns an instance of Python’s built-in Fraction class, which is not JSON-serializable by default.

Parameters:
This procedure has no arguments documentation
Returns:
  • Fraction - An unserializable Fraction instance. 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>errors.unserializable_result</methodName>
        <params>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 6282,
      "method": "errors.unserializable_result",
      "params": []
    }'

http.fetch_many(urls, timeout, max_concurrency)

Fetch many URLs concurrently with a concurrency limit.

This demonstrates awaiting multiple async tasks via asyncio.Semaphore and asyncio.gather.

Parameters:
  • urls (Iterable) - An iterable of URLs to fetch
  • timeout (Union) - Request timeout per request (seconds)
  • max_concurrency (int) - Max number of concurrent requests
Returns:
  • list - A list of response dicts in the same order as input URLs 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>http.fetch_many</methodName>
        <params>
        <param>
        <value><string>undefined</string></value>
        </param>
        <param>
        <value><double>464.994</double></value>
        </param>
        <param>
        <value><int>655</int></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 2220,
      "method": "http.fetch_many",
      "params": [
        "undefined",
        582.045,
        286
      ]
    }'

http.get_json(url, timeout)

Perform an async HTTP GET request and parse JSON body.

:raises httpx.HTTPError: On network or protocol errors :raises ValueError: If the response body is not valid JSON

Parameters:
  • url (str) - The URL to fetch
  • timeout (Union) - Request timeout in seconds (None = no timeout)
Returns:
  • dict - A dict containing ``url``, ``status``, ``headers``, and parsed ``json`` data 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>http.get_json</methodName>
        <params>
        <param>
        <value><string>abcde</string></value>
        </param>
        <param>
        <value><string>undefined</string></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 8868,
      "method": "http.get_json",
      "params": [
        "abcde",
        288.436
      ]
    }'

http.get_text(url, timeout)

Perform an async HTTP GET request and return response metadata and text body.

:raises httpx.HTTPError: On network or protocol errors

Parameters:
  • url (str) - The URL to fetch
  • timeout (Union) - Request timeout in seconds (None = no timeout)
Returns:
  • dict - A dict containing ``url``, ``status``, ``headers``, and ``text`` 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>http.get_text</methodName>
        <params>
        <param>
        <value><string>abcde</string></value>
        </param>
        <param>
        <value><double>998.752</double></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 9107,
      "method": "http.get_text",
      "params": [
        "abcde",
        "undefined"
      ]
    }'

http.sleep(seconds)

Await for the given number of seconds, then return the same value.

This demonstrates a minimal async RPC procedure that awaits an IO-bound task.

Parameters:
  • seconds (float) - Number of seconds to await (fractions allowed)
Returns:
  • float - The number of seconds actually awaited 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>http.sleep</methodName>
        <params>
        <param>
        <value><double>179.706</double></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 1845,
      "method": "http.sleep",
      "params": [
        781.387
      ]
    }'

math.add(terms)

Returns the sum of two or more terms.

This procedure can be used to test variable number of inputs

Parameters:
  • terms (Union) -
Returns:
  • Union - Sum of the two terms 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.add</methodName>
        <params>
        <param>
        <value><double>546.915</double></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 4930,
      "method": "math.add",
      "params": [
        977.887
      ]
    }'

math.divide(dividend, divisor)

Returns the division result of two numbers.

This procedure can be used to raise an exception. If divisor is set to 0, a ZeroDivisionError will be raised from the function and transformed into a proper RPC Error response.

Parameters:
  • dividend (Union) - First term of the division
  • divisor (Union) - Second term of the division
Returns:
  • Union - The result 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.divide</methodName>
        <params>
        <param>
        <value><double>355.166</double></value>
        </param>
        <param>
        <value><int>36</int></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 8035,
      "method": "math.divide",
      "params": [
        226,
        805.371
      ]
    }'

math.multiply(factors)

Return the product of two or more numbers.

:raises ValueError: If fewer than two factors are provided

Parameters:
  • factors (Union) - Two or more numeric factors to multiply, in order
Returns:
  • Union - The multiplication result, computed as the product of all provided ``factors`` 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.multiply</methodName>
        <params>
        <param>
        <value><double>337.122</double></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 4640,
      "method": "math.multiply",
      "params": [
        173.93
      ]
    }'

math.power(base, exponent)

Raise a number to a given power.

This is equivalent to Python's base ** exponent.

Parameters:
  • base (Union) - The base value
  • exponent (Union) - The exponent value (can be integer or float)
Returns:
  • Union - ``base`` raised to the power of ``exponent`` 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.power</methodName>
        <params>
        <param>
        <value><int>879</int></value>
        </param>
        <param>
        <value><int>779</int></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 7905,
      "method": "math.power",
      "params": [
        103,
        582.393
      ]
    }'

math.sqrt(x)

Return the non-negative square root of x.

This is a thin wrapper around math.sqrt. If x is negative, math.sqrt raises ValueError which will be converted into a proper RPC error by the framework.

:raises ValueError: If x is negative

Parameters:
  • x (Union) - The value whose square root is requested
Returns:
  • float - The square root of ``x`` as a floating-point number 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.sqrt</methodName>
        <params>
        <param>
        <value><int>15</int></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 1713,
      "method": "math.sqrt",
      "params": [
        126.566
      ]
    }'

math.subtract(minuend, subtrahends)

Return the result of subtracting one or more numbers from a first value.

:raises ValueError: If no subtrahends are provided

Parameters:
  • minuend (Union) - The initial value from which all following values are subtracted
  • subtrahends (Union) - One or more numbers to subtract from the minuend, in order
Returns:
  • Union - The subtraction result, computed as ``minuend - subtrahends[0] - subtrahends[1] - ...`` 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.subtract</methodName>
        <params>
        <param>
        <value><double>427.161</double></value>
        </param>
        <param>
        <value><double>264.046</double></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 5349,
      "method": "math.subtract",
      "params": [
        295,
        814
      ]
    }'

system.listMethods()

Returns a list of all procedures exposed by the server

Parameters:
This procedure has no arguments documentation
Returns:
No documentation on return types available yet 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>system.listMethods</methodName>
        <params>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 615,
      "method": "system.listMethods",
      "params": []
    }'

system.methodHelp(method_name)

Returns the documentation of the given procedure.

Parameters:
  • method_name (str) - Name of the procedure
Returns:
  • Documentation text for the procedure 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>system.methodHelp</methodName>
        <params>
        <param>
        <value><string>abcde</string></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 510,
      "method": "system.methodHelp",
      "params": [
        "abcde"
      ]
    }'

system.methodSignature(method_name)

Returns an array describing the signature of the given procedure.

The result is a list with:

  • Return type as first element
  • Types of arguments from element 1 to N
Parameters:
  • method_name (str) - Name of the procedure
Returns:
  • An array of arrays describing types of return values and method arguments 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>system.methodSignature</methodName>
        <params>
        <param>
        <value><string>abcde</string></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 2402,
      "method": "system.methodSignature",
      "params": [
        "abcde"
      ]
    }'

system.multicall(calls)

Call multiple procedure at once.

Parameters:
  • calls (list) - An array of struct like {"methodName": string, "params": [..., ...]}
Returns:
  • An array containing the result of each procedure call 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>system.multicall</methodName>
        <params>
        <param>
        <value><string>undefined</string></value>
        </param>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 9771,
      "method": "system.multicall",
      "params": [
        "undefined"
      ]
    }'

utils.printContentType()

Inspect the incoming request and extract the Content-Type header if present. This procedure demonstrates how a remote procedure can access the request object.

Parameters:
This procedure has no arguments documentation
Returns:
  • str - The Content-Type value for the incoming request, or an empty string if not set. 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>utils.printContentType</methodName>
        <params>
        </params>
      </methodCall>'

curl -X POST '' \
    --header 'Content-Type: application/json' \
    --data '{
      "jsonrpc": "2.0",
      "id": 8007,
      "method": "utils.printContentType",
      "params": []
    }'

About this website

The source code of this website is available on GitHub.

View Source

About django-modern-rpc

If you use this library in your project and want to help increasing its visibility, just go to djangopackages and vote for the library. Thank you!

Vote Now