Kobin Documentation¶

Type Hints friendly WSGI Framework for Python3.

Kobin has following features.

Decorator based Routing System exploited Type Hints.
WSGI request and response Wrapper.
Provide type annotations from stub files.
and other convenient utilities...

And Kobin has NO following features:

WSGI Server Adapters: Please use WSGICLI or Gunicorn CLI.
Serving static contents: Please use WSGICLI and Nginx.
Template Engine: But Kobin provides template adapter.

Statuses¶

https://travis-ci.org/kobinpy/kobin.svg?branch=master

Kobin documentation contents¶

Tutorial¶

Installation¶

In this tutorial, we will use Python 3.6.

$ python --version
Python 3.6.0b4
$ pip install -U pip
$ pip install kobin wsgicli

Kobin: WSGI Framework
WSGICLI: Command line tools for developing your WSGI Application

Your first kobin app¶

Let’s make Kobin’s application. Please create a main.py:

from kobin import Kobin, Response, JSONResponse
app = Kobin()

@app.route('/')
def index() -> Response:
    return Response("Hello World!")

@app.route('/users/{user_id}')
def say_hello(user_id: int) -> JSONResponse:
    return JSONResponse({
        "message": f"Hello user{user_id}!"
    })

For those who have used the WSGI framework such as Bottle and Flask, it may be familiar with this code. One distinctive feature is the existence of type hints. Kobin casts the URL variable based on the type hinting and passes it to the View function.

Let’s actually move it. There are several ways to run WSGI’s application. In the development environment we recommend a command line tool called wsgicli.

$ wsgicli run main.py app
Start: 127.0.0.1:8000

When the server starts up successfully, let’s access following urls.

Did you see any message? Congratulations!

Deploy to production¶

In a production, let’s use gunicorn instead of using wsgicli for a performance reasons.

$ pip install gunicorn
$ gunicorn main:app

Then please try accessing your website. If you use the function of static file serving in wsgicli, maybe the layout and styles have gone wrong. Actually, gunicorn doesn’t have the function of serving static content such as CSS, JS, and image files. Generally, the reverse proxy server such as Nginx is used for serving static content in production (See Serving Static Content - Nginx .

If you absolutely need to serve static contents in Python’s application side (ex: Using Heroku), Please use kobinpy/wsgi-static-middleware .

Next Step¶

More practical example is kobin-example . If you want to know the best practices in Kobin, Please check it.

API Documentation¶

This documentations is generated from kobin’s source code.

Developer guide¶

Bug Reports and Feature Requests¶

If you have encountered a problem with Kobin or have an idea for a new feature, please submit it to the issue tracker on Github.

Including or providing a link to the source files involved may help us fix the issue. If possible, try to create a minimal project that produces the error and post that instead.

Documentation¶

Build¶

English: make html
Japanese: make -e SPHINXOPTS="-D language='ja'" html

Translation¶

Updating your po files by new pot files.

$ make gettext
$ sphinx-intl update -p build/locale
# edit doc/source/locale/*.po files
$ make -e SPHINXOPTS="-D language='ja'" html

Reference: Internationalization – Sphinx documentation

Testing¶

The following test are running in Kobin project. If you add the changes to Kobin, Please run tox testing.

test: python setup.py test
coverage: coverage run setup.py test && coverage report
mypy: mypy --check-untyped-defs --fast-parser --python-version 3.6 kobin
Flake8: flake8
doctest: cd docs; make doctest
Run all with tox: tox

Requirements¶

Supported python versions are python 3.6. And Kobin has no required dependencies other than the Python Standard Libraries.

The following packages are optional:

wsgicli - Command Line Interface for developing WSGI application.
jinja2 - Jinja2 is a full featured template engine for Python.

Table Of Contents