falcon 0.1.6.post3 (beta)

A supersonic micro-framework for building cloud APIs.

System Message: ERROR/3 (<string>, line 57)

Unknown directive type "code".

.. code:: bash

    $ pip install cython falcon

System Message: ERROR/3 (<string>, line 64)

Unknown directive type "code".

.. code:: bash

    $ pip install nose && nosetests

System Message: ERROR/3 (<string>, line 70)

Unknown directive type "code".

.. code:: bash

    $ pip install tox && tox

System Message: ERROR/3 (<string>, line 86)

Unknown directive type "code".

.. code:: python

    # things.py

    # Let's get this party started
    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.body = ('\nTwo things awe me most, the starry sky '
                         'above me and the moral law within me.\n'
                         '\n'
                         '    ~ Immanuel Kant\n\n')

    # falcon.API instances are callable WSGI apps
    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)

System Message: ERROR/3 (<string>, line 118)

Unknown directive type "code".

.. code:: bash

    $ pip install gunicorn
    $ gunicorn things:app

System Message: ERROR/3 (<string>, line 125)

Unknown directive type "code".

.. code:: bash

    $ curl localhost:8000/things

System Message: ERROR/3 (<string>, line 134)

Unknown directive type "code".

.. code:: python

    import json
    import logging
    from wsgiref import simple_server

    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,
                  30)

            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)

    app = application = api

    # Useful for debugging problems in your API; works with pdb.set_trace()
    if __name__ == '__main__':
      httpd = simple_server.make_server('127.0.0.1', 8000, app)
      httpd.serve_forever()