Welcome to gemstone’s documentation!

The gemstone library aims to provide an easy way to develop simple and scalable microservices by using the asynchronous features of Python.

This library offers support for writing a microservice that:

  • exposes a public Json RPC 2.0 HTTP API (see The JSON RPC 2.0 specifications )
  • can communicate with other microservices through the JSON RPC protocol.
  • can communicate with other microservices through events (messages).

This documentation is structured in multiple parts:

  • Topics - A compilation in-depth explanations on various topics of interest.
  • Modules - The reference to the classes, functions, constants that can be used.

See also


pip install gemstone
# or
pip install gemstone[redis] # to use the Redis features
# or
pip install gemstone[rabbitmq] # to use the RabbitMq features

First look

In a script hello_world.py write the following:

import gemstone.core

class HelloWorldService(gemstone.core.MicroService):
    name = "hello_world_service"
    host = ""
    port = 8000

    def say_hello(self, name):
        return "hello {}".format(name)

if __name__ == '__main__':
    service = HelloWorldService()

We have now a microservice that exposes a public method say_hello and returns a "hello {name}".

What we did is the following:

  • declared the class of our microservice by inheriting gemstone.MicroService
  • assigned a name for our service (this is required)
  • assigned the host and the port where the microservice should listen
  • exposed a method by using the gemstone.exposed_method() decorator.
  • after that, when the script is directly executed, we start the service by calling the gemstone.MicroService.start() method.

To run it, run script

python hello_world.py

Now we have the service listening on http://localhost:8000/api (the default configuration for the URL endpoint). In order to test it, you have to do a HTTP POST request to that URL with the content:

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d '{"jsonrpc": "2.0","id": 1,"method": "say_hello","params": {"name": "world"}}' \

The answer should be

{"result": "hello world", "error": null, "jsonrpc": "2.0", "id": 1}

Table of contents:


Make this use self.io_loop to resolve the request. The current implementation is blocking and slow

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/pymicroservice/envs/latest/lib/python3.5/site-packages/gemstone-0.12.0-py3.5.egg/gemstone/core/microservice.py:docstring of gemstone.core.MicroService.get_service, line 7.)

Indices and tables