Quick Start

This is how to serve a simple string using yhttp.

Install yhttp if you’ve not installed it yet. it’s highly recommended to use virtual environment before that. I use virtualenvwrapper.

Create a virtual environment to isolate your hello world application from the rest of the system python packages.

mkvirtualenv hello

workon hello
pip install yhttp

Create a file named: hello.py:

from yhttp import Application, text


app = Application()


@app.route()
@text
def get(req):
    return 'Hello World!'


app.ready()

Serve it by your favorite WSGI server, for example:

pip install gunicorn
gunicorn hello:app

Use your favorite http clinet to check it:

curl localhost:8000

Command Line Interface

yhttp has builtin command line interface with auto completion support. to use it, just call Application.climain() as the entry point. We will learn how it works in the rest of this tutorial.

Let’s edit hello.py to act as both command line interface and WSGI application:

import sys

...

if __name__ == '__main__':
    sys.exit(app.climain())


app.ready()

Now, you can run:

python3 hello.py --help

You can set the execution bit of the hello.py and add a shebang at the first line to use it as a standalone executable.

chmod +x hello.py

And insert it at the first line:

#! /usr/bin/env python3

Lets take a look at hello.py.

#! /usr/bin/env python3
import sys

from yhttp import Application, text


app = Application()


@app.route()
@text
def get(req):
    return 'Hello World!'


if __name__ == '__main__':
    sys.exit(app.climain())


app.ready()

Use it as an executable python script:

./hello.py --help

There is also a subcommand serve to serve the WSGI application by python’s builtin WSGI server.

./hello.py serve

Or

./hello.py s

Use --help anywhere to know command line options:

./hello.py serve --help

usage: hello.py serve [-h] [-b {HOST:}PORT] [-C DIRECTORY]

optional arguments:
  -h, --help            show this help message and exit
  -b {HOST:}PORT, --bind {HOST:}PORT
                        Bind Address. default: 8080
  -C DIRECTORY, --directory DIRECTORY
                        Change to this path before starting, default is: `.`

Python Package

Create a setup.py.

from setuptools import setup


setup(
    name='hello',
    version='0.1.0',
    install_requires=[
        'yhttp',
    ],
    py_modules=['hello'],
    entry_points={
        'console_scripts': [
            'hello = hello:app.climain'
        ]
    },
)

After this, you can install the module as a reqular python package.

workon hello
pip install -e .

So, use the hello command without specifying path and extension, thanks to setuptools entry_points feature.

hello --help

hello serve --bind 8088

Bash Autocompletion

Just run:

hello completion install

Then deactivate and re-activate your virtual environment to apply changes:

deactivate && workon hello

Write hello and hit the TAB key twice to see the avaiable options:

hello TAB TAB

Check out the other tutorials to discover the yhttp features.

Custom Command Line insterface

Let’s add a version easycli.SubCommand to show the application’s version:

hello.py

from easycli import SubCommand


__version__ = '0.1.0'


class Version(SubCommand):
    __command__ = 'version'
    __aliases__ = ['v', 'ver']

    def __call__(self, args):
        print(__version__)

...


app.cliarguments.append(Version)


if __name__ == '__main__':
    sys.exit(app.climain())


app.ready()

Now you can do:

hello version
hello ver
hello v

It’s ok to modify the setup.py script to read version from __version__ attribute.

here is the complete version of the setup.py and hello.py.

setup.py

import re
from os.path import join, dirname

from setuptools import setup


# reading package's version (same way sqlalchemy does)
with open(join(dirname(__file__), 'hello.py')) as f:
    version = re.match(r".*__version__ = '(.*?)'", f.read(), re.S).group(1)


setup(
    name='hello',
    version=version,
    install_requires=[
        'yhttp',
    ],
    py_modules=['hello'],
    entry_points={
        'console_scripts': [
            'hello = hello:app.climain'
        ]
    },
)

hello.py

import sys

from yhttp import Application
from easycli import SubCommand


__version__ = '0.1.1'


class Version(SubCommand):
    __command__ = 'version'
    __aliases__ = ['v', 'ver']

    def __call__(self, args):
        print(__version__)


app = Application()
app.cliarguments.append(Version)


@app.route()
def get(req):
    return b'Hello World!'


if __name__ == '__main__':
    sys.exit(app.climain())


app.ready()

Install the version 0.1.1 using:

pip install -e .

Then test it by:

hello version
hello ver
hello v
hello serve

Checkout the other Tutorials and or Cookbook to discover more features.