README.rst

kore

Kore is a Python container-based application framework. Designed for rapid application creation. Combine your own application from reusable components and existing plugins.

Installation

Recommended way (via pip):

$ pip install kore

Alternatively you can download the code and install from the repository:

$ pip install -e git+https://github.com/p1c2u/kore.git#egg=kore

Testing

Install packages required for testing:

$ pip install -r requirements_dev.txt

Run tests with pytest:

$ py.test

Alternatively:

$ python setup.py test

Creating application

Add kore to your package requirements:

$ echo "kore" >> requirements.txt

Use existing plugins (see Enabling plugins) Create your own application plugin (see Creating component plugins) or use existing ones (see Enabling plugins)

Plugin types

There are two types of plugins:

• config plugins - allow you read application cnfiguration from different source types (i.e. INI file, Zookeeper host)
• component plugins - add components to your application (i.e. Flask app, Elasticsearch client)

See Enabling plugins

Enabling plugins

Kore has many plugins that can help you to fast create your own application.

Existing config plugins:

• kore-plugins-ini for INI file configuration

Existing component plugins:

• kore-plugins-celery for Celery application
• kore-plugins-flask for Flask application
• kore-plugins-sanic for Sanic application

See Plugin types for more information.

To enable specific plugin you just need to install that plugin. That's it!

Creating component plugins

Create your plugin module:

$ vi my_own_plugin.py

Every plugin can have many componenets. A component creates and returns a particular value or object. It has the ability to utilize an injected container to retrieve the necessary configuration settings and dependencies.

The container expects a component to adhere to the following rules:

1. It must be method.
2. It must accept the container as the only argument.
3. It must return anything except None.

There are two types of component: 1. factory - non cached component. Return value is created on every call. 2. service - cached component. Return value is created only once.

Create plugin class inside plugin module which inherits from kore.components.plugins.BasePluginComponent class:

from kore.components.plugins import BasePluginComponent


class MyOwnPlugin(BasePluginComponent):

Create get_factories method that returns two-element iterable with first element as component name and second factory function.

Create get_services method that returns two-element iterable with first element as component name and second service function.

class MyOwnPlugin(BasePluginComponent):

    def get_factories(self):
        return (
            ('my_own_component_1', self.my_own_component_1),
        )

    def get_services(self):
        return (
            ('my_own_component_2', self.my_own_component_2),
        )

    def my_own_component_1(self, container):
        return ComponentFactory()

    def my_own_component_2(self, container):
        return ComponentService()

Creating plugin hooks

A component hook is one time components usage. Inside hooks you can connect them together or configure.

You can define the following hooks:

1. Pre hook - executed before all componenets are added.
2. Post hook - executed after all componenets are added.

The container expects a component hook to adhere to the following rules:

1. It must be method.
2. It must accept the container as the only argument.

Create post_hook method inside plugin class:

class MyOwnPlugin(BasePluginComponent):

    def post_hook(self, container):
        application = container('application')
        my_own_component_1 = container('my_project.my_own_component_1')

        application.add_signal('launched', my_own_component_1)

Registering plugin

Every plugin should have entry point(s) in setup.py to be enabled.

entry_points = """\
[kore.components]
my_project = my_own_plugin:MyOwnPlugin
"""

setup(
    name='my_project',
    # ..
    entry_points=entry_points,
)

Entry point name is plugin namespace. Every component inside the plugin will be registered under that namespace.