v0.3.3

Fix link formatting

CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.3.3
+- Improved exceptions.
+- CORS support.
+
+# v0.3.2
+- Subtle improvements.
+
 # v0.3.1
 - Packaging fix.
 

README.md

@@ -41,81 +41,7 @@ This gets you a ASGI app, with a production static files server pre-installed, j
 
 ## More Examples
 
-Class-based views (and setting some headers and stuff):
-
-```python
-@api.route("/{greeting}")
-class GreetingResource:
-    def on_request(req, resp, *, greeting):   # or on_get...
-        resp.text = f"{greeting}, world!"
-        resp.headers.update({'X-Life': '42'})
-        resp.status_code = api.status_codes.HTTP_416
-```
-
-Render a template, with arguments:
-
-```python
-@api.route("/{greeting}")
-def greet_world(req, resp, *, greeting):
-    resp.content = api.template("index.html", greeting=greeting)
-```
-
-The `api` instance is available as an object during template rendering.
-
-Here, you can spawn off a background thread to run any function, out-of-request:
-
-```python
-@api.route("/")
-def hello(req, resp):
-
-    @api.background.task
-    def sleep(s=10):
-        time.sleep(s)
-        print("slept!")
-
-    sleep()
-    resp.content = "processing"
-```
-
-And even serve a GraphQL API:
-
-```python
-import graphene
-
-class Query(graphene.ObjectType):
-    hello = graphene.String(name=graphene.String(default_value="stranger"))
-
-    def resolve_hello(self, info, name):
-        return f"Hello {name}"
-
-api.add_route("/graph", graphene.Schema(query=Query))
-```
-
-We can then send a query to our service:
-
-```pycon
->>> requests = api.session()
->>> r = requests.get("http://;/graph", params={"query": "{ hello }"})
->>> r.json()
-{'data': {'hello': 'Hello stranger'}}
-```
-
-Or, request YAML back:
-
-```pycon
->>> r = requests.get("http://;/graph", params={"query": "{ hello(name:\"john\") }"}, headers={"Accept": "application/x-yaml"})
->>> print(r.text)
-data: {hello: Hello john}
-
-```
-
-Want HSTS?
-
-```
-api = responder.API(enable_hsts=True)
-```
-
-Boom.
+See [the documentation's feature tour](http://python-responder.org/en/latest/tour.html) for more details on features available in Responder.
 
 
 # Installing Responder
@@ -154,15 +80,7 @@ The primary concept here is to bring the niceties that are brought forth from bo
 - A production static file server is built-in.
 - Uvicorn built-in as a production web server. I would have chosen Gunicorn, but it doesn't run on Windows. Plus, Uvicorn serves well to protect against slowloris attacks, making nginx unnecessary in production.
 - GraphQL support, via Graphene. The goal here is to have any GraphQL query exposable at any route, magically.
-
-## Future Ideas
-
-- Cookie-based sessions are currently an afterthought, as this is an API framework, but websites are APIs too.
-- If frontend websites are supported, provide an official way to run webpack.
-
-# The Goal
-
-The primary goal here is to learn, not to get adoption. Though, who knows how these things will pan out.
+- Provide an official way to run webpack.
 
 
 ----------

docs/source/deployment.rst

@@ -30,7 +30,7 @@ The basics::
 
 Install Responder::
 
-    $ pipenv install responder
+    $ pipenv install responder --pre
     ...
 
 Write out an ``api.py``::

docs/source/index.rst

@@ -39,7 +39,7 @@ spread some `Hacktoberfest <https://hacktoberfest.digitalocean.com/>`_ spirit ar
 
 That ``async`` declaration is optional.
 
-This gets you a ASGI app, with a production static files server
+This gets you a ASGI app, with a production static files server (WhiteNoise)
 pre-installed, jinja2 templating (without additional imports), and a
 production webserver based on uvloop, serving up requests with gzip
 compression automatically.
@@ -144,14 +144,6 @@ Ideas
 - GraphQL support, via Graphene. The goal here is to have any GraphQL query exposable at any route, magically.
 
 
-Future Ideas
-------------
-
-- Cookie-based sessions are currently an afterthought, as this is an API framework, but websites are APIs too.
-- If frontend websites are supported, provide an official way to run webpack.
-
-
-
 Indices and tables
 ==================
 

docs/source/quickstart.rst

@@ -34,7 +34,7 @@ Next, we can run our web service easily, with ``api.run()``::
 
 This will spin up a production web server on port ``5042``, ready for incoming HTTP requests.
 
-Note: you can pass ``port=5000`` if you want to customize the port. The ``PORT`` environment variable for established web service providers (e.g. Heroku) will automatically be honored.
+Note: you can pass ``port=5000`` if you want to customize the port. The ``PORT`` environment variable for established web service providers (e.g. Heroku) will automatically be honored and will set the listening address to ``0.0.0.0`` automatically (also configurable through the ``address`` keyword argument).
 
 
 Accept Route Arguments

docs/source/tour.rst

@@ -9,7 +9,7 @@ Class-based views (and setting some headers and stuff)::
 
     @api.route("/{greeting}")
     class GreetingResource:
-        def on_request(req, resp, *, greeting):   # or on_get...
+        def on_request(self, req, resp, *, greeting):   # or on_get...
             resp.text = f"{greeting}, world!"
             resp.headers.update({'X-Life': '42'})
             resp.status_code = api.status_codes.HTTP_416
@@ -204,3 +204,26 @@ Want HSTS (to redirect all traffic to HTTPS)?
 
 
 Boom.
+
+CORS
+----
+
+Want `CORS <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/>`_ ?
+
+::
+
+    api = responder.API(cors=True)
+
+
+The default parameters used by **Responder** are restrictive by default, so you'll need to explicitly enable particular origins, methods, or headers, in order for browsers to be permitted to use them in a Cross-Domain context.
+
+In order to set custom parameters, you need to pass the ``cors_params`` argument, a dictionnary containing the following entries : 
+
+* ``allow_origins`` - A list of origins that should be permitted to make cross-origin requests. eg. ``['https://example.org', 'https://www.example.org']``. You can use ``['*']`` to allow any origin.
+* ``allow_origin_regex`` - A regex string to match against origins that should be permitted to make cross-origin requests. eg. ``'https://.*\.example\.org'``.
+* ``allow_methods`` - A list of HTTP methods that should be allowed for cross-origin requests. Defaults to `['GET']`. You can use ``['*']`` to allow all standard methods.
+* ``allow_headers`` - A list of HTTP request headers that should be supported for cross-origin requests. Defaults to ``[]``. You can use ``['*']`` to allow all headers. The ``Accept``, ``Accept-Language``, ``Content-Language`` and ``Content-Type`` headers are always allowed for CORS requests.
+* ``allow_credentials`` - Indicate that cookies should be supported for cross-origin requests. Defaults to ``False``.
+* ``expose_headers`` - Indicate any response headers that should be made accessible to the browser. Defaults to ``[]``.
+* ``max_age`` - Sets a maximum time in seconds for browsers to cache CORS responses. Defaults to ``60``.
+

responder/__version__.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.3.3"

responder/api.py

@@ -14,6 +14,8 @@ from starlette.debug import DebugMiddleware
 from starlette.testclient import TestClient
 from starlette.middleware.gzip import GZipMiddleware
 from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.exceptions import ExceptionMiddleware
 from apispec import APISpec
 from apispec.ext.marshmallow import MarshmallowPlugin
 from apispec import yaml_utils
@@ -26,6 +28,10 @@ from .routes import Route
 from .formats import get_formats
 from .background import BackgroundQueue
 from .templates import GRAPHIQL
+from .statics import (
+    DEFAULT_API_THEME, DEFAULT_SESSION_COOKIE, DEFAULT_SECRET_KEY, DEFAULT_CORS_PARAMS
+)
+
 
 # TODO: consider moving status codes here
 class API:
@@ -51,9 +57,11 @@ class API:
         static_route="/static",
         templates_dir="templates",
         auto_escape=True,
-        secret_key="NOTASECRET",
+        secret_key=DEFAULT_SECRET_KEY,
         enable_hsts=False,
         docs_route=None,
+        cors=False,
+        cors_params=DEFAULT_CORS_PARAMS
     ):
         self.secret_key = secret_key
         self.title = title
@@ -66,18 +74,22 @@ class API:
             os.path.abspath(os.path.dirname(__file__) + "/templates")
         )
         self.routes = {}
-        self.docs_theme = "swaggerui"
+        self.docs_theme = DEFAULT_API_THEME
         self.docs_route = docs_route
         self.schemas = {}
-        self.session_cookie = "Responder-Session"
+        self.session_cookie = DEFAULT_SESSION_COOKIE
 
         self.hsts_enabled = enable_hsts
+        self.cors = cors
+        self.cors_params = cors_params
+        # Make the static/templates directory if they don't exist.
+        for _dir in (self.static_dir, self.templates_dir):
+            os.makedirs(_dir, exist_ok=True)
 
         self.whitenoise = WhiteNoise(
             application=self._default_wsgi_app, index_file=True
         )
         self.whitenoise.add_files(str(self.static_dir))
-        import apistar
 
         self.whitenoise.add_files(
             (
@@ -90,10 +102,6 @@ class API:
 
         self.formats = get_formats()
 
-        # Make the static/templates directory if they don't exist.
-        for _dir in (self.static_dir, self.templates_dir):
-            os.makedirs(_dir, exist_ok=True)
-
         # Cached requests session.
         self._session = None
         self.background = BackgroundQueue()
@@ -109,9 +117,14 @@ class API:
         self.add_middleware(GZipMiddleware)
         if debug:
             self.add_middleware(DebugMiddleware)
+
         if self.hsts_enabled:
             self.add_middleware(HTTPSRedirectMiddleware)
 
+        if self.cors:
+            self.add_middleware(CORSMiddleware, **self.cors_params)
+        self.add_middleware(ExceptionMiddleware, debug=debug)
+
         # Jinja enviroment
         self.jinja_env = jinja2.Environment(
             loader=jinja2.FileSystemLoader(
@@ -275,6 +288,7 @@ class API:
                         cont = True
                 except Exception:
                     self.default_response(req, resp, error=True)
+                    raise
 
             elif route.is_class_based or cont:
                 try:
@@ -291,8 +305,9 @@ class API:
                     # If it's async, await it.
                     if hasattr(r, "send"):
                         await r
-                except Exception as e:
+                except Exception:
                     self.default_response(req, resp, error=True)
+                    raise
 
                 # Then on_get.
                 method = req.method
@@ -348,13 +363,6 @@ class API:
         if default:
             self.default_endpoint = endpoint
 
-        # Can we remove it ?
-        try:
-            if callable(endpoint):
-                endpoint.is_routed = True
-        except AttributeError:
-            pass
-
         self.routes[route] = Route(route, endpoint, websocket=websocket)
         # TODO: A better data structure or sort it once the app is loaded
         self.routes = dict(

responder/routes.py

@@ -15,7 +15,7 @@ def memoize(f):
 class Route:
     _param_pattern = re.compile(r"{([^{}]*)}")
 
-    def __init__(self, route, endpoint, websocket=False):
+    def __init__(self, route, endpoint, *, websocket=False):
         self.route = route
         self.endpoint = endpoint
         self.uses_websocket = websocket
@@ -72,11 +72,9 @@ class Route:
     @property
     def is_class_based(self):
         return hasattr(self.endpoint, "__class__")
-     
+
     @property
     def is_function(self):
-        # TODO: Should we remove is_routed ? 
-        routed = hasattr(self.endpoint, "is_routed")
         code = hasattr(self.endpoint, "__code__")
         kwdefaults = hasattr(self.endpoint, "__kwdefaults__")
         return all((callable(self.endpoint), code, kwdefaults))

responder/statics.py

@@ -1 +1,14 @@
 DEFAULT_ENCODING = "utf-8"
+DEFAULT_API_THEME = "swaggerui"
+DEFAULT_SESSION_COOKIE = "Responder-Session"
+DEFAULT_SECRET_KEY = "NOTASECRET"
+
+DEFAULT_CORS_PARAMS = {
+	"allow_origins": (),
+	"allow_methods": ("GET",),
+	"allow_headers": (),
+	"allow_credentials": False,
+	"allow_origin_regex": None,
+	"expose_headers": (),
+	"max_age": 600,
+}

setup.py

@@ -145,7 +145,7 @@ setup(
     include_package_data=True,
     license="Apache 2.0",
     classifiers=[
-        "License :: OSI Approved :: MIT License",
+        "License :: OSI Approved :: Apache Software License",
         "Programming Language :: Python",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.6",

static/index.html

@@ -1 +0,0 @@
-lorem

templates/test.html

@@ -1,3 +0,0 @@
-this is a test
-
-{{ api.static_url('test') }}

tests/test_responder.py

@@ -3,6 +3,8 @@ import yaml
 import responder
 import io
 
+from starlette.responses import PlainTextResponse
+
 
 def test_api_basic_route(api):
     @api.route("/")
@@ -355,6 +357,34 @@ def test_schema_generation():
     assert dump["openapi"] == "3.0"
 
 
+def test_documentation():
+    import responder
+    from marshmallow import Schema, fields
+
+    api = responder.API(title="Web Service", openapi="3.0", docs_route="/docs")
+
+    @api.schema("Pet")
+    class PetSchema(Schema):
+        name = fields.Str()
+
+    @api.route("/")
+    def route(req, resp):
+        """A cute furry animal endpoint.
+        ---
+        get:
+            description: Get a random pet
+            responses:
+                200:
+                    description: A pet to be returned
+                    schema:
+                        $ref = "#/components/schemas/Pet"
+        """
+        resp.media = PetSchema().dump({"name": "little orange"})
+
+    r = api.requests.get("/docs")
+    assert "html" in r.text
+
+
 def test_mount_wsgi_app(api, flask):
     @api.route("/")
     def hello(req, resp):
@@ -432,12 +462,18 @@ def test_file_uploads(api):
 
 
 def test_500(api):
+    def catcher(request, exc):
+        return PlainTextResponse("Suppressed error", 500)
+
+    api.app.add_exception_handler(ValueError, catcher)
+
     @api.route("/")
     def view(req, resp):
         raise ValueError
 
     r = api.requests.get(api.url_for(view))
     assert not r.ok
+    assert r.content == b'Suppressed error'
 
 
 def test_404(api):