Metadata-Version: 2.0
Name: gemstone
Version: 0.2.0
Summary: Build microservices with Python
Home-page: https://github.com/vladcalin/gemstone
Author: Vlad Calin
Author-email: vlad.s.calin@gmail.com
License: MIT
Keywords: microservice,service,gemstone,jsonrpc,rpc,http,asynchronous
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: click
Requires-Dist: tornado

The **gemstone** framework
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. image:: https://travis-ci.org/vladcalin/gemstone.svg?branch=master
    :target: https://travis-ci.org/vladcalin/gemstone
.. image :: https://ci.appveyor.com/api/projects/status/i6rep3022e7occ8e?svg=true
    :target: https://ci.appveyor.com/project/vladcalin/gemstone
.. image:: https://readthedocs.org/projects/gemstone/badge/?version=latest
    :target: http://gemstone.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
.. image:: https://badge.fury.io/py/gemstone.svg
    :target: https://badge.fury.io/py/gemstone
.. image:: https://coveralls.io/repos/github/vladcalin/gemstone/badge.svg?branch=master
    :target: https://coveralls.io/github/vladcalin/gemstone?branch=master
.. image:: https://codeclimate.com/github/vladcalin/gemstone/badges/gpa.svg
    :target: https://codeclimate.com/github/vladcalin/gemstone
    :alt: Code Climate



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](https://github.com/nameko/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 <http://www.tornadoweb.org/en/stable/>`_ .

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

::

    {
        "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``.

This library offers a class through which you can interact 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 <https://github.com/vladcalin/gemstone/issues>`_ .

Collaborate
~~~~~~~~~~~

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

Changes
~~~~~~~

See `CHANGES.MD` .


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


