gemstone 0.3.1

Build microservices with Python

The gemstone framework

Motivation

In the past years, the microservice-based architecture became very popular in the computing field. Although this architecture grew more and more popular, there are a few tools that can help an individual to build such systems. The current alternatives are using nameko or by building a web application that acts like a microservice. I started developing this framework in order to provide a tool for creating and managing such systems with ease, and that are capable of being specialized in a certain role, be it entity management, data storage or just computing.

Few words ahead

This library uses the asynchronous features of the Tornado web framework for creating a JSON RPC endpoint through which one can call exposed methods. The method calls are treated asynchronously. If you have no knowledge about asynchronous programming in Python, I suggest to read a few words from the Tornado documentation .

Although it is not required for you to know about all that coroutines and event loop theory, it sure helps to understand what happens under the hood.

Installation

In order to install this library, run the command

pip install gemstone

or to install it from sources

git clone https://github.com/vladcalin/gemstone.git
cd gemstone
python setup.py install

To run the tests, run the command

python setup.py test

Example basic usage

Write into a hello_world_service.py file the following code:

from gemstone import MicroService, public_method, private_api_method



class HelloWorldService(MicroService):
    name = "hello.world.service"
    host = "127.0.0.1"
    port = 5000

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

    @private_api_method
    def say_private_hello(self, name):
        return "this is secret: hello {}".format(name)

    def api_token_is_valid(self, api_token):
        return api_token == "hello_world_token"


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

After running the hello_world_service.py script, we will have a running microservice at http://localhost:5000/api . In order to interact with it, we have to use the JSONRPC protocol as follows

POST /api
{
    "jsonrpc": "2.0",
    "method": "say_hello",
    "params": {
        "name": "world"
    },
    "id": 1
}

The response will be

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

In order to access the private method, we have to include in the HTTP request an X-Api-Token header with the value hello_world, so that the method api_token_is_valid will return True (if the defaults configuration was kept).

This library offers a class through which you can interact programmatically with various services:

client = gemstone.RemoteClient("http://localhost:5000/api")
print(client.name)  # "service.hello.world"
print(client.methods.say_hello("world"))  # "hello world"

Issues

Check the Github issue tracker .

Collaborate

Any collaboration is welcome. Feel free to create new issues, make suggestions, open pull requests.

Changes

See CHANGES.MD .

0.3.1 (25.01.2017)

• fixed event loop freezing on Windows

• fixed a case when a TypeError was silenced when handling the bad parameters error in JSON RPC 2.0 handler (#21)

• major refactoring (handling of JSON RPC objects as Python objects instead of dicts and lists) to improve readability and maintainability

• improved documentation

0.3.0 (23.01.2017)

• added validation strategies (method for extraction of api token from the request)

• base subclass for implementing validation strategies

• built in validation strategies: HeaderValidationStrategy, BasicCookieStrategy

• improved documentation

0.2.0 (17.01.2017)

• added gemstone.RemoteService.get_service_by_name method

• added call command to cli

• added call_raw command to cli

• improved documentation a little

0.1.3 (16.01.2017)

• fixed manifest to include required missing files

0.1.2 (16.01.2017)

• added py36 to travis-ci

• refactored setup.py and reworked description files and documentation for better rendering

0.1.1 (13.01.2017)

• changed the name of the library from pymicroservice to gemstone

• added the gemstone.MicroService.accessible_at attribute

0.1.0 (09.01.2017)

• added the pymicroservice.PyMicroService.get_cli method

• improved documentation a little bit

0.0.4

• fixed bug when sending a notification that would result in an error was causing the microservice to respond abnormally (see #10)

• fixed a bug that was causing the service to never respond with the invalid parameters status when calling a method with invalid parameters

0.0.3

• added pymicroservice.RemoteService class

• added the pymicroservice.PyMicroService.get_service(name)

• improved documentation