doc: Rework introductory text in docs and README (#1078)
* doc: Rework introductory text in docs and README * doc: Further improvements to intro text
This commit is contained in:
Kurt Griffiths
John Vrbanac
parent
25e0c3873b
commit
72c634e8f7
2
LICENSE
2
LICENSE
|
|
@ -1,4 +1,4 @@
|
|||
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");
|
||||
|
|
|
|||
71
README.rst
71
README.rst
|
|
@ -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>`__.
|
||||
* `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
|
||||
------------
|
||||
How is Falcon different?
|
||||
------------------------
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
**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.
|
||||
**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.
|
||||
|
||||
**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>`__.
|
||||
**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*
|
||||
|
||||
`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+.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
.. _`six`: http://pythonhosted.org/six/
|
||||
.. _`mimeparse`: https://code.google.com/p/mimeparse/
|
||||
**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
|
||||
----------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue