http-router 6.0.0
A simple router system for HTTP applications
License: MIT License
Requires Python: >=3.9
Keywords: http, router, web, framework

HTTP Router
###########

.. _description:

**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.

.. _badges:

.. image:: https://github.com/klen/http-router/workflows/tests/badge.svg
    :target: https://github.com/klen/http-router/actions
    :alt: Tests Status

.. image:: https://img.shields.io/pypi/v/http-router
    :target: https://pypi.org/project/http-router/
    :alt: PYPI Version

.. image:: https://img.shields.io/pypi/pyversions/http-router
    :target: https://pypi.org/project/http-router/
    :alt: Python Versions

.. _contents:

.. contents::


.. _requirements:

Requirements
=============

- python 3.10, 3.11, 3.12, 3.13, 3.14, pypy3


.. _installation:

Installation
=============

**http-router** should be installed using pip: ::

    pip install http-router


Usage
=====

Create a router:

.. code:: python

    from http_router import Router


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


Define routes:

.. code:: python

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

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

.. code:: python

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

The router supports regex objects too:

.. code:: python

    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:

.. code:: python

    @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:

.. code:: python

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

Any unknown convertor will be parsed as a regex:

.. code:: python

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


Multiple paths are supported as well:

.. code:: python

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


Handling HTTP methods:

.. code:: python

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


Submounting routes:

.. code:: python

   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"}


.. _bugtracker:

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:

Contributing
============

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


.. _license:

License
========

Licensed under a `MIT license`_.


.. _links:

.. _klen: https://github.com/klen
.. _MIT license: http://opensource.org/licenses/MIT