The no-nonsense, minimalist REST and app backend framework for Python developers, with a focus on reliability, correctness, and performance at scale.

Overview
Falcon web framework logo

Build Status Falcon web framework docs codecov.io

The Falcon Web Framework

Falcon is a reliable, high-performance Python web framework for building large-scale app backends and microservices. It encourages the REST architectural style, and tries to do as little as possible while remaining highly effective.

Falcon apps work with any WSGI or ASGI server, and run like a champ under CPython 3.5+ and PyPy 3.5+ (3.6+ required for ASGI).

A Big Thank You to Our Patrons

Platinum

CERT Gouvernemental Luxembourg

Gold

LIKALO    Examination RU

Luhnar Site Accelerator

Silver

Paris Kejser

Has Falcon helped you make an awesome app? Show your support today with a one-time donation or by becoming a patron. Supporters get cool gear, an opportunity to promote their brand to Python developers, and prioritized support.

Learn how to support Falcon development

Thanks!

Quick Links

What People are Saying

"We have been using Falcon as a replacement for [framework] and we simply love the performance (three times faster) and code base size (easily half of our original [framework] code)."

"Falcon looks great so far. I hacked together a quick test for a tiny server of mine and was ~40% faster with only 20 minutes of work."

"Falcon is rock solid and it's fast."

"I'm loving #falconframework! Super clean and simple, I finally have the speed and flexibility I need!"

"I feel like I'm just talking HTTP at last, with nothing in the middle. Falcon seems like the requests of backend."

"The source code for Falcon is so good, I almost prefer it to documentation. It basically can't be wrong."

"What other framework has integrated support for 786 TRY IT NOW ?"

Features

  • ASGI and WSGI Support
  • WebSocket Support
  • Native asyncio support (no hacks or compatibility layers)
  • Strict adherence to RFCs
  • Highly-optimized, extensible code base
  • Intuitive routing via URI templates and REST-inspired resource classes
  • No reliance on magic globals for routing and state management
  • Easy access to headers and bodies through request and response classes
  • DRY request processing via middleware components and hooks
  • Idiomatic HTTP error responses
  • Straightforward exception handling
  • Snappy testing through WSGI/ASGI helpers and mocks
  • CPython 3.5+ and PyPy 3.5+ support
  • ~20% speed boost under CPython when Cython is available

How is Falcon Different?

Perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away.

- Antoine de Saint-Exupéry

We designed Falcon to support the demanding needs of large-scale microservices and responsive app backends. Falcon complements more general Python web frameworks by providing bare-metal performance, reliability, and flexibility wherever you need it.

Fast. Same hardware, more requests. Falcon turns around requests several times faster than most other Python frameworks. For an extra speed boost, Falcon compiles itself with Cython when available, and also works well with PyPy. Considering a move to another programming language? Benchmark with Falcon + PyPy first.

Reliable. We go to great lengths to avoid introducing breaking changes, and when we do they are fully documented and only introduced (in the spirit of SemVer) with a major version increment. The code is rigorously tested with numerous inputs and we require 100% coverage at all times. Falcon does not depend on any external Python packages.

Debuggable. Falcon eschews magic. It's easy to tell which inputs lead to which outputs. To avoid incentivizing the use of hard-to-debug global state, Falcon does not use decorators to define routes. Unhandled exceptions are never encapsulated or masked. Potentially surprising behaviors, such as automatic request body parsing, are well-documented and disabled by default. Finally, we take care to keep logic paths within the framework simple, shallow and understandable. All of this makes it easier to reason about the code and to debug edge cases in large-scale deployments.

Flexible. Falcon leaves a lot of decisions and implementation details to you, the API developer. This gives you a lot of freedom to customize and tune your implementation. Due to Falcon's minimalist design, Python community members are free to independently innovate on Falcon add-ons and complementary packages.

Who's Using Falcon?

Falcon is used around the world by a growing number of organizations, including:

  • 7ideas
  • Cronitor
  • EMC
  • Hurricane Electric
  • Leadpages
  • OpenStack
  • Rackspace
  • Shiftgig
  • tempfil.es
  • Opera Software

If you are using the Falcon framework for a community or commercial project, please consider adding your information to our wiki under Who's Using Falcon?

Community

A number of Falcon add-ons, templates, and complementary packages are available for use in your projects. We've listed several of these on the Falcon wiki as a starting point, but you may also wish to search PyPI for additional resources.

The Falconry community on Gitter is a great place to ask questions and share your ideas. You can find us in falconry/user. We also have a falconry/dev room for discussing the design and development of the framework itself.

Per our Code of Conduct, we expect everyone who participates in community discussions to act professionally, and lead by example in encouraging constructive discussions. Each individual in the community is responsible for creating a positive, constructive, and productive culture.

Installation

PyPy

PyPy is the fastest way to run your Falcon app. PyPy3.5+ is supported as of PyPy v5.10.

$ pip install falcon

Or, to install the latest beta or release candidate, if any:

$ pip install --pre falcon

CPython

Falcon also fully supports CPython 3.5+.

The latest stable version of Falcon can be installed directly from PyPI:

$ pip install falcon

Or, to install the latest beta or release candidate, if any:

$ pip install --pre falcon

In order to provide an extra speed boost, Falcon can compile itself with Cython. Wheels containing pre-compiled binaries are available from PyPI for several common platforms. However, if a wheel for your platform of choice is not available, you can choose to stick with the source distribution, or use the instructions below to cythonize Falcon for your environment.

The following commands tell pip to install Cython, and then to invoke Falcon's setup.py, which will in turn detect the presence of Cython and then compile (AKA cythonize) the Falcon framework with the system's default C compiler.

$ pip install cython
$ pip install --no-build-isolation --no-binary :all: falcon

Note that --no-build-isolation is necessary to override pip's default PEP 517 behavior that can cause Cython not to be found in the build environment.

If you want to verify that Cython is being invoked, simply pass -v to pip in order to echo the compilation commands:

$ pip install -v --no-build-isolation --no-binary :all: falcon

Installing on OS X

Xcode Command Line Tools are required to compile Cython. Install them with this command:

$ xcode-select --install

The Clang compiler treats unrecognized command-line options as errors, for example:

clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]

You might also see warnings about unused functions. You can work around these issues by setting additional Clang C compiler flags as follows:

$ export CFLAGS="-Qunused-arguments -Wno-unused-function"

Dependencies

Falcon does not require the installation of any other packages, although if Cython has been installed into the environment, it will be used to optimize the framework as explained above.

WSGI Server

Falcon speaks WSGI (or ASGI; see also below). In order to serve a Falcon app, you will need a WSGI server. Gunicorn and uWSGI are some of the more popular ones out there, but anything that can load a WSGI app will do.

$ pip install [gunicorn|uwsgi]

ASGI Server

In order to serve a Falcon ASGI app, you will need an ASGI server. Uvicorn is a popular choice:

$ pip install uvicorn

Source Code

Falcon lives on GitHub, making the code easy to browse, download, fork, etc. Pull requests are always welcome! Also, please remember to star the project if it makes you happy. :)

Once you have cloned the repo or downloaded a tarball from GitHub, you can install Falcon like this:

$ cd falcon
$ pip install .

Or, if you want to edit the code, first fork the main repo, clone the fork to your desktop, and then run the following to install it using symbolic linking, so that when you change your code, the changes will be automagically available to your app without having to reinstall the package:

$ cd falcon
$ pip install --no-use-pep517 -e .

You can manually test changes to the Falcon framework by switching to the directory of the cloned repo and then running pytest:

$ cd falcon
$ pip install -r requirements/tests
$ pytest tests

Or, to run the default set of tests:

$ pip install tox && tox

See also the tox.ini file for a full list of available environments.

Read the Docs

The docstrings in the Falcon code base are quite extensive, and we recommend keeping a REPL running while learning the framework so that you can query the various modules and classes as you have questions.

Online docs are available at: https://falcon.readthedocs.io

You can build the same docs locally as follows:

$ pip install tox && tox -e docs

Once the docs have been built, you can view them by opening the following index page in your browser. On OS X it's as simple as:

$ open docs/_build/html/index.html

Or on Linux:

$ xdg-open docs/_build/html/index.html

Getting Started

Here is a simple, contrived example showing how to create a Falcon-based WSGI app (the ASGI version is included further down):

# examples/things.py

# Let's get this party started!
from wsgiref.simple_server import make_server

import falcon


# Falcon follows the REST architectural style, meaning (among
# other things) that you think in terms of resources and state
# transitions, which map to HTTP verbs.
class ThingsResource:
    def on_get(self, req, resp):
        """Handles GET requests"""
        resp.status = falcon.HTTP_200  # This is the default status
        resp.content_type = falcon.MEDIA_TEXT  # Default is JSON, so override
        resp.text = ('\nTwo things awe me most, the starry sky '
                     'above me and the moral law within me.\n'
                     '\n'
                     '    ~ Immanuel Kant\n\n')


# falcon.App instances are callable WSGI apps...
# in larger applications the app is created in a separate file
app = falcon.App()

# Resources are represented by long-lived class instances
things = ThingsResource()

# things will handle all requests to the '/things' URL path
app.add_route('/things', things)

if __name__ == '__main__':
    with make_server('', 8000, app) as httpd:
        print('Serving on port 8000...')

        # Serve until process is killed
        httpd.serve_forever()

You can run the above example directly using the included wsgiref server:

$ pip install falcon
$ python things.py

Then, in another terminal:

$ curl localhost:8000/things

The ASGI version of the example is similar:

# examples/things_asgi.py

import falcon
import falcon.asgi


# Falcon follows the REST architectural style, meaning (among
# other things) that you think in terms of resources and state
# transitions, which map to HTTP verbs.
class ThingsResource:
    async def on_get(self, req, resp):
        """Handles GET requests"""
        resp.status = falcon.HTTP_200  # This is the default status
        resp.content_type = falcon.MEDIA_TEXT  # Default is JSON, so override
        resp.text = ('\nTwo things awe me most, the starry sky '
                     'above me and the moral law within me.\n'
                     '\n'
                     '    ~ Immanuel Kant\n\n')


# falcon.asgi.App instances are callable ASGI apps...
# in larger applications the app is created in a separate file
app = falcon.asgi.App()

# Resources are represented by long-lived class instances
things = ThingsResource()

# things will handle all requests to the '/things' URL path
app.add_route('/things', things)

You can run the ASGI version with uvicorn or any other ASGI server:

$ pip install falcon uvicorn
$ uvicorn things_asgi:app

A More Complex Example (WSGI)

Here is a more involved example that demonstrates reading headers and query parameters, handling errors, and working with request and response bodies. Note that this example assumes that the requests package has been installed.

(For the equivalent ASGI app, see: A More Complex Example (ASGI)).

# examples/things_advanced.py

import json
import logging
import uuid
from wsgiref import simple_server

import falcon
import requests


class StorageEngine:

    def get_things(self, marker, limit):
        return [{'id': str(uuid.uuid4()), 'color': 'green'}]

    def add_thing(self, thing):
        thing['id'] = str(uuid.uuid4())
        return thing


class StorageError(Exception):

    @staticmethod
    def handle(ex, req, resp, params):
        # TODO: Log the error, clean up, etc. before raising
        raise falcon.HTTPInternalServerError()


class SinkAdapter:

    engines = {
        'ddg': 'https://duckduckgo.com',
        'y': 'https://search.yahoo.com/search',
    }

    def __call__(self, req, resp, engine):
        url = self.engines[engine]
        params = {'q': req.get_param('q', True)}
        result = requests.get(url, params=params)

        resp.status = str(result.status_code) + ' ' + result.reason
        resp.content_type = result.headers['content-type']
        resp.text = result.text


class AuthMiddleware:

    def process_request(self, req, resp):
        token = req.get_header('Authorization')
        account_id = req.get_header('Account-ID')

        challenges = ['Token type="Fernet"']

        if token is None:
            description = ('Please provide an auth token '
                           'as part of the request.')

            raise falcon.HTTPUnauthorized(title='Auth token required',
                                          description=description,
                                          challenges=challenges,
                                          href='http://docs.example.com/auth')

        if not self._token_is_valid(token, account_id):
            description = ('The provided auth token is not valid. '
                           'Please request a new token and try again.')

            raise falcon.HTTPUnauthorized(title='Authentication required',
                                          description=description,
                                          challenges=challenges,
                                          href='http://docs.example.com/auth')

    def _token_is_valid(self, token, account_id):
        return True  # Suuuuuure it's valid...


class RequireJSON:

    def process_request(self, req, resp):
        if not req.client_accepts_json:
            raise falcon.HTTPNotAcceptable(
                description='This API only supports responses encoded as JSON.',
                href='http://docs.examples.com/api/json')

        if req.method in ('POST', 'PUT'):
            if 'application/json' not in req.content_type:
                raise falcon.HTTPUnsupportedMediaType(
                    title='This API only supports requests encoded as JSON.',
                    href='http://docs.examples.com/api/json')


class JSONTranslator:
    # NOTE: Normally you would simply use req.media and resp.media for
    # this particular use case; this example serves only to illustrate
    # what is possible.

    def process_request(self, req, resp):
        # req.stream corresponds to the WSGI wsgi.input environ variable,
        # and allows you to read bytes from the request body.
        #
        # See also: PEP 3333
        if req.content_length in (None, 0):
            # Nothing to do
            return

        body = req.stream.read()
        if not body:
            raise falcon.HTTPBadRequest(title='Empty request body',
                                        description='A valid JSON document is required.')

        try:
            req.context.doc = json.loads(body.decode('utf-8'))

        except (ValueError, UnicodeDecodeError):
            description = ('Could not decode the request body. The '
                           'JSON was incorrect or not encoded as '
                           'UTF-8.')

            raise falcon.HTTPBadRequest(title='Malformed JSON',
                                        description=description)

    def process_response(self, req, resp, resource, req_succeeded):
        if not hasattr(resp.context, 'result'):
            return

        resp.text = json.dumps(resp.context.result)


def max_body(limit):

    def hook(req, resp, resource, params):
        length = req.content_length
        if length is not None and length > limit:
            msg = ('The size of the request is too large. The body must not '
                   'exceed ' + str(limit) + ' bytes in length.')

            raise falcon.HTTPPayloadTooLarge(
                title='Request body is too large', description=msg)

    return hook


class ThingsResource:

    def __init__(self, db):
        self.db = db
        self.logger = logging.getLogger('thingsapp.' + __name__)

    def on_get(self, req, resp, user_id):
        marker = req.get_param('marker') or ''
        limit = req.get_param_as_int('limit') or 50

        try:
            result = self.db.get_things(marker, limit)
        except Exception as ex:
            self.logger.error(ex)

            description = ('Aliens have attacked our base! We will '
                           'be back as soon as we fight them off. '
                           'We appreciate your patience.')

            raise falcon.HTTPServiceUnavailable(
                title='Service Outage',
                description=description,
                retry_after=30)

        # NOTE: Normally you would use resp.media for this sort of thing;
        # this example serves only to demonstrate how the context can be
        # used to pass arbitrary values between middleware components,
        # hooks, and resources.
        resp.context.result = result

        resp.set_header('Powered-By', 'Falcon')
        resp.status = falcon.HTTP_200

    @falcon.before(max_body(64 * 1024))
    def on_post(self, req, resp, user_id):
        try:
            doc = req.context.doc
        except AttributeError:
            raise falcon.HTTPBadRequest(
                title='Missing thing',
                description='A thing must be submitted in the request body.')

        proper_thing = self.db.add_thing(doc)

        resp.status = falcon.HTTP_201
        resp.location = '/%s/things/%s' % (user_id, proper_thing['id'])

# Configure your WSGI server to load "things.app" (app is a WSGI callable)
app = falcon.App(middleware=[
    AuthMiddleware(),
    RequireJSON(),
    JSONTranslator(),
])

db = StorageEngine()
things = ThingsResource(db)
app.add_route('/{user_id}/things', things)

# If a responder ever raises an instance of StorageError, pass control to
# the given handler.
app.add_error_handler(StorageError, StorageError.handle)

# Proxy some things to another service; this example shows how you might
# send parts of an API off to a legacy system that hasn't been upgraded
# yet, or perhaps is a single cluster that all data centers have to share.
sink = SinkAdapter()
app.add_sink(sink, r'/search/(?P<engine>ddg|y)\Z')

# Useful for debugging problems in your API; works with pdb.set_trace(). You
# can also use Gunicorn to host your app. Gunicorn can be configured to
# auto-restart workers when it detects a code change, and it also works
# with pdb.
if __name__ == '__main__':
    httpd = simple_server.make_server('127.0.0.1', 8000, app)
    httpd.serve_forever()

Again this code uses wsgiref, but you can also run the above example using any WSGI server, such as uWSGI or Gunicorn. For example:

$ pip install requests gunicorn
$ gunicorn things:app

On Windows you can run Gunicorn and uWSGI via WSL, or you might try Waitress:

$ pip install requests waitress
$ waitress-serve --port=8000 things:app

To test this example, open another terminal and run:

$ http localhost:8000/1/things authorization:custom-token

You can also view the the application configuration from the CLI via the falcon-inspect-app script that is bundled with the framework:

falcon-inspect-app things_advanced:app

A More Complex Example (ASGI)

Here's the ASGI version of the app from above. Note that it uses the httpx package in lieu of requests.

# examples/things_advanced_asgi.py

import json
import logging
import uuid

import falcon
import falcon.asgi
import httpx


class StorageEngine:

    async def get_things(self, marker, limit):
        return [{'id': str(uuid.uuid4()), 'color': 'green'}]

    async def add_thing(self, thing):
        thing['id'] = str(uuid.uuid4())
        return thing


class StorageError(Exception):

    @staticmethod
    async def handle(ex, req, resp, params):
        # TODO: Log the error, clean up, etc. before raising
        raise falcon.HTTPInternalServerError()


class SinkAdapter:

    engines = {
        'ddg': 'https://duckduckgo.com',
        'y': 'https://search.yahoo.com/search',
    }

    async def __call__(self, req, resp, engine):
        url = self.engines[engine]
        params = {'q': req.get_param('q', True)}

        async with httpx.AsyncClient() as client:
            result = await client.get(url, params=params)

        resp.status = result.status_code
        resp.content_type = result.headers['content-type']
        resp.text = result.text


class AuthMiddleware:

    async def process_request(self, req, resp):
        token = req.get_header('Authorization')
        account_id = req.get_header('Account-ID')

        challenges = ['Token type="Fernet"']

        if token is None:
            description = ('Please provide an auth token '
                           'as part of the request.')

            raise falcon.HTTPUnauthorized(title='Auth token required',
                                          description=description,
                                          challenges=challenges,
                                          href='http://docs.example.com/auth')

        if not self._token_is_valid(token, account_id):
            description = ('The provided auth token is not valid. '
                           'Please request a new token and try again.')

            raise falcon.HTTPUnauthorized(title='Authentication required',
                                          description=description,
                                          challenges=challenges,
                                          href='http://docs.example.com/auth')

    def _token_is_valid(self, token, account_id):
        return True  # Suuuuuure it's valid...


class RequireJSON:

    async def process_request(self, req, resp):
        if not req.client_accepts_json:
            raise falcon.HTTPNotAcceptable(
                description='This API only supports responses encoded as JSON.',
                href='http://docs.examples.com/api/json')

        if req.method in ('POST', 'PUT'):
            if 'application/json' not in req.content_type:
                raise falcon.HTTPUnsupportedMediaType(
                    description='This API only supports requests encoded as JSON.',
                    href='http://docs.examples.com/api/json')


class JSONTranslator:
    # NOTE: Normally you would simply use req.get_media() and resp.media for
    # this particular use case; this example serves only to illustrate
    # what is possible.

    async def process_request(self, req, resp):
        # NOTE: Test explicitly for 0, since this property could be None in
        # the case that the Content-Length header is missing (in which case we
        # can't know if there is a body without actually attempting to read
        # it from the request stream.)
        if req.content_length == 0:
            # Nothing to do
            return

        body = await req.stream.read()
        if not body:
            raise falcon.HTTPBadRequest(title='Empty request body',
                                        description='A valid JSON document is required.')

        try:
            req.context.doc = json.loads(body.decode('utf-8'))

        except (ValueError, UnicodeDecodeError):
            description = ('Could not decode the request body. The '
                           'JSON was incorrect or not encoded as '
                           'UTF-8.')

            raise falcon.HTTPBadRequest(title='Malformed JSON',
                                        description=description)

    async def process_response(self, req, resp, resource, req_succeeded):
        if not hasattr(resp.context, 'result'):
            return

        resp.text = json.dumps(resp.context.result)


def max_body(limit):

    async def hook(req, resp, resource, params):
        length = req.content_length
        if length is not None and length > limit:
            msg = ('The size of the request is too large. The body must not '
                   'exceed ' + str(limit) + ' bytes in length.')

            raise falcon.HTTPPayloadTooLarge(
                title='Request body is too large', description=msg)

    return hook


class ThingsResource:

    def __init__(self, db):
        self.db = db
        self.logger = logging.getLogger('thingsapp.' + __name__)

    async def on_get(self, req, resp, user_id):
        marker = req.get_param('marker') or ''
        limit = req.get_param_as_int('limit') or 50

        try:
            result = await self.db.get_things(marker, limit)
        except Exception as ex:
            self.logger.error(ex)

            description = ('Aliens have attacked our base! We will '
                           'be back as soon as we fight them off. '
                           'We appreciate your patience.')

            raise falcon.HTTPServiceUnavailable(
                title='Service Outage',
                description=description,
                retry_after=30)

        # NOTE: Normally you would use resp.media for this sort of thing;
        # this example serves only to demonstrate how the context can be
        # used to pass arbitrary values between middleware components,
        # hooks, and resources.
        resp.context.result = result

        resp.set_header('Powered-By', 'Falcon')
        resp.status = falcon.HTTP_200

    @falcon.before(max_body(64 * 1024))
    async def on_post(self, req, resp, user_id):
        try:
            doc = req.context.doc
        except AttributeError:
            raise falcon.HTTPBadRequest(
                title='Missing thing',
                description='A thing must be submitted in the request body.')

        proper_thing = await self.db.add_thing(doc)

        resp.status = falcon.HTTP_201
        resp.location = '/%s/things/%s' % (user_id, proper_thing['id'])


# The app instance is an ASGI callable
app = falcon.asgi.App(middleware=[
    # AuthMiddleware(),
    RequireJSON(),
    JSONTranslator(),
])

db = StorageEngine()
things = ThingsResource(db)
app.add_route('/{user_id}/things', things)

# If a responder ever raises an instance of StorageError, pass control to
# the given handler.
app.add_error_handler(StorageError, StorageError.handle)

# Proxy some things to another service; this example shows how you might
# send parts of an API off to a legacy system that hasn't been upgraded
# yet, or perhaps is a single cluster that all data centers have to share.
sink = SinkAdapter()
app.add_sink(sink, r'/search/(?P<engine>ddg|y)\Z')

You can run the ASGI version with any ASGI server, such as uvicorn:

$ pip install falcon httpx uvicorn
$ uvicorn things_advanced_asgi:app

Contributing

Thanks for your interest in the project! We welcome pull requests from developers of all skill levels. To get started, simply fork the master branch on GitHub to your personal account and then clone the fork into your development environment.

If you would like to contribute but don't already have something in mind, we invite you to take a look at the issues listed under our next milestone. If you see one you'd like to work on, please leave a quick comment so that we don't end up with duplicated effort. Thanks in advance!

Please note that all contributors and maintainers of this project are subject to our Code of Conduct.

Before submitting a pull request, please ensure you have added/updated the appropriate tests (and that all existing tests still pass with your changes), and that your coding style follows PEP 8 and doesn't cause pyflakes to complain.

Commit messages should be formatted using AngularJS conventions.

Comments follow Google's style guide, with the additional requirement of prefixing inline comments using your GitHub nick and an appropriate prefix:

  • TODO(riker): Damage report!
  • NOTE(riker): Well, that's certainly good to know.
  • PERF(riker): Travel time to the nearest starbase?
  • APPSEC(riker): In all trust, there is the possibility for betrayal.

The core Falcon project maintainers are:

  • Kurt Griffiths, Project Lead (kgriffs on GH, Gitter, and Twitter)
  • John Vrbanac (jmvrbanac on GH, Gitter, and Twitter)
  • Vytautas Liuolia (vytas7 on GH and Gitter, and vliuolia on Twitter)
  • Nick Zaccardi (nZac on GH and Gitter)

Please don't hesitate to reach out if you have any questions, or just need a little help getting started. You can find us in falconry/dev on Gitter.

See also: CONTRIBUTING.md

Legal

Copyright 2013-2020 by Individual and corporate contributors as noted in the individual source files.

Falcon image courtesy of John O'Neill.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use any portion of the Falcon framework except in compliance with the License. Contributors agree to license their work under the same License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Comments
  • Support form param parsing

    Support form param parsing

    Maybe do this as a /contrib hook? Alternatively, role into get_param?

    application/x-www-form-urlencoded
    multipart/form-data

    See also: http://www.w3.org/TR/html401/interact/forms.html#submit-format

    opened by kgriffs 30
  • bug: sse-stream not properly consumed

    bug: sse-stream not properly consumed

    I recently implemented an async route, where I "awaited" some result, but had to send a "keep-alive"-message in case the result takes longer than a certain time (1m in my case).

    The exact same code works when setting the generator as value for response.stream, but will get stuck if instead setting it as response.sse (will work for small data, though).

    This is my code:

    # works:
    async def wait_for_result_and_yield_keepalives():
        nonlocal awaitable
        while True:
            done, pending = await asyncio.wait((awaitable,), timeout=30)
            if not done:
                logger.info('sending keep-alive')
                awaitable = pending.pop()
                yield b' '
                continue
            break
        result = done.pop().result()
        logger.info(f'scan done {result=}')
        yield json.dumps(result).encode('utf-8')
    
    resp.stream = wait_for_result_and_yield_keepalives()
    
    # does not work (will get stuck):
    async def wait_for_result_and_yield_keepalives():
        nonlocal awaitable
        while True:
            done, pending = await asyncio.wait((awaitable,), timeout=30)
            if not done:
                logger.info('sending keep-alive')
                awaitable = pending.pop()
                yield falcon.asgi.SSEvent(event='keep-alive')
                continue
            break
        result = done.pop().result()
        logger.info(f'scan done {result=}')
        yield falcon.asgi.SSEvent(event='result', json=result)
    
    resp.sse = wait_for_result_and_yield_keepalives()
    

    To be fair, I am so far not very familiar w/ "async", so maybe my code is conceptionally flawed (feedback welcome..). However, I still would expect that behaviour between using response.stream and response.sse ought to be consistent.

    Maybe there are more elegant ways of sending those "keep-alives"? I have to send those, because in my (kubernetes) environment, stale HTTP connections are closed (I think by Load-Balancer) after about 1m of inactivity (just in case you wonder why I want to do such a thing in the first place).

    needs-information question 
    opened by ccwienk 26
  • feat(routing): add support for multiple path segment fields

    feat(routing): add support for multiple path segment fields

    Summary of Changes

    This adds support for a converter to be declared as consuming all the remaining path.

    The current implementation does not allow nesting these converters and is quite conservative (I think), but I believe we can improve on this later if we need to.

    Related Issues

    Closes #423 Fixes #648 Relates to #1895

    Pull Request Checklist

    This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!

    If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

    • [x] Applied changes to both WSGI and ASGI code paths and interfaces (where applicable).
    • [x] Added tests for changed code.
    • [x] Prefixed code comments with GitHub nick and an appropriate prefix.
    • [x] Coding style is consistent with the rest of the framework.
    • [x] Updated documentation for changed code.
      • [ ] Added docstrings for any new classes, functions, or modules.
      • [ ] Updated docstrings for any modifications to existing code.
      • [ ] Updated both WSGI and ASGI docs (where applicable).
      • [ ] Added references to new classes, functions, or modules to the relevant RST file under docs/.
      • [ ] Updated all relevant supporting documentation files under docs/.
      • [ ] A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
      • [ ] Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
    • [ ] Changes (and possible deprecations) have towncrier news fragments under docs/_newsfragments/, with the file name format {issue_number}.{fragment_type}.rst. (Run towncrier --draft to ensure it renders correctly.)

    If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

    PR template inspired by the attrs project.

    opened by CaselIT 26
  • Allow docs to be larger on large screens

    Allow docs to be larger on large screens

    Summary of Changes

    Allow the max width of the docs to be larger for uses with a large screen. The current max body is set to 1000px.

    On a large screen (2560px). The version image currend read the docs image

    There is still a lot of white, but that's definitely nicer to me that the better than the current version. Personally I don't think we gain much by going wider, but it's easy to set 1200-1400px as max body width.

    For reference current max is 660px

    opened by CaselIT 26
  • fix(media): let media handlers deserialize empty media

    fix(media): let media handlers deserialize empty media

    Summary of Changes

    Let media handlers deserialize an empty media.

    NOTE: as is this change creates a possible large breaking change for WSGI application since it changes empty json requests from None to an 400 error. As implemented is probably the cleanest version, but I think we may scale it back a bit by:

    • if the media handler returns an error, the stream was empty and the user has not supplied a fallback value, warn the user that next version will propagate the exception
    • return None

    Thought?

    Related Issues

    Fixes #1589 Fixes #1216

    Pull Request Checklist

    This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!

    If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

    • [x] Applied changes to both WSGI and ASGI code paths and interfaces (where applicable).
    • [x] Added tests for changed code.
    • [x] Prefixed code comments with GitHub nick and an appropriate prefix.
    • [x] Coding style is consistent with the rest of the framework.
    • [x] Updated documentation for changed code.
      • [x] Added docstrings for any new classes, functions, or modules.
      • [x] Updated docstrings for any modifications to existing code.
      • [x] Updated both WSGI and ASGI docs (where applicable).
      • [x] Added references to new classes, functions, or modules to the relevant RST file under docs/.
      • [x] Updated all relevant supporting documentation files under docs/.
      • [x] A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
      • [x] Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
    • [x] Changes (and possible deprecations) have towncrier news fragments under docs/_newsfragments/, with the file name format {issue_number}.{fragment_type}.rst. (Run towncrier --draft to ensure it renders correctly.)

    If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

    PR template inspired by the attrs project.

    opened by CaselIT 26
  • Custom error handler that won't raise the exception in the CLI

    Custom error handler that won't raise the exception in the CLI

    Hi,

    I'm looking into custom error handling for my API and I cannot seem to get custom error handling as I'd wish, unlike on flask.

    On Flask, I can do custom error handlers that would look like this https://github.com/Seluj78/PyMatcha/blob/dev/backend/PyMatcha/utils/errors/badrequest.py and will simply return a custom message and code.

    Whereas on Falcon, whenever there's a for example 404 raised, it is also raised in the CLI.

    Is there anyway to have a better custom exception experience ?

    question 
    opened by Seluj78 24
  • fix(request): Decouple form and URL param parsing

    fix(request): Decouple form and URL param parsing

    Separate form and URL parameter parsing into request.param and request.form_param. Introduces new APIs for accessing the data.

    Also, do not consume the POST stream unless the data is requested, and make the raw POST data available on the request.

    Closes #418

    opened by necaris 24
  • feat(API): Add middlewares to falcon API

    feat(API): Add middlewares to falcon API

    Currently falcon provides hooks as a way to add logic to all "routed" requests. With this approach it's not possible to execute code when a request is not routed (e.g., method not allowed, path not found ...) I would like to include the concept of middlewares (same as django) in falcon as it may be useful for many projects. Typical middlewares:

    • Generate unique transaction for all requests
    • Log all requests and include time ellapsed
    • Authentication (imo this should happend before any logic of routing, aka find responder).

    A list of Middleware classes can be added to falcon WSGI in this way:

    api.add_middlewares([MiddClass1,MidClass2])

    A middleware will be executed always with every request/response dispatched, no matters routing and errors. A middleware can define process_request or process_response or both; internally the code will be executed when corresponds. Arguments are the same as hooks and error_handlers. In unit tests, some examples can be seen.

    opened by ealogar 24
  • Low performance in req._parse_form_urlencoded()

    Low performance in req._parse_form_urlencoded()

    It's really slow when invoking req._parse_form_urlencoded() if the form body is huge. And after digging deeper, I found it was caused by the function named decode(encoded_uri, unquote_plus=True) defined in falcon/util/uri.py. The root cause is the low performance of list concatenation. A little refactor can improve performance greatly. The code before:

    def decode(encoded_uri, unquote_plus=True):
        """Decodes percent-encoded characters in a URI or query string.
        This function models the behavior of `urllib.parse.unquote_plus`,
        albeit in a faster, more straightforward manner.
        Args:
            encoded_uri (str): An encoded URI (full or partial).
        Keyword Arguments:
            unquote_plus (bool): Set to ``False`` to retain any plus ('+')
                characters in the given string, rather than converting them to
                spaces (default ``True``). Typically you should set this
                to ``False`` when decoding any part of a URI other than the
                query string.
        Returns:
            str: A decoded URL. If the URL contains escaped non-ASCII
            characters, UTF-8 is assumed per RFC 3986.
        """
    
        decoded_uri = encoded_uri
    
        # PERF(kgriffs): Don't take the time to instantiate a new
        # string unless we have to.
        if '+' in decoded_uri and unquote_plus:
            decoded_uri = decoded_uri.replace('+', ' ')
    
        # Short-circuit if we can
        if '%' not in decoded_uri:
            return decoded_uri
    
        # NOTE(kgriffs): Clients should never submit a URI that has
        # unescaped non-ASCII chars in them, but just in case they
        # do, let's encode into a non-lossy format.
        decoded_uri = decoded_uri.encode('utf-8')
    
        # PERF(kgriffs): This was found to be faster than using
        # a regex sub call or list comprehension with a join.
        tokens = decoded_uri.split(b'%')
        decoded_uri = tokens[0]
        for token in tokens[1:]:
            token_partial = token[:2]
            try:
                decoded_uri += _HEX_TO_BYTE[token_partial] + token[2:]
            except KeyError:
                # malformed percentage like "x=%" or "y=%+"
                decoded_uri += b'%' + token
    
        # Convert back to str
        return decoded_uri.decode('utf-8', 'replace')
    

    The code optimized:

    import io
    def decode(encoded_uri, unquote_plus=True):
        """Decodes percent-encoded characters in a URI or query string.
        This function models the behavior of `urllib.parse.unquote_plus`,
        albeit in a faster, more straightforward manner.
        Args:
            encoded_uri (str): An encoded URI (full or partial).
        Keyword Arguments:
            unquote_plus (bool): Set to ``False`` to retain any plus ('+')
                characters in the given string, rather than converting them to
                spaces (default ``True``). Typically you should set this
                to ``False`` when decoding any part of a URI other than the
                query string.
        Returns:
            str: A decoded URL. If the URL contains escaped non-ASCII
            characters, UTF-8 is assumed per RFC 3986.
        """
    
        decoded_uri = encoded_uri
    
        # PERF(kgriffs): Don't take the time to instantiate a new
        # string unless we have to.
        if '+' in decoded_uri and unquote_plus:
            decoded_uri = decoded_uri.replace('+', ' ')
    
        # Short-circuit if we can
        if '%' not in decoded_uri:
            return decoded_uri
    
        # NOTE(kgriffs): Clients should never submit a URI that has
        # unescaped non-ASCII chars in them, but just in case they
        # do, let's encode into a non-lossy format.
        decoded_uri = decoded_uri.encode('utf-8')
    
        # PERF(kgriffs): This was found to be faster than using
        # a regex sub call or list comprehension with a join.
        tokens = decoded_uri.split(b'%')
        bytes = io.BytesIO()
        bytes.write(tokens[0])
        # decoded_uri = tokens[0]
        for token in tokens[1:]:
            token_partial = token[:2]
            try:
                bytes.write(_HEX_TO_BYTE[token_partial])
                bytes.write(token[2:])
                # decoded_uri += _HEX_TO_BYTE[token_partial] + token[2:]
            except KeyError:
                # malformed percentage like "x=%" or "y=%+"
                # decoded_uri += b'%' + token
                bytes.write(b'%')
                bytes.write(token)
    
        # Convert back to str
        # return decoded_uri.decode('utf-8', 'replace')
        return bytes.getvalue().decode('utf-8', 'replace')
    

    And the time costs before optimizing is python3.7 test.py 2019-10-27 23:25:38,030 urllib3.connectionpool: DEBUG Starting new HTTP connection (1): 127.0.0.1:8080 2019-10-27 23:26:04,819 urllib3.connectionpool: DEBUG http://127.0.0.1:8080 "POST /api/import/postdata/async HTTP/1.1" 200 146 2019-10-27 23:26:04,820 main : DEBUG post data return: {"status":"ok","error_msg":"","successRecords":[],"failedRecords":[],"totalSuccessRecords":500,"totalFailedRecords":0,"timeElapsed":26.7830269337} 2019-10-27 23:26:04,821 main : DEBUG time elapsed: 27.266945600509644 After optimizing is: python3.7 test.py 2019-10-27 23:54:09,490 urllib3.connectionpool: DEBUG Starting new HTTP connection (1): 127.0.0.1:8080 2019-10-27 23:54:09,791 urllib3.connectionpool: DEBUG http://127.0.0.1:8080 "POST /api/import/postdata/async HTTP/1.1" 200 145 2019-10-27 23:54:09,794 main : DEBUG post data return: {"status":"ok","error_msg":"","successRecords":[],"failedRecords":[],"totalSuccessRecords":500,"totalFailedRecords":0,"timeElapsed":0.2936162949} 2019-10-27 23:54:09,794 main : DEBUG time elapsed: 0.862856388092041

    As you can see, there is a great improvement

    bug perf 
    opened by JerryKwan 23
  • doc(changelog): reorganize towncrier

    doc(changelog): reorganize towncrier

    Summary of Changes

    Reorganize towncrier to match previous changelogs

    Related Issues

    N/A

    Pull Request Checklist

    This is just a reminder about the most common mistakes. Please make sure that you tick all appropriate boxes. But please read our contribution guide at least once; it will save you a few review cycles!

    If an item doesn't apply to your pull request, check it anyway to make it apparent that there's nothing to do.

    • [x] Added tests for changed code.
    • [x] Prefixed code comments with GitHub nick and an appropriate prefix.
    • [x] Coding style is consistent with the rest of the framework.
    • [x] Updated documentation for changed code.
      • [x] Added docstrings for any new classes, functions, or modules.
      • [x] Updated docstrings for any modifications to existing code.
      • [x] Added references to new classes, functions, or modules to the relevant RST file under docs/.
      • [x] Updated all relevant supporting documentation files under docs/.
      • [x] A copyright notice is included at the top of any new modules (using your own name or the name of your organization).
      • [x] Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
    • [x] Changes (and possible deprecations) have towncrier news fragments under docs/_newsfragments/. (Run towncrier --draft to ensure it renders correctly.)

    If you have any questions to any of the points above, just submit and ask! This checklist is here to help you, not to deter you from contributing!

    PR template inspired by the attrs project.

    opened by csojinb 22
  • feat(api): Add CORS support

    feat(api): Add CORS support

    Add first-class support for CORS to falcon. Includes a CORS object for specifying CORS configuration, CORS middleware for applying a CORS object, and a kwarg to the API class that will take a CORS object and configure the middleware for you. Allows over-riding the CORS configuration on a per-resource basis.

    Resolves issue #303

    needs-decision 
    opened by lwcolton 21
  • req.params is empty when incoming HTTP POST data has a field longer than 256 bytes.

    req.params is empty when incoming HTTP POST data has a field longer than 256 bytes.

    Setup a simple API, as follows with Falcon 3.1.1:

    class MyApi(object):
        def on_post(self, req, resp):
            form = req.params
            # do stuff with the form data...
    
    app = falcon.App()
    app.req_options.auto_parse_form_urlencoded = True
    app.add_route('/myapi', MyApi())
    

    Call the API from a C# app using BestHTTP/2.

    HTTPRequest request = new HTTPRequest(new Uri(MyApiUri), HTTPMethods.Post, MyApiResponseCallback);
    string a1= "somevalue";
    string a2 = "someothervalue";
    string a3 = "somethirdvalue";
    request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
    request.AddField("a1", a1);
    request.AddField("a2", a2);
    request.AddField("a3", a3);
    request.ConnectTimeout = new TimeSpan(0, 0, 10);
    request.Timeout = new TimeSpan(0, 0, 10);
    request.Send();
    

    The above works perfectly as long as the strings aren't too large. A simple test case:

    • a2 and a3 values remain constant between tests, while a1 changes between a shorter string and a longer string.
    • When a1 is long enough (>256 bytes), the API no longer extracts form data from req.params.

    I have not found any information about a limit the 100s of bytes for a given field in a POST request like this, and I have reason to believe that this issue is on the Falcon side. I have been able to extract the values (not keys) from req.media and confirmed that the data in question has arrived at the server, but fails to be read through the request params method wrapper.

    Any help would be greatly appreciated.

    needs-information 
    opened by justinvirtualitics 2
  • Request: Add sameSite parameter to unset_cookie

    Request: Add sameSite parameter to unset_cookie

    It would be appreciated if I could use the unset_cookie method to unset a cookie I created with the parameter sameSite='None'. Otherwise, I'm forced to use set_cookie for the sole purpose of unsetting that cookie...

    With current behaviour, sameSite is set to 'Lax' by default and so the browser ignores it because I'm using different domains for front and backend, and so using Cross Site requests.

    Thank you

    good first issue enhancement needs contributor 
    opened by agulab 1
  • Replace the obsolete JS media type

    Replace the obsolete JS media type

    RFC-4329 is obsolete.

    According to RFC-9239,

    • Changed the intended usage of the media type "text/javascript" from OBSOLETE to COMMON.
    • Changed the intended usage for all other script media types to obsolete.
    good first issue maintenance 
    opened by euj1n0ng 4
  • Cryptic 500 Internal Server Error when testing ASGI app endpoint

    Cryptic 500 Internal Server Error when testing ASGI app endpoint

    I'm trying to test an endpoint of my ASGI app using pytest. For now I'm simply running client.simulate_post("/my/endpoint)" and doing nothing with it. The test succeeds, but regardless of what I put into the request, result.json is always {'title': '500 Internal Server Error'}.

    This could very well mean that something in my endpoint is broken, which is why I want the test in the first place, but the trouble is that I get no information on what went wrong or where. I don't expect that to be in the response for obvious reasons, but even if I set a debugger breakpoint on the very first line of the endpoint's handler, it is never triggered, and looking around with the debugger on the simulate_post() call itself I couldn't figure out what is wrong either.

    It would seem the error occurs before the request handler is even called, meaning something is wrong in my setup, but the simulate_post() call itself does not raise any exception or something inside it catches it and turns it into a 500 inside the response, effectively hiding the error and its cause. How could I debug this further?

    documentation good first issue question 
    opened by berzi 9
  • [WIP] docs(user):add a recipe on how to organize a falcon project file structure.

    [WIP] docs(user):add a recipe on how to organize a falcon project file structure.

    First time writing a documentations for anything, so sorry in advance!. This PR tackles issue #1520, i added a "Organizing Your Project" under recipes in the user guide. Any feedback would be much appreciated!

    opened by RioAtHome 1
Releases(3.1.1)
Creating delicious APIs for Django apps since 2010.

django-tastypie Creating delicious APIs for Django apps since 2010. Currently in beta but being used actively in production on several sites. Requirem

3.8k Dec 30, 2022
Simple Crud Api With Django Rest Framework

SIMPLE CRUD API WITH DJANGO REST FRAMEWORK Django REST framework is a powerful and flexible toolkit for building Web APIs. Requirements Python 3.6 Dja

kibet hillary 1 May 03, 2022
Embrace the APIs of the future. Hug aims to make developing APIs as simple as possible, but no simpler.

Read Latest Documentation - Browse GitHub Code Repository hug aims to make developing Python driven APIs as simple as possible, but no simpler. As a r

Hug API Framework 6.7k Dec 27, 2022
Browsable web APIs for Flask.

Flask API Browsable web APIs for Flask. Status: This project is in maintenance mode. The original author (Tom Christie) has shifted his focus to API S

Flask API 1.3k Dec 27, 2022
Little Library API REST

Little Library API REST py 3.10 The only one requeriment it's to have Flask installed.

Luis Quiñones Requelme 1 Dec 15, 2021
Automatically generate a RESTful API service for your legacy database. No code required!

sandman2 sandman2 documentation [ ~ Dependencies scanned by PyUp.io ~ ] sandman2 automagically generates a RESTful API service from your existing data

Jeff Knupp 1.9k Jan 07, 2023
RESTler is the first stateful REST API fuzzing tool for automatically testing cloud services through their REST APIs and finding security and reliability bugs in these services.

RESTler is the first stateful REST API fuzzing tool for automatically testing cloud services through their REST APIs and finding security and reliability bugs in these services.

Microsoft 1.8k Jan 04, 2023
Country-specific Django helpers, to use in Django Rest Framework

django-rest-localflavor Country-specific serializers fields, to Django Rest Framework Documentation (soon) The full documentation is at https://django

Gilson Filho 19 Aug 30, 2022
JSON:API support for Django REST framework

JSON:API and Django REST framework Overview JSON:API support for Django REST framework Documentation: https://django-rest-framework-json-api.readthedo

1k Dec 27, 2022
Authentication Module for django rest auth

django-rest-knox Authentication Module for django rest auth Knox provides easy to use authentication for Django REST Framework The aim is to allow for

James McMahon 873 Dec 30, 2022
Key-Value база данных на Tarantool и REST API к ней.

KVmail Key-Value база данных на Tarantool и REST API к ней. Документация к API доступна здесь. Requiremrnts ubuntu 16.04+ python3.6+ supervisord nginx

1 Jun 16, 2021
A minimalistic manga reader for desktop built with React and Django

smanga A minimalistic manga reader/server for serving local manga images on desktop browser. Provides a two-page view layout just as reading a physica

Padam Upreti 13 Sep 24, 2022
Kong API Manager with Prometheus And Splunk

API Manager Stack Run Kong Server + Konga + Prometheus + Grafana + API & DDBB + Splunk Clone the proyect and run docker-compose up

Santiago Fernandez 82 Nov 26, 2022
DSpace REST API Client Library

DSpace Python REST Client Library This client library allows Python 3 scripts (Python 2 probably compatible but not officially supported) to interact

The Library Code GmbH 10 Nov 21, 2022
A JSON Web Token authentication plugin for the Django REST Framework.

Simple JWT Abstract Simple JWT is a JSON Web Token authentication plugin for the Django REST Framework. For full documentation, visit django-rest-fram

Jazzband 3.3k Jan 04, 2023
A RESTful whois

whois-rest A RESTful whois. Installation $ pip install poetry $ poetry install $ uvicorn app:app INFO: Started server process [64616] INFO: W

Manabu Niseki 4 Feb 19, 2022
Django Ninja is a web framework for building APIs with Django and Python 3.6+ type hints.

💨 Fast, Async-ready, Openapi, type hints based framework for building APIs

Vitaliy Kucheryaviy 3.8k Jan 04, 2023
Authentication for Django Rest Framework

Dj-Rest-Auth Drop-in API endpoints for handling authentication securely in Django Rest Framework. Works especially well with SPAs (e.g React, Vue, Ang

Michael 1.1k Dec 28, 2022
REST API framework designed for human beings

Eve Eve is an open source Python REST API framework designed for human beings. It allows to effortlessly build and deploy highly customizable, fully f

eve 6.6k Jan 04, 2023
Web APIs for Django. 🎸

Django REST framework Awesome web-browsable Web APIs. Full documentation for the project is available at https://www.django-rest-framework.org/. Fundi

Encode 24.7k Jan 04, 2023