Skip to main content

A framework to simplify Sanic daemon development.

Project description

# os-sanic

[![Build Status](https://www.travis-ci.org/cfhamlet/os-sanic.svg?branch=master)](https://www.travis-ci.org/cfhamlet/os-sanic)
[![codecov](https://codecov.io/gh/cfhamlet/os-sanic/branch/master/graph/badge.svg)](https://codecov.io/gh/cfhamlet/os-sanic)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/os-sanic.svg)](https://pypi.python.org/pypi/os-sanic)
[![PyPI](https://img.shields.io/pypi/v/os-sanic.svg)](https://pypi.python.org/pypi/os-sanic)

A framework to organize [Sanic](https://github.com/huge-success/sanic) project and simplify development.



## Install

```
pip install os-sanic
```

## Usage

* Create project

Typically, a project contains management script, config file and a set of reusable apps.

```
os-sanic startproject project
```

This command will create a new project(with an example app) in current directory with the following structure:

```
project/
├── apps
├── __init__.py
│ ├── example
│ │ ├── __init__.py
│ │ ├── app.py
│ │ ├── extension.py
│ │ ├── view.py
├── config.py
└── manager.py
```


* Create app

App is designed as reusable unit. Each app may has some extensions as pluggins for loading data, managing db connection. It also has [views](https://sanic.readthedocs.io/en/latest/sanic/class_based_views.html) for http requests. The definition of the app is in ``app.py``, You can check the ``example`` app for more details.


```
python manage.py startproject first
```

This command will create a app in the apps directory. You should at least add the app package string into ``INSTALLED_APPS`` in the ``config.py`` manually to enable it.

* Show the project information

```
python manage.py info
```

* Start the server

```
python manage.py run
```

This command will load ``config.py`` and start the server. Use ``--help`` to seed more command line options.


## Config

* Server config

The default config file is ``config.py``, parameters define here are used in server scope, can be accessed from the ``config`` member of ``Sanic`` instance, [more details](https://sanic.readthedocs.io/en/latest/sanic/config.html).

* Install apps

You can add app package string into ``INSTALLED_APPS`` in the ``config.py`` to make it work.

```
INSTALLED_APPS = ['apps.examples', ]
```

More verbose config can be written as following:

```
INSTALLED_APPS = [
{
'name': 'example',
'package': 'apps.example',
'root': True,
},
]
```
- ``name``: the app name, if not set will use ``package``'s last fragment
- ``package``: the app's package
- ``root``: if the ``root`` is set ``True``, the app's views will not use app name as url prefix.
- ``prefix``: use this as the app's views prefix otherwise use app name

* App definition

App is defined in the ``app.py``. ``EXTENSIONS`` and ``VIEWS`` are the core components.

``EXTENSIONS`` are used as plugin mechanism. Can be used for loadding data, manage db connection and so forth. ``name`` and ``extension_class`` are necessary, other params will pass to extension instance's config.

```
EXTENSIONS = [
{
'name': 'Example',
'extension_class': '.extension.Example',
'key1', 'value1',
},
]
```

``VIEWS`` are used for http requests. The simple style:

````
VIEWS = [('/', '.view.ExampleView'), ]
````

More verbose style which can pass params:

```
VIEWS = [
{
'uri': '/',
'view_class': '.view.ExampleView',
'key1': 'value1',
}
]
```


## APIs

* View Class

The view class is normal sanic [HTTPMethodView](https://sanic.readthedocs.io/en/latest/sanic/class_based_views.html#class-based-views). If you define extra params in the ``VIEWS``, they will be attached to a config object and pass to the view's ``__init__()``

```
from sanic.views import HTTPMethodView

class ExampleView(HTTPMethodView):

def __init__(self, config):
config.key1
```

* Extension Class

The extenion class must inherit from ``os_sanic.extension.Extension``.

The base class's members are ``name``, ``config``, ``application``, ``logger``

- ``name``: the extension name
- ``config``: if you define extra params in the ``EXTENSIONS``, they will be attached to this config object
- ``application``: a project scope object for accessing all of the apps
- ``logger``, the built-in logger object


The extension class has three usefull methods invoked by the framework, ``setup``, ``run``, ``cleanup``, they all can be normal method or async method

- ``setup``: called before server start
- ``run``: called afeter server run
- ``cleanup``: called after server stop, if there are multi extensions configured in ``EXTENSIONS``, the cleanup methods execute order will from last extension to the first one


* application object

The application object is a project scope object for accessing all of the apps.

- it is a member of extension instance:

```
from os_sanic.extension import Extension

class Example(Extension):

def setup(self):
self.application
...
```

- it can be access from the sanic app instance

```
from sanic.views import HTTPMethodView

class ExampleView(HTTPMethodView):

def get(self, request):
request.app.application
...
```

- you can get sanic app instance by:

```
application.sanic
```

- you can ge extension instance by:

```
application.get_extension('appname.extensionname')
```


## Unit Tests

```
tox
```

## License

MIT licensed.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

os-sanic-0.1.0.tar.gz (17.1 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page