v2.0.0 Django-modern-rpc

A powerful RPC framework for Django applications

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 the documentation for each one and copy/paste the command into your preferred terminal to try it by yourself. Both sync and async versions of the view are available. Use the selector on top-right to switch between them. The currently select server is available to RPC calls at this URL:

errors.custom()
xml-rpc json-rpc

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": 5409,
      "method": "errors.custom",
      "params": []
    }'

errors.unserializable_result()
xml-rpc json-rpc

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": 3672,
      "method": "errors.unserializable_result",
      "params": []
    }'

http.fetch_many(urls, timeout, max_concurrency)
xml-rpc json-rpc

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 (float | None) - 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><string>undefined</string></value>
        </param>
        <param>
        <value><int>937</int></value>
        </param>
        </params>
      </methodCall>'

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

http.get_json(url, timeout)
xml-rpc json-rpc

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 (float | None) - 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": 299,
      "method": "http.get_json",
      "params": [
        "abcde",
        "undefined"
      ]
    }'

http.get_text(url, timeout)
xml-rpc json-rpc

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 (float | None) - 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><string>undefined</string></value>
        </param>
        </params>
      </methodCall>'

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

http.sleep(seconds)
xml-rpc json-rpc

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>624.12</double></value>
        </param>
        </params>
      </methodCall>'

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

math.add(terms)
xml-rpc json-rpc

Returns the sum of two or more terms.

This procedure can be used to test variable number of inputs

Parameters:
  • terms (int | float) -
Returns:
  • int | float - 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>69.384</double></value>
        </param>
        </params>
      </methodCall>'

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

math.divide(dividend, divisor)
xml-rpc json-rpc

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 (int | float) - First term of the division
  • divisor (int | float) - Second term of the division
Returns:
  • int | float - The result 
curl -X POST '' \
    --header 'Content-Type: application/xml' \
    --data '<?xml version="1.0"?>
      <methodCall>
        <methodName>math.divide</methodName>
        <params>
        <param>
        <value><double>379.262</double></value>
        </param>
        <param>
        <value><int>881</int></value>
        </param>
        </params>
      </methodCall>'

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

math.multiply(factors)
xml-rpc json-rpc

Return the product of two or more numbers.

:raises ValueError: If fewer than two factors are provided

Parameters:
  • factors (int | float) - Two or more numeric factors to multiply, in order
Returns:
  • int | float - 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><int>10</int></value>
        </param>
        </params>
      </methodCall>'

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

math.power(base, exponent)
xml-rpc json-rpc

Raise a number to a given power.

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

Parameters:
  • base (int | float) - The base value
  • exponent (int | float) - The exponent value (can be integer or float)
Returns:
  • int | float - ``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><double>134.16</double></value>
        </param>
        <param>
        <value><double>73.901</double></value>
        </param>
        </params>
      </methodCall>'

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

math.sqrt(x)
xml-rpc json-rpc

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 (int | float) - 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>79</int></value>
        </param>
        </params>
      </methodCall>'

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

math.subtract(minuend, subtrahends)
xml-rpc json-rpc

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

:raises ValueError: If no subtrahends are provided

Parameters:
  • minuend (int | float) - The initial value from which all following values are subtracted
  • subtrahends (int | float) - One or more numbers to subtract from the minuend, in order
Returns:
  • int | float - 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><int>499</int></value>
        </param>
        <param>
        <value><double>843.862</double></value>
        </param>
        </params>
      </methodCall>'

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

system.listMethods()
xml-rpc json-rpc

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": 9844,
      "method": "system.listMethods",
      "params": []
    }'

system.methodHelp(method_name)
xml-rpc json-rpc

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": 7957,
      "method": "system.methodHelp",
      "params": [
        "abcde"
      ]
    }'

system.methodSignature(method_name)
xml-rpc json-rpc

Returns an array describing the possible signatures for the given procedure.

Currently, this procedure only returns one possible signature, so the result is a list of 1 list.

The inner list contains:

  • 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": 891,
      "method": "system.methodSignature",
      "params": [
        "abcde"
      ]
    }'

system.multicall(calls)
xml-rpc

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>'

utils.printContentType()
xml-rpc json-rpc

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": 149,
      "method": "utils.printContentType",
      "params": []
    }'

About this website

The source code of this website is available on GitHub. If you find any issue or have a suggestion, please open an issue on the project's repository.

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