# JSON-RPC Server for Python
This is a core implementation of JSON-RPC v2.0 server for Python.
Available adapters:
- [Django](https://github.com/marcinn/json-rpc-server-django/)
*Since version 0.5, this library only supports Python 3.*
## Features
- Service oriented
- No external dependencies
- Easy integration with frameworks
## Roadmap
- 0.5: Python3 only
- 0.6: type hinting
- 0.7: async support
- 1.0: final/stable version
## Getting started
### Installation
```
pip install damn-simple-jsonrpc-server
```
### Calculator service example
Let's make calculator service which supports `add` and `subtract` operations.
(calculator_service.py)
```python
import jsonrpcserver as rpc
calculator = rpc.Service()
@calculator.method
def add(x, y):
return x+y
@calculator.method('subtract')
def sub(x, y):
return x-y
```
Well... it's done. But where it is accessible? Nowhere!
You can access it directly by `calculator` variable, but this is nonsense.
This is an API for HTTP adapters, but not for humans.
### Exposing JSON-RPC service via HTTP
Simplest way to expose `calculator` service is to use well-known HTTP framework.
It may be a Django, for example:
(urls.py)
```python
from django.conf.urls import patterns, include, url
from .calculator_service import calculator
def calculator_service_view(request):
return calculator.handle_request_body(request.body)
urlpatterns = patterns('',
url(r'^$', calculator_service_view, name='calculator'),
)
```
But there is a simpler way! :)
#### Using existing adaptors
If you need quickly expose your service using Django, just use [damn simple JSON-RPC Django adaptor](https://pypi.python.org/pypi/damn-simple-jsonrpc-server-django),
which contains ready to use adaptor:
(urls.py)
```python
from django.conf.urls import patterns, include, url
from calculator_service import calculator
urlpatterns = patterns('',
url(r'^$', 'jsonrpcdjango.serve', kwargs={'service': calculator},
name='calculator'),
)
```
That's all. Nothing more, nothing less!
### Writing custom adaptors
JSON-RPC `Service` class has very simple API based on str/unicode or request-like object.
You may use one of the following methods available in `Service` class:
- `handle_request_body`
- `handle_http_request`
The `handle_request_body` method expects that input string will be a representation of a JSON-RPC Request object.
The `handle_http_request` method expects that request-like object will be passed as an argument.
In that case request-like object **must** contain `body` attribute with string representation
of JSON-RPC request.
Return value of `handle_request_body` and `handle_http_request` is always a str/unicode
with a JSON-RPC Response object representation (success and error responses are returned
same way, as described in http://www.jsonrpc.org/specification, but will contain `result`
and `error` keys respectively).
## Authentication, CSRF, other stuff...
Authentication and CSRF are HTTP-related topics.
You may implement them in adaptors or just use tools from your favourite HTTP framework.
For Django framework you may simply decorate whole service:
(urls.py)
```python
import jsonrpcdjango as rpc
[...]
urlpatterns = patterns('',
url(r'^$', login_required(rpc.serve), kwargs={'service': calculator},
name='calculator'),
```
To enable or disable CSRF just use specific adaptor:
- `jsonrpcdjango.serve` for CSRF-less handler
- `jsonrpcdjango.csrf_serve` for CSRF-protected handler
- or use directly Django's decorators `csrf_exempt`, `csrf_protect` or enable `CsrfViewMiddleware` (read https://docs.djangoproject.com/en/dev/ref/csrf/ for details)
*Currently there is no possibility to decorate specific methods of the service with `jsonrpcdjango` adaptor.*
## Authorization
If you want add authorization to your method you should use similar solution as for authentication.
For Django framework you may simply decorate whole service:
(urls.py)
```python
import jsonrpcdjango as rpc
[...]
urlpatterns = patterns('',
url(r'^$', permission_required('can_use_rpc')(rpc.serve), kwargs={'service': calculator},
name='calculator'),
```
*Currently there is no possibility to decorate specific methods of the service with `jsonrpcdjango` adaptor.*
## Accessing original HTTP request inside service methods
Sometimes you may need access to specific request data added somewhere
in middleware stack. In that case you can register JSON-RPC method with
additional argument `takes_http_request=True`. Original `request` object
will be passed as first argument.
If you're using Django as an HTTP framework and `jsonrpcdjango` adaptor,
you can provide access to Django's `HttpRequest` object inside service method
without any hacks. Just declare `takes_http_request=True` at registering
time. This will make your service dependend on Django, but will add more flexibility.
(calculator_service.py)
```python
calculator = rpc.Service()
[...]
@calculator.method(takes_http_request=True)
def beast_add(request, x, y):
if request.user.is_superuser:
return x+y
else:
return 666
```
## What is JSON-RPC?
JSON-RPC is a protocol similar to XML-RPC, but simpler and very lightweight.
There is no necessary to generate nor parse XML documents by using heavy libraries.
For more information please read JSON-RPC v2.0 specification: http://www.jsonrpc.org/specification
Raw data
{
"_id": null,
"home_page": null,
"name": "damn-simple-jsonrpc-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "web, json, rpc, python, server",
"author": null,
"author_email": "Marcin Nowak <marcin.j.nowak@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/84/7f/8713279b4a87da3e3f6c0a376546b7beb36893cde7445eb37cdd05872387/damn_simple_jsonrpc_server-0.5.0.tar.gz",
"platform": null,
"description": "\n\n\n\n\n\n# JSON-RPC Server for Python\n\nThis is a core implementation of JSON-RPC v2.0 server for Python.\n\nAvailable adapters:\n- [Django](https://github.com/marcinn/json-rpc-server-django/)\n\n*Since version 0.5, this library only supports Python 3.*\n\n## Features\n\n- Service oriented\n- No external dependencies\n- Easy integration with frameworks\n\n## Roadmap\n\n- 0.5: Python3 only\n- 0.6: type hinting\n- 0.7: async support\n- 1.0: final/stable version\n\n## Getting started\n\n### Installation\n\n```\npip install damn-simple-jsonrpc-server\n```\n\n### Calculator service example\n\nLet's make calculator service which supports `add` and `subtract` operations.\n\n(calculator_service.py)\n```python\n\nimport jsonrpcserver as rpc\n\ncalculator = rpc.Service()\n\n@calculator.method\ndef add(x, y):\n return x+y\n\n@calculator.method('subtract')\ndef sub(x, y):\n return x-y\n\n```\n\nWell... it's done. But where it is accessible? Nowhere!\nYou can access it directly by `calculator` variable, but this is nonsense.\nThis is an API for HTTP adapters, but not for humans.\n\n\n### Exposing JSON-RPC service via HTTP\n\nSimplest way to expose `calculator` service is to use well-known HTTP framework.\nIt may be a Django, for example:\n\n(urls.py)\n```python\n\nfrom django.conf.urls import patterns, include, url\nfrom .calculator_service import calculator\n\ndef calculator_service_view(request):\n return calculator.handle_request_body(request.body)\n\nurlpatterns = patterns('',\n url(r'^$', calculator_service_view, name='calculator'),\n)\n```\n\nBut there is a simpler way! :)\n\n\n#### Using existing adaptors\n\nIf you need quickly expose your service using Django, just use [damn simple JSON-RPC Django adaptor](https://pypi.python.org/pypi/damn-simple-jsonrpc-server-django),\nwhich contains ready to use adaptor:\n\n(urls.py)\n```python\nfrom django.conf.urls import patterns, include, url\nfrom calculator_service import calculator\n\nurlpatterns = patterns('',\n url(r'^$', 'jsonrpcdjango.serve', kwargs={'service': calculator},\n name='calculator'),\n)\n```\n\nThat's all. Nothing more, nothing less!\n\n\n### Writing custom adaptors\n\nJSON-RPC `Service` class has very simple API based on str/unicode or request-like object.\nYou may use one of the following methods available in `Service` class:\n - `handle_request_body`\n - `handle_http_request`\n\nThe `handle_request_body` method expects that input string will be a representation of a JSON-RPC Request object.\n\nThe `handle_http_request` method expects that request-like object will be passed as an argument.\nIn that case request-like object **must** contain `body` attribute with string representation\nof JSON-RPC request.\n\nReturn value of `handle_request_body` and `handle_http_request` is always a str/unicode\nwith a JSON-RPC Response object representation (success and error responses are returned\nsame way, as described in http://www.jsonrpc.org/specification, but will contain `result`\nand `error` keys respectively).\n\n\n## Authentication, CSRF, other stuff...\n\nAuthentication and CSRF are HTTP-related topics.\nYou may implement them in adaptors or just use tools from your favourite HTTP framework.\nFor Django framework you may simply decorate whole service:\n\n(urls.py)\n```python\nimport jsonrpcdjango as rpc\n\n[...]\n\nurlpatterns = patterns('',\n url(r'^$', login_required(rpc.serve), kwargs={'service': calculator},\n name='calculator'),\n```\n\nTo enable or disable CSRF just use specific adaptor:\n - `jsonrpcdjango.serve` for CSRF-less handler\n - `jsonrpcdjango.csrf_serve` for CSRF-protected handler\n - or use directly Django's decorators `csrf_exempt`, `csrf_protect` or enable `CsrfViewMiddleware` (read https://docs.djangoproject.com/en/dev/ref/csrf/ for details)\n\n*Currently there is no possibility to decorate specific methods of the service with `jsonrpcdjango` adaptor.*\n\n## Authorization\n\nIf you want add authorization to your method you should use similar solution as for authentication.\nFor Django framework you may simply decorate whole service:\n\n(urls.py)\n```python\nimport jsonrpcdjango as rpc\n\n[...]\n\nurlpatterns = patterns('',\n url(r'^$', permission_required('can_use_rpc')(rpc.serve), kwargs={'service': calculator},\n name='calculator'),\n```\n\n*Currently there is no possibility to decorate specific methods of the service with `jsonrpcdjango` adaptor.*\n\n## Accessing original HTTP request inside service methods\n\nSometimes you may need access to specific request data added somewhere\nin middleware stack. In that case you can register JSON-RPC method with\nadditional argument `takes_http_request=True`. Original `request` object\nwill be passed as first argument.\n\nIf you're using Django as an HTTP framework and `jsonrpcdjango` adaptor,\nyou can provide access to Django's `HttpRequest` object inside service method\nwithout any hacks. Just declare `takes_http_request=True` at registering\ntime. This will make your service dependend on Django, but will add more flexibility.\n\n\n(calculator_service.py)\n```python\n\ncalculator = rpc.Service()\n\n[...]\n\n@calculator.method(takes_http_request=True)\ndef beast_add(request, x, y):\n if request.user.is_superuser:\n return x+y\n else:\n return 666\n\n```\n\n## What is JSON-RPC?\n\nJSON-RPC is a protocol similar to XML-RPC, but simpler and very lightweight.\nThere is no necessary to generate nor parse XML documents by using heavy libraries.\n\nFor more information please read JSON-RPC v2.0 specification: http://www.jsonrpc.org/specification\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "Damn simple, framework-agnostic JSON-RPC server",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/marcinn/json-rpc-server"
},
"split_keywords": [
"web",
" json",
" rpc",
" python",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a54b91786f2a55f266fe7c2342a657cd0d6eb614f6de60b5e2bbd5a106da681a",
"md5": "26608002b72fdb95a961b931bcfe9d78",
"sha256": "c97530e64ff9518ed18673483d8f11e09e71f8daba5c8ce43b2bf5f166dbe1c5"
},
"downloads": -1,
"filename": "damn_simple_jsonrpc_server-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26608002b72fdb95a961b931bcfe9d78",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8620,
"upload_time": "2025-11-04T02:04:19",
"upload_time_iso_8601": "2025-11-04T02:04:19.401752Z",
"url": "https://files.pythonhosted.org/packages/a5/4b/91786f2a55f266fe7c2342a657cd0d6eb614f6de60b5e2bbd5a106da681a/damn_simple_jsonrpc_server-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "847f8713279b4a87da3e3f6c0a376546b7beb36893cde7445eb37cdd05872387",
"md5": "ff0ab75db596f1987d95589ccddcba84",
"sha256": "bc77666bf90d4ff40f3a57367d0c4559ea912552eb44218e987f25c838eeb31c"
},
"downloads": -1,
"filename": "damn_simple_jsonrpc_server-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "ff0ab75db596f1987d95589ccddcba84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8183,
"upload_time": "2025-11-04T02:04:20",
"upload_time_iso_8601": "2025-11-04T02:04:20.801586Z",
"url": "https://files.pythonhosted.org/packages/84/7f/8713279b4a87da3e3f6c0a376546b7beb36893cde7445eb37cdd05872387/damn_simple_jsonrpc_server-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-04 02:04:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marcinn",
"github_project": "json-rpc-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "damn-simple-jsonrpc-server"
}
JSON
