Metadata-Version: 2.0
Name: Micro
Version: 1.0.2
Summary: Celery platform to create microservices
Home-page: https://github.com/humu1us/micro
Author: Felipe Ortiz, Pablo Ahumada
Author-email: fortizc@gmail.com, pablo.ahumadadiaz@gmail.com
License: MIT
Keywords: microservices celery
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: System
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: celery (<5,>=4)

Micro
=====

|travis| |coverage| |pypi|

A platform to create microservices available through Celery API.

Micro API
---------

Micro uses a very simple API to run, list and get information about
plugins:

-  ``plugins()``: list all available plugins.
-  ``info(plugin_name)``: show information about a specific plugin.
-  ``help(plugin_name)``: show the plugin help.
-  ``run(plugin_name, params)``: execute the given plugin.

To use this API you can use the
`Micro-dev <https://github.com/humu1us/micro-dev>`__ package who provide
two important libraries, the access to the Celery API and the PluginBase
class who allow writing Micro plugins.

API example
~~~~~~~~~~~

.. code:: python

    >>> from micro.api.endpoints import plugins, run
    >>>
    >>> plugins.delay().wait()
    {'Example plugin': 'A very simple example plugin'}
    >>>
    >>> run.delay("Example plugin", name="Micro").wait()
    'Hello Micro!!!'

Micro plugins
-------------

Write a plugin to Micro is very simple all that you need is create a
file named ``interface.py`` this file defines the plugin as follow:

.. code:: python

    from micro.plugin.pluginbase import PluginBase
    from micro.plugin.pluginbase import PluginDescription


    class ExamplePlugin(PluginBase):
      def __init__(self):
          print("This is an example plugin")

    # This is the method executed by Micro
      def run(self, **kwargs):
          return "Hello " + kwargs["name"] + "!!!"

    # This description is required by Micro
    plugin = PluginDescription(
      name="Example Plugin",
      author="Jhon Doe",
      short_desc="A very simple example plugin",
      long_desc="This plugin is a very simple example, "
                "for that reason, we don't have a long description"
      help_str="Params: name type string; A name to greet",
      instance=ExamplePlugin
    )

Each plugin needs to have its own folder inside of the plugins directory
(check the section `“Configuring
Micro” <https://github.com/humu1us/micro#configuring-micro>`__ for
details)

The plugin directory should look like this:

::

    my_plugindir/
        example-plugin/
            interface.py
            exmple_plugin_core/
                libs...
        other-plugin/
            inteface.py
            other_plugin_core/
                libs...


**IMPORTANT:** All the plugins must provide its own libraries inside of its own
namespace in order to avoid overwritting files. The general recomendation is to
use a base directory with the same name of the plugin as the example above shows

Installation
------------

PyPi:

::

    $ pip install micro

Development version:

::

    $ git clone git@github.com:humu1us/micro.git
    $ cd micro
    $ pip install .

or direct from repository:

::

    $ pip install git+ssh://git@github.com/humu1us/micro.git

Configuration
-------------

Parameters priority
~~~~~~~~~~~~~~~~~~~

Micro can be configurated through CLI, environment variables, config
file and/or default values (in that order).

Command line (CLI)
~~~~~~~~~~~~~~~~~~

These arguments are the highest priority for Micro. So, these overwrite
any other parameters set by any other method. The CLI arguments that can
be used are:

::

    $ micro -h
    usage: micro [-h] [-b BROKER_URL] [-q QUEUE_NAME] [-H HOSTNAME]
                 [-w NUM_WORKERS] [-lp LOG_PATH] [-pp PID_PATH]
                 [--default-params]

    optional arguments:
      -h, --help            show this help message and exit
      -b BROKER_URL, --broker-url BROKER_URL
                            Set the broker url
      -q QUEUE_NAME, --queue-name QUEUE_NAME
                            Set the Celery queue name
      -H HOSTNAME, --hostname HOSTNAME
                            Set the hostname for the workers
      -w NUM_WORKERS, --num-workers NUM_WORKERS
                            Set the Celery worker number
      -lp LOG_PATH, --log-path LOG_PATH
                            Set the log file path
      -pp PID_PATH, --pid-path PID_PATH
                            Set the pid file path
      --default-params      Show default parameters

Environment variables
~~~~~~~~~~~~~~~~~~~~~

The next priority in parameters for Micro are environment variables. The
list of environment variables used are:

::

    MICRO_CONFIG             # config file location: /path/to/config/config.json
    MICRO_PLUGIN_PATH        # path to plugin folder: /path/to/plugin/folder
    MICRO_LOG_PATH           # path to log folder: /path/to/plugin/folder
    MICRO_LOG_FROM           # minimun log level to write: DEBUG, INFO, WARNING, ERROR, CRITICAL or FATAL
    MICRO_BROKER_URL         # broker url: ampq://user:pass@host:port//
    MICRO_QUEUE_NAME         # queue name used
    MICRO_HOSTNAME           # workers hostname
    MICRO_NUM_WORKERS        # number of workers to create (integer number)
    MICRO_CELERY_LOG_PATH    # path to Celery log folder: /path/to/celery/log/folder
    MICRO_CELERY_PID_PATH    # path to Celery pid folder: /path/to/celery/pid/folder

**IMPORTANT:** ``MICRO_CONFIG``, ``MICRO_PLUGIN_PATH``,
``MICRO_LOG_PATH`` and ``MICRO_LOG_FROM`` variables provide the only way
to set config file, the plugin folder path, the logger file path and the
logger level.

Config file
~~~~~~~~~~~

The lowest priority is the use of a JSON config file. The path to this
config file must be set using ``MICRO_CONFIG`` environment variable.

Config file example:

.. code:: js

    {
        "broker_url": "ampq://user:pass@host:port//",
        "queue_name": "",
        "hostname": "",
        "num_workers": ,
        "log_path": "/path/to/log/folder",
        "pid_path": "/path/to/pid/folder"
    }

A config file skeleton can be created using the following command:
``$ micro --default-params > config.json``

Default values
~~~~~~~~~~~~~~

The default values are:

::

    $ micro --default-params
    {
        "broker_url": "",
        "queue_name": "micro_queue",
        "hostname": "micro",
        "num_workers": 1,
        "log_path": "/var/log",
        "pid_path": "/var/run"
    }

Docker
------

Pull
~~~~

To download from Docker Hub:

::

    $ docker pull humu1us/micro:<tag>

To check the available tags please visit `Micro’s repository on Docker
Hub <https://hub.docker.com/r/humu1us/micro/>`__

Build
~~~~~

To build the container first move to the branch/tag to use and then use
the following command:

::

    $ docker build -t micro:<tag> .

Run
~~~

Run Micro as container is pretty easy and only needs to define
``MICRO_BROKER_URL`` to set the amqp host. All Micro environment
variables are available with ``-e`` flag, for example:

::

    $ docker run -e MICRO_BROKER_URL="amqp://guest:guest@my_host:5672//" -e MICRO_NUM_WORKERS=5 micro:<tag>

The ``MICRO_BROKER_URL`` is the only mandatory environment variable to
use

Tests
-----

Run all unit tests with:

::

    $ python setup.py test

.. |travis| image:: https://img.shields.io/travis/humu1us/micro.svg?style=flat-square
   :target: https://travis-ci.org/humu1us/micro
.. |coverage| image:: https://img.shields.io/coveralls/humu1us/micro.svg?style=flat-square
   :target: https://coveralls.io/github/humu1us/micro
.. |pypi| image:: https://img.shields.io/pypi/v/Micro.svg?style=flat-square
   :target: https://pypi.python.org/pypi/Micro/


