Update opentelemetry-instrumentation/src/opentelemetry/instrumentatio…

…n/propagators.py

Co-authored-by: Aaron Abbott <aaronabbott@google.com>

opentelemetry-instrumentation/src/opentelemetry/instrumentation/propagators.py

@@ -13,8 +13,8 @@
 # limitations under the License.
 
 """
-This module implements experimental propagators to inject trace response context
-into HTTP responses. This is useful for server side frameworks that start traces
+This module implements experimental propagators to inject trace context
+into response carriers. This is useful for server side frameworks that start traces
 when server requests and want to share the trace context with the client so the
 client can add it's spans to the same trace.
 
@@ -44,25 +44,48 @@ def set_global_response_propagator(propagator):
     _RESPONSE_PROPAGATOR = propagator
 
 
-class DictHeaderSetter:
+class Setter(ABC):
+
+    @abstractmethod
+    def set(self, carrier, key, value):
+        """Inject the provided key value pair in carrier."""
+
+
+class DictHeaderSetter(Setter):
     def set(self, carrier, key, value):  # pylint: disable=no-self-use
         old_value = carrier.get(key, "")
         if old_value:
             value = "{0}, {1}".format(old_value, value)
         carrier[key] = value
 
 
-default_setter = DictHeaderSetter()
+class FuncSetter:
+    '''FuncSetter coverts a function into a valid Setter. Any function that can
+    set values in a carrier can be converted into a Setter by using FuncSetter.
+    This is useful when injecting trace context into non-dict objects such
+    HTTP Response objects for different framework.
+    
+    For example, it can be used to create a setter for Falcon response object as:
 
+        setter = FuncSetter(falcon.api.Response.append_header)
+
+    and then used with the propagator as:
+
+        propagator.inject(falcon_response, setter=setter)
+
+    This would essentially make the propagator call `falcon_response.append_header(key, value)`
+    '''
 
-class FuncSetter:
     def __init__(self, func):
         self._func = func
 
     def set(self, carrier, key, value):
         self._func(carrier, key, value)
 
 
+default_setter = DictHeaderSetter()
+
+
 class ResponsePropagator(ABC):
     @abstractmethod
     def inject(
@@ -100,5 +123,7 @@ def inject(
             ),
         )
         setter.set(
-            carrier, _HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS, header_name,
+            carrier,
+            _HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS,
+            header_name,
         )