Metadata-Version: 2.1
Name: http-router
Version: 2.6.8
Summary: A simple router for HTTP applications
Home-page: https://github.com/klen/http-router
Author: Kirill Klenov
Author-email: horneds@gmail.com
License: MIT
Project-URL: Documentation, https://github.com/klen/http-router
Project-URL: Source code, https://github.com/klen/http-router
Project-URL: Issue tracker, https://github.com/klen/http-router/issues
Keywords: http,http router,paths management
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Cython
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.7
Provides-Extra: build
Provides-Extra: tests
License-File: LICENSE

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

.. _description:

**http-router** -- A simple router for HTTP applications

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


.. _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('/items')
   def items():
        pass

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


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


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


