README.md

ServerTemplate.py

Simple API server template and utilities for Python.

Quickstart

Requirements

• PyYAML

Using ServerTemplate.py

You need to setup ServerTemplate.py.

1. Create a repository from ServerTemplate.py.
2. Start server with:

   $ bin/start

3. Edit config.yml. -> Configuration

Configuration

• system.bind.port (REQUIRED) - Server listening port.
• system.request.header_readlimit - Bytes maximum read per line.
• system.request.default_protocol - Default protocol.
• system.request.header_limit - Limit of headers clients can be send.
• system.request.default_content_type - Default type if content type does not match.
• system.route_paths - Endpoint root directory.

Features

• Static routes with json or text files.

• Dynamic routes with directory tree and .py files.

  Example

    /
    ├── _.py <- this is index file.
    ├── api
    │   ├── user.py
    │   └── post.py
    ├── articles
    │   ├── a.py
    │   └── __.py
    ├── download
    │   └── ___.py
    ├── video
    │   └── __
    │       ├── watch.py
    │       └── info.py
    └── example.py
  

  In this example, you can make a route of /api/user.
  Also, you can make a route of /download/path/to/foo.bar and you can make a route of /articles/foobar.
  __ supports only one path component and can be used multiple times, but cannot contain /. You can also use __ for directories.
  ___.py cannot be used more than once, but it can contain /. The directory where ___.py is placed cannot contain any other files.

• RESTful api support

  Example

  # /user/__.py
  @http("GET", args=(Argument("user_id", "string", "path")))
  def handle(handler, params):
      pass
  
  @http("PUT|DELETE", args=(Argument("user_id", "string", "path"), 
                            Argument("user_name", "string", "query"),
                            Argument("data", "int", "body")))
  def handle(handler, params):
      pass
  
  @http(Method.PATCH & Method.HEAD, args=(Argument("user_id", "string", "path"))
  def handle(handler, params):
      pass

• Show stack trace in logs.

  Example

  [00:00:00 WARN] Unexpected exception while handling client request resource /example
        at server.handler.dynamic_handle(handler.py:133): handler.handle(self, path, params)
        at _context(py:194): if missing(handler, params, args):
        at missing(py:43): diff = search_missing(fields, require)
  Caused by: AttributeError: 'tuple' object has no attribute 'remove'
        at search_missing(py:66): require.remove(key)

• Argument validation with annotation.

  Example

      
  from endpoint import *
  impport route 
  @http("GET", args=(
      Argument("text", "str", "query", maximum=32),
      Argument("count", "int", "query", minimum=1, maximum=100)),
  require_auth=False)
  def handle(handler, path, params):
      q = params["text"] * params["count"]
      route.success(handler, 200, q)

• Multi-threaded routing.

• Document definition in code.

  Example

      from endpoint import *
      @http("GET", args=(
      Argument("text", "str", "path", maximum=32,
                     doc=Document(summary="Input text.")),
      Argument("count", "int", "path", minimum=1, maximum=100,
                     doc=Document(summary="Multiple count."))),
              require_auth=False,
              docs=Document("Repeats the string specified with text.",
                                  types="application/json",
                                  responses=[
                                      Response(200, "Successful response.", {
                                          "success": True,
                                          "result": "Hello, world!"
                                      })
                                  ]))

• Automatic generation of HTML documents for Swagger UI

  $ py -3 src/gendoc.py

• Customizable commands