klen / http-router

A simple router for HTTP applications

HTTP Router

http-router -- A simple router for HTTP applications

The library is not a HTTP framework. It's an utilite to build the frameworks. The main goal of the library to bind targets to http routes and match them.

Requirements

• python 3.8, 3.9, 3.10, 3.11, 3.12, pypy3

Installation

http-router should be installed using pip: :

pip install http-router

Usage

Create a router:

from http_router import Router


# Initialize the router
router = Router(trim_last_slash=True)

Define routes:

@router.route('/simple')
def simple():
    return 'result from the fn'

Call the router with HTTP path and optionally method to get a match result.

match = router('/simple', method='GET')
assert match, 'HTTP path is ok'
assert match.target is simple

The router supports regex objects too:

import re

@router.route(re.compile(r'/regexp/\w{3}-\d{2}/?'))
def regex():
    return 'result from the fn'

But the lib has a simplier interface for the dynamic routes:

@router.route('/users/{username}')
def users():
    return 'result from the fn'

By default this will capture characters up to the end of the path or the next /.

Optionally, you can use a converter to specify the type of the argument like {variable_name:converter}.

Converter types:

str	(default) accepts any text without a slash
int	accepts positive integers
float	accepts positive floating point values
path	like string but also accepts slashes
uuid	accepts UUID strings

Convertors are used by prefixing them with a colon, like so:

@router.route('/orders/{order_id:int}')
def orders():
    return 'result from the fn'

Any unknown convertor will be parsed as a regex:

@router.route('/orders/{order_id:\d{3}}')
def orders():
    return 'result from the fn'

Multiple paths are supported as well:

@router.route('/', '/home')
def index():
    return 'index'

Handling HTTP methods:

@router.route('/only-post', methods=['POST'])
def only_post():
    return 'only-post'

Submounting routes:

subrouter = Router()

@subrouter.route('/items/{item}')
def items():
     pass

 router = Router()
 router.route('/api')(subrouter)


match = router('/api/items/12', method='GET')
assert match, 'HTTP path is ok'
assert match.target is items
 assert match.params == {"item": "12"}

Bug tracker

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

Contributing

Development of the project happens at: https://github.com/klen/http-router

License

Licensed under a MIT license.