doc: Publish website
This commit is contained in:
kgriffs
217
README.md
217
README.md
@@ -1,215 +1,4 @@
|
||||
Falcon [](https://travis-ci.org/racker/falcon) [](https://coveralls.io/r/racker/falcon)
|
||||
======
|
||||
[falconframework.org](http://falconframework.org)
|
||||
=============
|
||||
|
||||
:runner: Come hang out with us in **#falconframework** on freenode.
|
||||
|
||||
Falcon is a [high-performance Python framework][home] for building cloud APIs. It tries to do as little as possible while remaining [highly effective][benefits].
|
||||
|
||||
> 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*
|
||||
|
||||
[home]: http://falconframework.org/index.html
|
||||
[benefits]: http://falconframework.org/index.html#Benefits
|
||||
|
||||
<img align="right" src="http://falconframework.org/img/falcon.png" alt="Falcon picture" />
|
||||
|
||||
### 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 processes requests [several times faster][bench] than other popular web frameworks.
|
||||
|
||||
**Light.** Only the essentials are included, with *six* being the only dependency outside the standard library. We work to keep the code lean, making Falcon easier to test, optimize, and deploy.
|
||||
|
||||
**Flexible.** Falcon can be deployed in a variety of ways, depending on your needs. The framework speaks WSGI, and works great with [Python 2.6 and 2.7, PyPy, and Python 3.3][ci]. There's no tight coupling with any async framework, leaving you free to mix-and-match what you need.
|
||||
|
||||
[bench]: http://falconframework.org/#Metrics
|
||||
[ci]: https://travis-ci.org/racker/falcon
|
||||
|
||||
### Features ###
|
||||
|
||||
* Intuitive routing via URI templates and resource classes
|
||||
* Easy access to headers and bodies through request and response classes
|
||||
* Idiomatic HTTP error responses via a handy exception base class
|
||||
* DRY request processing using global, resource, and method hooks
|
||||
* Snappy unit testing through WSGI helpers and mocks
|
||||
* 20% speed boost when Cython is available
|
||||
* Python 2.6, Python 2.7, PyPy and Python 3.3 support
|
||||
* Speed, speed, and more speed!
|
||||
|
||||
### Install ###
|
||||
|
||||
```bash
|
||||
$ pip install cython falcon
|
||||
```
|
||||
|
||||
### Test ###
|
||||
|
||||
```bash
|
||||
$ pip install nose && nosetests
|
||||
```
|
||||
|
||||
To test across all supported Python versions:
|
||||
|
||||
```bash
|
||||
$ pip install tox && tox
|
||||
```
|
||||
|
||||
### Usage ###
|
||||
|
||||
Read the source, Luke!
|
||||
|
||||
Docstrings can be found throughout the Falcon code base for your learning pleasure. You can also ask questions in **#falconframework** on freenode. We are planning on having real docs eventually; if you need them right away, consider sending a pull request. ;)
|
||||
|
||||
Here is a simple example showing how to create a Falcon-based API.
|
||||
|
||||
```python
|
||||
class ThingsResource:
|
||||
def on_get(self, req, resp):
|
||||
"""Handles GET requests"""
|
||||
resp.status = falcon.HTTP_200
|
||||
resp.body = 'Hello world!'
|
||||
|
||||
# falcon.API instances are callable WSGI apps
|
||||
wsgi_app = api = falcon.API()
|
||||
|
||||
# Resources are represented by long-lived class instances
|
||||
things = ThingsResource()
|
||||
|
||||
# things will handle all requests to the '/things' URL path
|
||||
api.add_route('/things', things)
|
||||
```
|
||||
|
||||
Here is a more involved example, demonstrating getting headers and query parameters, handling errors, and reading/writing message bodies.
|
||||
|
||||
```python
|
||||
|
||||
import json
|
||||
import logging
|
||||
|
||||
import falcon
|
||||
|
||||
|
||||
class StorageEngine:
|
||||
pass
|
||||
|
||||
|
||||
class StorageError(Exception):
|
||||
pass
|
||||
|
||||
|
||||
def token_is_valid(token, user_id):
|
||||
return True # Suuuuuure it's valid...
|
||||
|
||||
|
||||
def auth(req, resp, params):
|
||||
# Alternatively, do this in middleware
|
||||
token = req.get_header('X-Auth-Token')
|
||||
|
||||
if token is None:
|
||||
raise falcon.HTTPUnauthorized('Auth token required',
|
||||
'Please provide an auth token '
|
||||
'as part of the request',
|
||||
'http://docs.example.com/auth')
|
||||
|
||||
if not token_is_valid(token, params['user_id']):
|
||||
raise falcon.HTTPUnauthorized('Authentication required',
|
||||
'The provided auth token is '
|
||||
'not valid. Please request a '
|
||||
'new token and try again.',
|
||||
'http://docs.example.com/auth')
|
||||
|
||||
|
||||
def check_media_type(req, resp, params):
|
||||
if not req.client_accepts_json():
|
||||
raise falcon.HTTPUnsupportedMediaType(
|
||||
'Media Type not Supported',
|
||||
'This API only supports the JSON media type.',
|
||||
'http://docs.examples.com/api/json')
|
||||
|
||||
|
||||
class ThingsResource:
|
||||
|
||||
def __init__(self, db):
|
||||
self.db = db
|
||||
self.logger = logging.getLogger('thingsapi.' + __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('Service Outage', description)
|
||||
|
||||
resp.set_header('X-Powered-By', 'Donuts')
|
||||
resp.status = falcon.HTTP_200
|
||||
resp.body = json.dumps(result)
|
||||
|
||||
def on_post(self, req, resp, user_id):
|
||||
try:
|
||||
raw_json = req.stream.read()
|
||||
except Exception:
|
||||
raise falcon.HTTPError(falcon.HTTP_748,
|
||||
'Read Error',
|
||||
'Could not read the request body. Must be '
|
||||
'them ponies again.')
|
||||
|
||||
try:
|
||||
thing = json.loads(raw_json, 'utf-8')
|
||||
except ValueError:
|
||||
raise falcon.HTTPError(falcon.HTTP_753,
|
||||
'Malformed JSON',
|
||||
'Could not decode the request body. The '
|
||||
'JSON was incorrect.')
|
||||
|
||||
try:
|
||||
proper_thing = self.db.add_thing(thing)
|
||||
|
||||
except StorageError:
|
||||
raise falcon.HTTPError(falcon.HTTP_725,
|
||||
'Database Error',
|
||||
"Sorry, couldn't write your thing to the "
|
||||
'database. It worked on my machine.')
|
||||
|
||||
resp.status = falcon.HTTP_201
|
||||
resp.location = '/%s/things/%s' % (user_id, proper_thing.id)
|
||||
|
||||
wsgi_app = api = falcon.API(before=[auth, check_media_type])
|
||||
|
||||
db = StorageEngine()
|
||||
things = ThingsResource(db)
|
||||
api.add_route('/{user_id}/things', things)
|
||||
|
||||
```
|
||||
|
||||
### Contributing ###
|
||||
|
||||
Kurt Griffiths (kgriffs) is the creator and current maintainer of the Falcon framework. Pull requests are always welcome.
|
||||
|
||||
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][ajs] (one-liners are OK for now but body and footer may be required as the project matures).
|
||||
|
||||
Comments follow [Google's style guide][goog-style-comments].
|
||||
|
||||
[ajs]: http://goo.gl/QpbS7
|
||||
[goog-style-comments]: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
|
||||
|
||||
### Legal ###
|
||||
|
||||
Copyright 2013 by Rackspace Hosting, Inc.
|
||||
|
||||
Falcon image courtesy of [John O'Neill](https://commons.wikimedia.org/wiki/File:Brown-Falcon,-Vic,-3.1.2008.jpg).
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the 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.
|
||||
Python Falcon Framework Marketing Site
|
||||
|
||||
BIN
css/Amethysta-Regular.ttf
Executable file
BIN
css/Amethysta-Regular.ttf
Executable file
Binary file not shown.
BIN
css/DroidSans-Bold.ttf
Executable file
BIN
css/DroidSans-Bold.ttf
Executable file
Binary file not shown.
BIN
css/DroidSans.ttf
Executable file
BIN
css/DroidSans.ttf
Executable file
Binary file not shown.
873
css/bootstrap.min.css
vendored
Executable file
873
css/bootstrap.min.css
vendored
Executable file
File diff suppressed because one or more lines are too long
1
css/styles.css
Normal file
1
css/styles.css
Normal file
@@ -0,0 +1 @@
|
||||
@font-face { font-family:'Amethysta'; font-style:normal; font-weight:400; src:local(Amethysta),local(Amethysta-Regular),url(http://c420059.r59.cf1.rackcdn.com/assets/css/Amethysta-Regular.ttf) format("truetype") } @font-face { font-family:'Droid Sans'; font-style:normal; font-weight:400; src:local('Droid Sans'),local(DroidSans),url(http://c420059.r59.cf1.rackcdn.com/assets/css/DroidSans.ttf) format("truetype") } @font-face { font-family:'Droid Sans'; font-style:normal; font-weight:700; src:local('Droid Sans Bold'),local(DroidSans-Bold),url(http://c420059.r59.cf1.rackcdn.com/assets/css/DroidSans-Bold.ttf) format("truetype") } body { font-family:"Droid Sans"; background-color:#fefefe } .carousel { margin-bottom:0 } .carousel .container { position:relative; z-index:9 } .carousel-control { height:80px; margin-top:0; font-size:120px; text-shadow:0 1px 1px rgba(0,0,0,.4); background-color:transparent; border:0 } .carousel .item { height:380px } .carousel .cover { position:absolute; top:0; left:0; min-width:100%; height:380px; background-color:#3e3e3e; background-image:url(../img/sky.jpg) } .carousel-caption { background-color:transparent; position:static; max-width:550px; padding:0; margin-top:130px } .carousel-caption h1,.carousel-caption .lead { margin:0; line-height:1.25; color:#fefefe; text-shadow:0 1px 1px rgba(0,0,0,0.7) } .carousel-caption h1 { font-family:"Amethysta"; font-size:120px } .carousel-caption .btn { margin-top:10px } .background-strip { position:absolute; z-index:-1; height:220px; width:100%; padding:0; margin:0; background-image:-ms-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:-moz-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:-o-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:-webkit-gradient(linear,left top,left bottom,color-stop(0,#FFF),color-stop(1,#DCDDE2)); background-image:-webkit-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:linear-gradient(to bottom,#FFF 0%,#DCDDE2 100%) } #nav { padding-top:25px } .featurette-divider { margin-top:160px; border:none } .featurette { overflow:hidden } .featurette-image { margin-top:-120px } .featurette-image.pull-left { margin-right:40px } .featurette-image.pull-right { margin-left:40px } .featurette-heading { font-size:50px; font-weight:300; line-height:1; letter-spacing:-1px } .featurette h2 { padding-bottom:8px } table.benchmarks { border-collapse:1; border:1px solid #000 } table.benchmarks tr td { width:100px } table.benchmarks tr td:first-child { width:260px } table.benchmarks tr th,table.benchmarks tr td { text-align:right; border:1px solid #000; padding:10px } table.benchmarks tr.highlight td { background-color:#eee5c7 } table.benchmarks th { background-color:#DCDDE2; background-image:-ms-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:-moz-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:-o-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:-webkit-gradient(linear,left top,left bottom,color-stop(0,#FFF),color-stop(1,#DCDDE2)); background-image:-webkit-linear-gradient(top,#FFF 0%,#DCDDE2 100%); background-image:linear-gradient(to bottom,#FFF 0%,#DCDDE2 100%) } /* Thanks Daniel! http://unindented.org/articles/2009/10/github-ribbon-using-css-transforms */ .forkme { background-color: #a00; overflow: hidden; /* top left corner */ position: absolute; z-index: 10; left: -3em; top: 2.5em; /* 45 deg ccw rotation */ transform: rotate(-45deg); -moz-transform: rotate(-45deg); -webkit-transform: rotate(-45deg); /* shadow */ box-shadow: 0 0 1em #888; -moz-box-shadow: 0 0 1em #888; -webkit-box-shadow: 0 0 1em #888; } .forkme a { border: 1px solid #faa; color: #fff; display: block; font: bold 81.25% 'Helvetiva Neue', Helvetica, Arial, sans-serif; margin: 0.05em 0 0.075em 0; padding: 0.5em 3.5em; text-align: center; text-decoration: none; /* shadow */ text-shadow: 0 0 0.5em #444; }
|
||||
BIN
favicon.ico
Normal file
BIN
favicon.ico
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.4 KiB |
BIN
img/falcon.png
Normal file
BIN
img/falcon.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
BIN
img/sky.jpg
Normal file
BIN
img/sky.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
1
index.html
Normal file
1
index.html
Normal file
File diff suppressed because one or more lines are too long
7
js/bootstrap.min.js
vendored
Executable file
7
js/bootstrap.min.js
vendored
Executable file
File diff suppressed because one or more lines are too long
2
js/jquery.js
vendored
Normal file
2
js/jquery.js
vendored
Normal file
File diff suppressed because one or more lines are too long
@@ -1,6 +1,6 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
git checkout gh-pages
|
||||
git
|
||||
rm -rf css
|
||||
rm -rf img
|
||||
rm -rf js
|
||||
|
||||
Reference in New Issue
Block a user