kinto 19.5.0__py3-none-any.whl → 19.6.0__py3-none-any.whl

kinto/core/cornice/renderer.py

@@ -0,0 +1,89 @@
+from pyramid import httpexceptions as exc
+from pyramid.renderers import JSON
+from pyramid.response import Response
+
+
+def bytes_adapter(obj, request):
+    """Convert bytes objects to strings for json error renderer."""
+    if isinstance(obj, bytes):
+        return obj.decode("utf8")
+    return obj
+
+
+class JSONError(exc.HTTPError):
+    def __init__(self, serializer, serializer_kw, errors, status=400):
+        body = {"status": "error", "errors": errors}
+        Response.__init__(self, serializer(body, **serializer_kw))
+        self.status = status
+        self.content_type = "application/json"
+
+
+class CorniceRenderer(JSON):
+    """We implement JSON serialization by extending Pyramid's default
+    JSON rendering machinery using our own custom Content-Type logic `[1]`_.
+
+    This allows developers to config the JSON renderer using Pyramid's
+    configuration machinery `[2]`_.
+
+      .. _`[1]`: https://github.com/mozilla-services/cornice/pull/116 \
+                 #issuecomment-14355865
+      .. _`[2]`: http://pyramid.readthedocs.io/en/latest/narr/renderers.html \
+                 #serializing-custom-objects
+    """
+
+    acceptable = ("application/json", "text/plain")
+
+    def __init__(self, *args, **kwargs):
+        """Adds a `bytes` adapter by default."""
+        super(CorniceRenderer, self).__init__(*args, **kwargs)
+        self.add_adapter(bytes, bytes_adapter)
+
+    def render_errors(self, request):
+        """Returns an HTTPError with the given status and message.
+
+        The HTTP error content type is "application/json"
+        """
+        default = self._make_default(request)
+        serializer_kw = self.kw.copy()
+        serializer_kw["default"] = default
+        return JSONError(
+            serializer=self.serializer,
+            serializer_kw=serializer_kw,
+            errors=request.errors,
+            status=request.errors.status,
+        )
+
+    def render(self, value, system):
+        """Extends the default `_render` function of the pyramid JSON renderer.
+
+        Compared to the default `pyramid.renderers.JSON` renderer:
+            1. Overrides the response with an empty string and
+               no Content-Type in case of HTTP 204.
+            2. Overrides the default behavior of Content-Type handling,
+               forcing the use of `acceptable_offers`, instead of letting
+               the user specify the Content-Type manually.
+               TODO: maybe explain this a little better
+        """
+        request = system.get("request")
+        if request is not None:
+            response = request.response
+
+            # Do not return content with ``204 No Content``
+            if response.status_code == 204:
+                response.content_type = None
+                return ""
+
+            ctypes = request.accept.acceptable_offers(offers=self.acceptable)
+            if not ctypes:
+                ctypes = [(self.acceptable[0], 1.0)]
+            response.content_type = ctypes[0][0]
+        default = self._make_default(request)
+        return self.serializer(value, default=default, **self.kw)
+
+    def __call__(self, info):
+        """Overrides the default behavior of `pyramid.renderers.JSON`.
+
+        Uses a public `render()` method instead of defining render inside
+        `__call__`, to let the user extend it if necessary.
+        """
+        return self.render

kinto/core/cornice/resource.py

@@ -0,0 +1,205 @@
+# -*- coding: utf-8 -*-
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+import functools
+import warnings
+
+import venusian
+
+from kinto.core.cornice import Service
+
+
+def resource(depth=2, **kw):
+    """Class decorator to declare resources.
+
+    All the methods of this class named by the name of HTTP resources
+    will be used as such. You can also prefix them by ``"collection_"`` and
+    they will be treated as HTTP methods for the given collection path
+    (collection_path), if any.
+
+    :param depth:
+        Which frame should be looked in default 2.
+
+    :param kw:
+        Keyword arguments configuring the resource.
+
+    Here is an example::
+
+        @resource(collection_path='/users', path='/users/{id}')
+    """
+
+    def wrapper(klass):
+        return add_resource(klass, depth, **kw)
+
+    return wrapper
+
+
+def add_resource(klass, depth=2, **kw):
+    """Function to declare resources of a Class.
+
+    All the methods of this class named by the name of HTTP resources
+    will be used as such. You can also prefix them by ``"collection_"`` and
+    they will be treated as HTTP methods for the given collection path
+    (collection_path), if any.
+
+    :param klass:
+        The class (resource) on which to register the service.
+
+    :param depth:
+        Which frame should be looked in default 2.
+
+    :param kw:
+        Keyword arguments configuring the resource.
+
+
+    Here is an example:
+
+    .. code-block:: python
+
+        class User(object):
+            pass
+
+        add_resource(User, collection_path='/users', path='/users/{id}')
+
+    Alternatively if you want to reuse your existing pyramid routes:
+
+    .. code-block:: python
+
+        class User(object):
+            pass
+
+        add_resource(User, collection_pyramid_route='users',
+            pyramid_route='user')
+
+    """
+
+    services = {}
+
+    if ("collection_pyramid_route" in kw or "pyramid_route" in kw) and (
+        "collection_path" in kw or "path" in kw
+    ):
+        raise ValueError("You use either paths or route names, not both")
+
+    if "collection_path" in kw:
+        if kw["collection_path"] == kw["path"]:
+            msg = "Warning: collection_path and path are not distinct."
+            warnings.warn(msg)
+
+        prefixes = ("", "collection_")
+    else:
+        prefixes = ("",)
+
+    if "collection_pyramid_route" in kw:
+        if kw["collection_pyramid_route"] == kw["pyramid_route"]:
+            msg = "Warning: collection_pyramid_route and pyramid_route are not distinct."
+            warnings.warn(msg)
+
+        prefixes = ("", "collection_")
+
+    for prefix in prefixes:
+        # get clean view arguments
+        service_args = {}
+        for k in list(kw):
+            if k.startswith("collection_"):
+                if prefix == "collection_":
+                    service_args[k[len(prefix) :]] = kw[k]
+            elif k not in service_args:
+                service_args[k] = kw[k]
+
+        # auto-wire klass as its own view factory, unless one
+        # is explicitly declared.
+        if "factory" not in kw:
+            service_args["factory"] = klass
+
+        # create service
+        service_name = service_args.pop("name", None) or klass.__name__.lower()
+        service_name = prefix + service_name
+        service = services[service_name] = Service(name=service_name, depth=depth, **service_args)
+        # ensure the service comes with the same properties as the wrapped
+        # resource
+        functools.update_wrapper(service, klass)
+
+        # initialize views
+        for verb in ("get", "post", "put", "delete", "options", "patch"):
+            view_attr = prefix + verb
+            meth = getattr(klass, view_attr, None)
+
+            if meth is not None:
+                # if the method has a __views__ arguments, then it had
+                # been decorated by a @view decorator. get back the name of
+                # the decorated method so we can register it properly
+                views = getattr(meth, "__views__", [])
+                if views:
+                    for view_args in views:
+                        service.add_view(verb, view_attr, klass=klass, **view_args)
+                else:
+                    service.add_view(verb, view_attr, klass=klass)
+
+    setattr(klass, "_services", services)
+
+    def callback(context, name, ob):
+        # get the callbacks registered by the inner services
+        # and call them from here when the @resource classes are being
+        # scanned by venusian.
+        for service in services.values():
+            config = context.config.with_package(info.module)
+            config.add_cornice_service(service)
+
+    info = venusian.attach(klass, callback, category="pyramid", depth=depth)
+
+    return klass
+
+
+def view(**kw):
+    """Method decorator to store view arguments when defining a resource with
+    the @resource class decorator
+
+    :param kw:
+        Keyword arguments configuring the view.
+    """
+
+    def wrapper(func):
+        return add_view(func, **kw)
+
+    return wrapper
+
+
+def add_view(func, **kw):
+    """Method to store view arguments when defining a resource with
+    the add_resource class method
+
+    :param func:
+        The func to hook to
+
+    :param kw:
+        Keyword arguments configuring the view.
+
+    Example:
+
+    .. code-block:: python
+
+        class User(object):
+
+            def __init__(self, request):
+                self.request = request
+
+            def collection_get(self):
+                return {'users': _USERS.keys()}
+
+            def get(self):
+                return _USERS.get(int(self.request.matchdict['id']))
+
+        add_view(User.get, renderer='json')
+        add_resource(User, collection_path='/users', path='/users/{id}')
+    """
+    # XXX needed in py2 to set on instancemethod
+    if hasattr(func, "__func__"):  # pragma: no cover
+        func = func.__func__
+    # store view argument to use them later in @resource
+    views = getattr(func, "__views__", None)
+    if views is None:
+        views = []
+        setattr(func, "__views__", views)
+    views.append(kw)
+    return func