Installing hug

The first step to get started is to install hug. hug has very minimal base system requirements - a local installation of Python3.3+, optionally inside a virtualenv. Additionally, pip is required, but this should be included with most Python3 installations by default. Once the base system is in good shape, run the following command to install the latest version of hug:

First hug API

To start off, we are going to make a simple API with local access only, but which demonstrates a couple of basic hug features: annotation-based validation and directives. Our first API will simply return a happy birthday message to the user, along with the time it took to generate the message:

In this example: hug's built-in type annotation automatically validates and converts incoming inputs while hug's directives automatically replace the hug_timer argument with a HugTimer object that keeps track of how long the function has been running. hug type annotations are, at their core, simply functions or objects which take a value as input, cast that value as something (raising on errors), and then return it. As a result of this, most built-in Python cast functions (int, str, etc.) are valid annotations in hug out of the box. You can also use Marshmallow schemas and types as hug type annotations without modification.

Exposing our API as an HTTP micro-service

To expose our API over HTTP, all we need to do is apply a hug HTTP route decorator to the function, in addition to the local decorator. hug includes convience decorators for all common HTTP methods (GET, POST, PUT, etc). In this case we will apply a get decorator to specify that the function should return on an HTTP GET request. We will also supply an example set of parameters to lead our users in the correct direction:

Enabling command line interaction

What if we want to allow users to interact with our API from the command line, as well? No problem! All that's necessary is adding a hug.cli route decorator to our API function:

Final step: Production HTTP use

Finally, it's important to note that it's generally never a good idea to use a development server (like hug's, Flask's, etc.) directly in production. Instead, a WSGI-compatible server (such as uwsgi or Gunicorn) is recommended. Every hug API that contains an http endpoint automatically exposes a `__hug_wsgi__` WSGI-compatible API - making integration of our above example a breeze: