Commit 72c634e8 authored by Kurt Griffiths's avatar Kurt Griffiths Committed by John Vrbanac

doc: Rework introductory text in docs and README (#1078)

* doc: Rework introductory text in docs and README

* doc: Further improvements to intro text
parent 25e0c387
Copyright 2012-2016 by Rackspace Hosting, Inc. and other contributors,
Copyright 2012-2017 by Rackspace Hosting, Inc. and other contributors,
as noted in the individual source code files.
Licensed under the Apache License, Version 2.0 (the "License");
......
......@@ -6,39 +6,58 @@ Falcon |Docs| |Build Status| |codecov.io|
*- Antoine de Saint-Exupéry*
Falcon is a `high-performance Python
framework <http://falconframework.org/index.html>`__ for building cloud
APIs. It encourages the REST architectural style, and tries to do as
little as possible while remaining `highly
effective <http://falconframework.org/index.html#Benefits>`__.
`Falcon <http://falconframework.org/index.html>`__ 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 server, and run great under
CPython 2.7, PyPy, and CPython 3.3+.
Quick Links
-----------
* `Read the docs <https://falcon.readthedocs.io/en/stable>`__.
* `Join the discussion group <https://groups.google.com/forum/#!forum/falconframework>`__.
* `Hang out in #falconframework on freenode <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`__.
Design Goals
------------
**Fast.** Cloud APIs need to turn around requests quickly, and make
efficient use of hardware. This is particularly important when serving
many concurrent requests. Falcon is among the fastest WSGI frameworks
available, processing requests
`several times faster <http://falconframework.org/#Metrics>`__ than
other Python web frameworks.
**Light.** Only the essentials are included, with *six* and *mimeparse*
being the only dependencies outside the standard library. We work hard
to keep the code lean, making Falcon easier to test, secure, optimize,
and deploy.
**Flexible.** Falcon is not opinionated when it comes to talking to
databases, rendering content, authorizing requests, etc. You are free to
mix and match your own favorite libraries. Falcon apps work with
any WSGI server, and run great under `CPython 2.6-2.7, PyPy, Jython 2.7,
and CPython 3.3-3.6 <https://travis-ci.org/falconry/falcon>`__.
* `Read the docs <https://falcon.readthedocs.io/en/stable>`__
* `Join the discussion group <https://groups.google.com/forum/#!forum/falconframework>`__
* `Hang out in #falconframework on freenode <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`__
How is Falcon different?
------------------------
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 <https://pypy.org>`__.
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 <http://semver.org/>`__) with a major version
increment. The code is rigorously tested with numerous inputs and we
require 100% coverage at all times. Six and mimeparse are the only
third-party dependencies.
**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 complimentary packages <https://github.com/falconry/falcon/wiki>`__.
**Debuggable.** Falcon eschews magic. It's easy to tell which inputs
lead to which outputs. Unhandled exceptions are never encapsulated or
masked. Potentially surprising behaviors, such as automatic request body
parsing, are well-documented and disabled by default. Finally, when it
comes to the framework itself, we take care to keep logic paths simple
and understandable. All this makes it easier to reason about the code
and to debug edge cases in large-scale deployments.
Features
--------
......@@ -52,7 +71,7 @@ Features
- Idiomatic HTTP error responses
- Straightforward exception handling
- Snappy unit testing through WSGI helpers and mocks
- CPython 2.6-2.7, PyPy 2.7, Jython 2.7, and CPython 3.3-3.6 support
- CPython 2.6-2.7, PyPy 2.7, Jython 2.7, and CPython 3.3+ support
- ~20% speed boost when Cython is available
Who's Using Falcon?
......
......@@ -3,21 +3,70 @@
Introduction
============
Falcon is a minimalist, high-performance web framework for building RESTful services and app backends with Python. Falcon works with any WSGI container that is compliant with PEP-3333, and works great with Python 2.6, Python 2.7, Python 3.3, Python 3.4 and PyPy, giving you a wide variety of deployment options.
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*
How is Falcon different?
------------------------
First, Falcon is one of the fastest WSGI frameworks available. When there is a conflict between saving the developer a few keystrokes and saving a few microseconds to serve a request, Falcon is strongly biased toward the latter. That being said, Falcon strives to strike a good balance between usability and speed.
`Falcon <http://falconframework.org/index.html>`__ 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.
Second, Falcon is lean. It doesn't try to be everything to everyone, focusing instead on a single use case: HTTP APIs. Falcon doesn't include a template engine, form helpers, or an ORM (although those are easy enough to add yourself). When you sit down to write a web service with Falcon, you choose your own adventure in terms of async I/O, serialization, data access, etc. In fact, Falcon only has two dependencies: `six`_, to make it easier to support both Python 2 and 3, and `mimeparse`_ for handling complex Accept headers. Neither of these packages pull in any further dependencies of their own.
Falcon apps work with any WSGI server, and run great under
CPython 2.7, PyPy, and CPython 3.3+.
Third, Falcon eschews magic. When you use the framework, it's pretty obvious which inputs lead to which outputs. Also, it's blatantly obvious where variables originate. All this makes it easier to reason about the code and to debug edge cases in large-scale deployments of your application.
.. _`six`: http://pythonhosted.org/six/
.. _`mimeparse`: https://code.google.com/p/mimeparse/
How is Falcon different?
------------------------
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 <https://pypy.org>`__.
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 <http://semver.org/>`__) with a major version
increment. The code is rigorously tested with numerous inputs and we
require 100% coverage at all times. Six and mimeparse are the only
third-party dependencies.
**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 complimentary packages <https://github.com/falconry/falcon/wiki>`__.
**Debuggable.** Falcon eschews magic. It's easy to tell which inputs
lead to which outputs. Unhandled exceptions are never encapsulated or
masked. Potentially surprising behaviors, such as automatic request body
parsing, are well-documented and disabled by default. Finally, when it
comes to the framework itself, we take care to keep logic paths simple
and understandable. All this makes it easier to reason about the code
and to debug edge cases in large-scale deployments.
Features
--------
- Highly-optimized, extensible code base
- Intuitive routing via URI templates and REST-inspired resource
classes
- 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 unit testing through WSGI helpers and mocks
- CPython 2.6-2.7, PyPy 2.7, Jython 2.7, and
About Apache 2.0
----------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment