context: graduate-oslo-context

Change-Id: I077f5c7047b589e5ca239d8f87f1e6d0b1a85038

specs/kilo/graduate-oslo-context.rst

@@ -0,0 +1,141 @@
+=========================
+ Graduating oslo.context
+=========================
+
+https://blueprints.launchpad.net/oslo-incubator/+spec/graduate-oslo-context
+
+oslo.context holds the context base class, which defines APIs used by
+oslo.messaging and oslo.log.
+
+Library Name
+============
+
+What is the name of the new library?: oslo.context
+
+Contents
+========
+
+- openstack/common/context.py
+- tests/unit/test_context.py
+
+Early Adopters
+==============
+
+- oslo.log
+- oslo.messaging
+
+Public API
+==========
+
+::
+
+  import oslo_context
+
+.. The package name will depend on the outcome of our discussion about
+   namespace packages.
+
+All of the existing public functions and classes will remain public.
+
+::
+
+  def generate_request_id():
+      "Return a unique request identifier."
+
+  class RequestContext(object):
+
+      """Helper class to represent useful information about a request context.
+
+      Stores information about the security context under which the user
+      accesses the system, as well as additional request information.
+      """
+
+  def get_admin_context(show_deleted=False):
+      "Return a RequestContext configured as an admin user"
+
+  def get_context_from_function_and_args(function, args, kwargs):
+      """Find an arg of type RequestContext and return it.
+
+         This is useful in a couple of decorators where we don't
+         know much about the function we're wrapping.
+      """
+
+  def is_user_context(context):
+      """Indicates if the request context is a normal user."""
+
+A private registry of context objects will be kept using a
+threading.local() instance and logic based on
+nova.context.RequestContext. A new public API for accessing the
+context will be added:
+
+::
+
+    def get_current():
+        "Return this thread's current context"
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  doug-hellmann
+
+Other contributors:
+  None
+
+Primary Maintainer
+------------------
+
+Primary Maintainer:
+  Unknown
+
+Other Contributors:
+  None
+
+Security Contact
+----------------
+
+Security Contact:
+  doug-hellmann
+
+Milestones
+----------
+
+Target Milestone for completion: kilo-1
+
+Work Items
+----------
+
+- https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary#Checklist
+- Add registry management logic.
+- We will evolve the API for RequestContext after exporting it, based
+  on needs for oslo.messaging and oslo.log. Those changes have not yet
+  been worked out, and will come in another spec.
+
+Adoption Notes
+==============
+
+Projects using oslo.context should subclass
+oslo_context.RequestContext and create their own application-specific
+context class.
+
+Dependencies
+============
+
+None
+
+References
+==========
+
+- https://etherpad.openstack.org/p/kilo-oslo-library-proposals
+- https://blueprints.launchpad.net/oslo.log/+spec/remove-context-adapter
+- https://blueprints.launchpad.net/oslo.log/+spec/app-agnostic-logging-parameters
+
+.. note::
+
+  This work is licensed under a Creative Commons Attribution 3.0
+  Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode
+