os-sanic 0.1.7

Description:

ossanic 0.1.7

# os-sanic[](https://www.travis-ci.org/cfhamlet/os-sanic)[](https://codecov.io/gh/cfhamlet/os-sanic)[](https://pypi.python.org/pypi/os-sanic)[](https://pypi.python.org/pypi/os-sanic)A framework to organize [Sanic](https://github.com/huge-success/sanic) project, make you focus on 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 --with-app example ``` 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 │ │ ├── handler.py │ │ ├── static │ │ │ ├── README.txt ├── config.py └── manager.py ```* Create app App is designed as reusable unit. Each app may has some extensions as pluggins for loading/dumping data, managing db connection when server starting up/down. It should has handlers for processing http/https/websocket requests. Routes(URIs to handlers) are necessary. Besides, [serving static files](https://sanic.readthedocs.io/en/latest/sanic/static_files.html) is also useful. You can check the ``example`` app for more details. ``` python manage.py startproject first ``` This command will create a app named 'first' in the apps directory. You should add the app package string into ``INSTALLED_APPS`` in the ``config.py`` manually to enable it.* Create app with full feature The sanic framework offering [Middleware](https://sanic.readthedocs.io/en/latest/sanic/middleware.html) and [Exception](https://sanic.readthedocs.io/en/latest/sanic/exceptions.html), they all can be used. The following command will create a app with middleware and error handlers. ``` python manage.py startapp second --full-feature ``` But, attention please, the middlewares and exception handler is not just working on blueprint scope right now(v18.12). They will affect on the whole project. [issue](https://github.com/huge-success/sanic/issues/37) * 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 follows: ``` INSTALLED_APPS = [ { 'name': 'example', 'package': 'apps.example', 'url_prefix': '/example', } ] ``` - ``name``: the app name, if not set will use ``package``'s last fragment - ``package``: the app's package - ``url_prefix``(alias ``prefix``): use this as the app's views prefix otherwise use app name - ``config``: app's config file, same as the ``app.py`` file, but will cover the parameters defined in ``app.py``. * App definition App is defined in the ``app.py``. ``EXTENSIONS``, ``ROUTES`` and ``STATICS`` are the main components. - ``EXTENSIONS`` are used as plugin mechanism. Can be used for loadding/dumping data, managing db connection when server staring up/down. ``name`` and ``extension_class`` are necessary, other parameters will pass to extension instance's config. ``` EXTENSIONS = [ { 'name': 'Example', 'extension_class': '.extension.Example', 'key1', 'value1', } ] ``` - ``ROUTES`` are used for specifying handlers for different URIs. All [built-in parameters](https://sanic.readthedocs.io/en/latest/sanic/routing.html) of route definition can be used. ```` ROUTES = [ ('/e1', '.handler.ExampleView'), ('/e2', '.handler.handle_post', ['post']), ('/e3', '.handler.handle_websocket', 'websocket', None, True) ] ```` More verbose style which can pass custom parameters: ``` ROUTES = [ { 'uri': '/', 'handler': '.view.ExampleView', 'costom_key': 'custom_value', } ] ``` - ``STATICS`` are used for [serving static files](https://sanic.readthedocs.io/en/latest/sanic/static_files.html). ``file_or_directory`` can be absolute or relative path base on the appliction runtime config path. ``` STATICS = [ { 'uri': '/static', 'file_or_directory': '.', } ] ```## APIs* Handler The handler can be normal function, sanic [``HTTPMethodView``](https://sanic.readthedocs.io/en/latest/sanic/class_based_views.html) class or sanic [``CompositionView``](https://sanic.readthedocs.io/en/latest/sanic/class_based_views.html#using-compositionview) instance. The parameters defined in the ``ROUTES`` will be attached to a config object. If you use ```HTTPMethodView``, the config can be accessed from the View class. ``` from sanic.views import HTTPMethodView class ExampleView(HTTPMethodView): def get(self, request): self.config.key1 ... ```* Extension Class The extenion class must inherit from ``os_sanic.extension.Extension``. The base class's members are ``config``, ``application`` and ``logger`` - ``config``: if you define extra parameters in the ``EXTENSIONS``, they will be attached to this config object - ``application``: current application object, can be used for accessing all the project apps - ``logger``, the built-in logger object The extension class has two usefull methods invoked by the framework: ``setup``, ``cleanup``. They all can be sync or async. - ``setup``: called before server start - ``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* application object The application object represent the each individual app - it is a member of extension instance: ``` from os_sanic.extension import Extension class Example(Extension): def setup(self): self.application ... ``` - it can be accessed in the view class ``` from sanic.views import HTTPMethodView class ExampleView(HTTPMethodView): def get(self, request): self.application ... ``` - you can get extension instance by: ``` application.get_extension('extension_name') ``` or get other app's extension ``` application.get_extension('app_name/extension_name') ``` - get app relative logger ``` application.get_logger('logger_name') ``` - get sanic instance(it is the same object ``request.app`` in the view) ``` application.sanic ```## Unit Tests ``` tox ```## LicenseMIT licensed.