Problem: No easy way to create custom per-request context about graceful

[swistakm]

Idea - simply add context argument to every implementation of http method calls

Implementation:
Implementation would require modifying every HTTP method handler in the resource.mixins module. Example:

class ListMixin(BaseMixin):
    ...

    def on_get(self, req, resp, handler=None, **kwargs):
        kwargs['context'] = req.context

        self.handle(
            handler or self.list, req, resp, **kwargs
        )

As the effect developer may use three methods to provide custom per-request context variables:

• using HTTP method overrides

  class MyResource(ListAPI):
      def on_get(req, resp, **kwargs):
          req.context['session'] = Session()
          super().on_get(req, resp, **kwargs)
  
      def list(self, params, meta, context, **kwargs):
          # context object content available here
          ...

• using middleware

  class SessionMiddleware:
      def process_resource(self, req, resp, resource, params):
          req.context['session'] = Session()

• using hooks:

  def create_session(req, resp, resource, params):
      req.context['session'] = Session()
  
  @falcon.before(create_session)
  class MyResource(ListAPI):
      def on_get(req, resp, **kwargs):
          req.context['session'] = Session()
          super().on_get(req, resp, **kwargs)
  
      def list(self, params, meta, context, **kwargs):
          # context object content available here
          ...

Pros of this approach are:

• simple implementation
• low risk of breaking backwards incompatibility
• compatible with existing techniques of providing context in falcon
• compatible with any existing falcon extension built using hooks or middleware

Also if we improve support for falcon hooks (per-method falcon hooks with falcon.before) this solution will still work as expected.

Backward compatibility concerns:

Good practice is to allow passing any set of keyword arguments to resource manipulation methods using generic and basic resources in graceful. Anyway we cannot be sure that every developer uses this approach. We should expect that graceful users sometimes do following:

class MyResourceList(ListAPI):
    def list(params, meta):
        pass

# or

class MyResourceItem(RetrieveAPI):
    def retrieve(params, meta, object_id):  # <= object id from URI template
        pass

We could ensure backwards compatibility by using class keyword arguments:

class MyResourceItemWithCtx(RetrieveAPI, with_context=True):
    def retrieve(params, meta, context, **kwargs):
        pass

class MyResourceItemWithoutCtx(RetrieveAPI, with_context=False):
    def retrieve(params, meta, **kwargs):
        pass

This is feature of Python 3 but we do not target anything below Python 3.3. Of course default for with_context for 0.x branch would be False and for 1.x would be True