openstack/deb-python-falcon
Code Issues Proposed changes

doc(reference): Cleaned up directives and added section intros

Browse Source
This commit is contained in:
kgriffs
2014-04-04 17:19:49 -05:00
parent 6cf8c6e2b7
commit 4d4c77fed4
12 changed files with 175 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@@ -28,6 +28,9 @@ nosetests.xml
htmlcov
*.dat
# Docs
doc/_build
# Translations
*.mo

13
doc/api/api.rst
View File

@@ -3,6 +3,17 @@
API Class
=========
.. automodule:: falcon.api
Falcon's API class is a WSGI callable "application" that you can host with any
of a number of WSGI servers.
.. code:: python
import falcon
api = application = falcon.API()
.. autoclass:: falcon.API
:members:
:undoc-members:

30
doc/api/errors.rst Normal file
View File

@@ -0,0 +1,30 @@
.. _errors:
Error Handling
==============
When something goes horribly (or mildly) wrong, you *could* manually set the
error status, appropriate response headers, and even an error body using the
``resp`` object. However, Falcon tries to make things a bit easier by
providing a set of exceptions you can raise when something goes wrong. In fact,
if Falcon catches any exception your responder throws that inherits from
``falcon.HTTPError``, the framework will convert that exception to an
appropriate HTTP error response.
You may raise an instance of ``falcon.HTTPError`` directly, or use any one
of a number of predefined error classes that try to be idiomatic in
setting appropriate headers and bodies.
Base Class
----------
.. autoclass:: falcon.HTTPError
:members:
:undoc-members:
Predefined Errors
-----------------
.. automodule:: falcon.exceptions
:members:
:undoc-members:

42
doc/api/hooks.rst
View File

@@ -3,6 +3,44 @@
Hooks
=====
.. automodule:: falcon.hooks
:members:
Falcon support *before* and *after* hooks. You install a hook simply by
applying one of the decorators below either to an individual responder or
to an entire resource.
For example, suppose you had a hook like this:
.. code:: python
def validate_image_type(req, resp, params):
if req.content_type not in ALLOWED_IMAGE_TYPES:
msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
raise falcon.HTTPBadRequest('Bad request', msg)
You would attach the hook to an ``on_post`` responder like so:
.. code:: python
@falcon.before(validate_image_type)
def on_post(self, req, resp):
Or, if you had a hook that you would like to applied to *all*
responders for a given resource, you could install the hook like this:
.. code:: python
@falcon.before(extract_project_id)
class Message(object):
# ...
And you can apply hooks globally by passing them into the API class
initializer (note that this does not require the use of a decorator):
.. code:: python
falcon.API(before=[extract_project_id])
.. automodule:: falcon
:members: before, after
:undoc-members:

36
doc/api/request_and_response.rst
View File

@@ -1,19 +1,33 @@
.. _request_and_response:
.. _request:
Request and Response
====================
Req & Resp
==========
Request
-------
Instances of the Request and Response classes are passed into responders as the second
and third arguments, respectively.
.. automodule:: falcon.request
.. code:: python
import falcon
class Resource(object):
def on_get(self, req, resp):
resp.body = '{"message": "Hello world!"}'
resp.status = falcon.HTTP_200
Request Class
-------------
.. autoclass:: falcon.Request
:members:
:undoc-members:
Response
--------
Response Class
--------------
.. automodule:: falcon.response
.. autoclass:: falcon.Response
:members:
:undoc-members:

11
doc/api/status.rst Normal file
View File

@@ -0,0 +1,11 @@
.. _status:
Status Codes
============
Falcon provides the following status definitions that you can use to set
``resp.status`` from within your responders and hooks.
.. automodule:: falcon.status_codes
:members:
:undoc-members:

23
doc/api/status_and_errors.rst
View File

@@ -1,23 +0,0 @@
.. _status_and_errors:
HTTP Status and Error Handling
==============================
Status Codes
------------
This module contains variables representing the HTTP status codes.
HTTP Error
----------
.. automodule:: falcon.http_error
:members:
:undoc-members:
Exceptions
----------
.. automodule:: falcon.exceptions
:members:
:undoc-members:

21
doc/api/util.rst
View File

@@ -1,7 +1,7 @@
.. _util:
Miscellaneous Utilities
=======================
Utilities
=========
URI Functions
-------------
@@ -10,13 +10,24 @@ URI Functions
:members:
:undoc-members:
Data Structures
---------------
Testing
-------
.. automodule:: falcon.util.structures
.. autoclass:: falcon.testing.TestBase
:members:
:undoc-members:
.. autoclass:: falcon.testing.TestResource
:members:
.. autoclass:: falcon.testing.StartResponseMock
:members:
:undoc-members:
.. automodule:: falcon.testing
:members: httpnow, rand_string, create_environ
:undoc-members:
Miscellaneous
-------------

19
doc/index.rst
View File

@@ -65,7 +65,7 @@ Falcon tries to do as little as possible while remaining highly effective.
- Minimal attack surface for writing secure APIs
- 100% code coverage with a comprehensive test suite
- Only depends on six and mimeparse
- Python 2.6, 2.7, 3.3 + PyPy
- Python 2.6, 2.7, 3.3, 3.4 + PyPy
User Guide
@@ -80,16 +80,16 @@ User Guide
user/tutorial
Community Guide
-----------------
.. Community Guide
.. -----------------
*Coming soon*
.. *Coming soon*
Contributor Guide
-----------------
.. Contributor Guide
.. -----------------
*Coming soon*
.. *Coming soon*
API Documentation
@@ -99,8 +99,9 @@ API Documentation
:maxdepth: 2
api/api
api/hooks
api/request_and_response
api/status_and_errors
api/status
api/errors
api/hooks
api/util

3
doc/user/advanced.rst
View File

@@ -4,4 +4,5 @@
.. after hooks
.. error responses for auth - 404 ?
.. error hooks
.. document all the individual error classes?
.. document all the individual error classes?
.. stacked hooks

30
falcon/__init__.py
View File

@@ -1,20 +1,16 @@
"""Falcon is a fast micro-framework for building cloud APIs.
Copyright 2013 by Rackspace Hosting, Inc.
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.
"""
# Copyright 2013 by Rackspace Hosting, Inc.
#
# 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.
HTTP_METHODS = (
'CONNECT',

30
falcon/testing/__init__.py
View File

@@ -1,20 +1,16 @@
"""Helper classes and functions for unit-testing API's implemented on Falcon.
Copyright 2013 by Rackspace Hosting, Inc.
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.
"""
# Copyright 2013 by Rackspace Hosting, Inc.
#
# 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.
# Hoist classes and functions into the falcon.testing namespace
from falcon.testing.helpers import * # NOQA