muffin 0.0.96

web framework based on Asyncio stack

The Muffin

The Muffin – A web framework based on Asyncio stack. (early alpha)

Contents

• The Muffin

  • Requirements

  • Benchmarks

  • Installation

  • Plugins

  • Getting Started

    • Configuration

      • Base application options

    • CLI integration

      • Write a custom command

  • Testing

    • Setup tests

    • Testing application

  • Deployment

  • Bug tracker

  • Contributing

  • Contributors

  • License

Requirements

• python >= 3.3

Benchmarks

You could find some tests here: http://klen.github.io/py-frameworks-bench/

Installation

The Muffin should be installed using pip:

pip install muffin

Plugins

The Muffin has a plugins support.

• Muffin-Admin – Basic Admin interface

• Muffin-DebugToolbar – Debug Toolbar

• Muffin-Jinja2 – Jinja2 templates

• Muffin-Jade – Jade templates

• Muffin-Mongo – MongoDB (pymongo) support

• Muffin-OAuth – OAuth client

• Muffin-Peewee – Peewee support (SQL, ORM)

• Muffin-REST – Helpers for building REST API

• Muffin-Redis – Redis support

• Muffin-Sentry – Sentry integration

• Muffin-Session – User session (auth)

Getting Started

Hello World example hello.py

import muffin

app = muffin.Application('example')

@app.register('/')
def index(request):
    return 'Hello, World!'

Run with command:

$ muffin hello run

And open http://fuf.me:5000 in your browser.

See more in the example application sources. The application is deployed on Heroku: https://muffin-py.herokuapp.com

Run example server locally:

$ make -C example run

And open http://fuf.me:5000 in your browser.

Configuration

Muffin gets configuration options from python files. By default the package tries to load a configuration from config module (config.py).

There are few ways to redifine configuration module:

• Set configuration module in your app initialization:

  app = muffin.Application('myapp', CONFIG='config.debug')

• Set environment variable MUFFIN_CONFIG:

  $ MUFFIN_CONFIG=settings_local muffin example run

Also you can define any options while initializing your application:

app = muffin.Application('myapp', DEBUG=True, ANY_OPTION='Here', ONE_MORE='Yes')

Base application options

Base Muffin options and default values:

# Configuration module
'CONFIG': 'config'

# Enable debug mode
'DEBUG': False

# Logging options
'LOG_LEVEL': 'WARNING'
'LOG_FORMAT': '%(asctime)s [%(process)d] [%(levelname)s] %(message)s'
'LOG_DATE_FORMAT': '[%Y-%m-%d %H:%M:%S %z]'

# List of enabled plugins
'PLUGINS': []

# Setup static files in development
'STATIC_PREFIX': '/static'
'STATIC_FOLDERS': ['static']

CLI integration

Run in your shell:

$ muffin path.to.your.module:app_object_name --help

Write a custom command

@app.manage.command
def hello(name, upper=False):
    """ Write command help text here.

    :param name:  Write your name
    :param upper: Use uppercase

    """
    greetings = 'Hello %s!' % name
    if upper:
        greetings = greetings.upper()
    print(greetings)

$ muffin example hello --help

    Write command help text here.

    positional arguments:
    name        Write your name

    optional arguments:
    -h, --help  show this help message and exit
    --upper     Enable use uppercase
    --no-upper  Disable use uppercase

$ muffin example hello mike --upper

    HELLO MIKE!

Testing

Setup tests

Set module path to your Muffin Application in pytest configuration file or use command line option --muffin-app.

Example:

$ py.test -xs --muffin-app example

Testing application

See examples:

import pytest

@pytest.mark.async
def test_async_code():
    from aiohttp import request
    response = yield from request('GET', 'http://google.com')
    text = yield from response.text()
    assert 'html' in text

def test_app(app):
    """ Get your app in your tests as fixture. """
    assert app.name == 'my app name'
    assert app.cfg.MYOPTION == 'develop'

def test_view(client):
    """ Make HTTP request to your application. """
    response = client.get('/my-handler')
    assert 'mydata' in response.text

Deployment

Use muffin command. By example:

$ muffin example run --workers=4

See muffin {APP} run --help for more info.

Bug tracker

If you have any suggestions, bug reports or annoyances please report them to the issue tracker at https://github.com/klen/muffin/issues

Contributing

Development of The Muffin happens at: https://github.com/klen/muffin

Contributors

• klen (Kirill Klenov)

License

Licensed under a MIT license (See LICENSE)