updating docstrings and tests

opentracing/harness/api_check.py

@@ -47,21 +47,21 @@ def check_baggage_values(self):
 
     def check_scope_manager(self):
         """If true, the test suite will validate the `ScopeManager` propagation
-        and storage to ensure the correct parenting and active `Scope` are
-        properly defined by the implementation. If false, it will only use
-        the API without any assert. The latter mode is only useful for no-op
-        tracer.
+        to ensure correct parenting. If false, it will only use the API without
+        asserting. The latter mode is only useful for no-op tracer.
         """
         return True
 
     def is_parent(self, parent, span):
         """Utility method that must be defined by Tracer implementers to define
         how the test suite can check when a `Span` is a parent of another one.
+        It depends by the underlying implementation that is not part of the
+        OpenTracing API.
         """
         return False
 
     def test_start_span(self):
-        # test for deprecated API
+        # test deprecated API for minor compatibility
         tracer = self.tracer()
         span = tracer.start_span(operation_name='Fry')
         span.finish()
@@ -320,7 +320,7 @@ def test_tracer_start_active_nesting(self):
         # when a Scope is closed, the previous one must be activated
         tracer = self.tracer()
         with tracer.start_active(operation_name='Fry') as parent:
-            with tracer.start_active(operation_name='Fry'):
+            with tracer.start_active(operation_name='Farnsworth'):
                 pass
 
             if self.check_scope_manager():
@@ -335,7 +335,7 @@ def test_tracer_start_active_nesting_finish_on_close(self):
         parent = tracer.start_active(operation_name='Fry',
                                      finish_on_close=False)
         with mock.patch.object(parent.span(), 'finish') as finish:
-            with tracer.start_active(operation_name='Fry'):
+            with tracer.start_active(operation_name='Farnsworth'):
                 pass
             parent.close()
 
@@ -348,7 +348,7 @@ def test_tracer_start_active_wrong_close_order(self):
         # only the active `Scope` can be closed
         tracer = self.tracer()
         parent = tracer.start_active(operation_name='Fry')
-        child = tracer.start_active(operation_name='Fry')
+        child = tracer.start_active(operation_name='Farnsworth')
         parent.close()
 
         if self.check_scope_manager():

opentracing/scope.py

@@ -22,19 +22,18 @@
 
 
 class Scope(object):
-    """
-    A `Scope` formalizes the activation and deactivation of a `Span`, usually
-    from a CPU standpoint. Many times a `Span` will be extant (in that
+    """A `Scope` formalizes the activation and deactivation of a `Span`,
+    usually from a CPU standpoint. Many times a `Span` will be extant (in that
     `Span#finish()` has not been called) despite being in a non-runnable state
     from a CPU/scheduler standpoint. For instance, a `Span` representing the
     client side of an RPC will be unfinished but blocked on IO while the RPC is
     still outstanding. A `Scope` defines when a given `Span` is scheduled
     and on the path.
     """
     def __init__(self, manager, span, finish_on_close=True):
-        """
-        Initialize a `Scope` for the given `Span` object
+        """Initialize a `Scope` for the given `Span` object
 
+        :param manager: the `ScopeManager` that created this `Scope`
         :param span: the `Span` used for this `Scope`
         :param finish_on_close: whether span should automatically be
             finished when `Scope#close()` is called
@@ -43,14 +42,11 @@ def __init__(self, manager, span, finish_on_close=True):
         self._span = span
 
     def span(self):
-        """
-        Return the `Span` that's been scoped by this `Scope`.
-        """
+        """Return the `Span` that's been scoped by this `Scope`."""
         return self._span
 
     def close(self):
-        """
-        Mark the end of the active period for the current thread and `Scope`,
+        """Mark the end of the active period for the current thread and `Scope`,
         updating the `ScopeManager#active()` in the process.
 
         NOTE: Calling `close()` more than once on a single `Scope` instance
@@ -59,14 +55,11 @@ def close(self):
         pass
 
     def __enter__(self):
-        """
-        Allow `Scope` to be used inside a Python Context Manager.
-        """
+        """Allow `Scope` to be used inside a Python Context Manager."""
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        """
-        Call `close()` when the execution is outside the Python
+        """Call `close()` when the execution is outside the Python
         Context Manager.
         """
         self.close()

opentracing/scope_manager.py

@@ -25,8 +25,7 @@
 
 
 class ScopeManager(object):
-    """
-    The `ScopeManager` interface abstracts both the activation of `Span`
+    """The `ScopeManager` interface abstracts both the activation of `Span`
     instances (via `ScopeManager#activate(Span)`) and access to an active
     `Span` / `Scope` (via `ScopeManager#active()`).
     """
@@ -38,8 +37,7 @@ def __init__(self):
         self._noop_scope = Scope(self, self._noop_span)
 
     def activate(self, span, finish_on_close=True):
-        """
-        Make a `Span` instance active.
+        """Make a `Span` instance active.
 
         :param span: the `Span` that should become active
         :param finish_on_close: whether span should automatically be

opentracing/tracer.py

@@ -47,7 +47,7 @@ def __init__(self):
 
     @property
     def scope_manager(self):
-        """Accessor for `ScopeManager`."""
+        """ScopeManager accessor"""
         return self._scope_manager
 
     def start_active(self,
@@ -58,10 +58,8 @@ def start_active(self,
                      start_time=None,
                      ignore_active_scope=False,
                      finish_on_close=True):
-        """
-        Returns a newly started and activated `Scope`.
-
-        The returned `Scope` supports with-statement contexts. For example:
+        """Returns a newly started and activated `Scope`.
+        Returned `Scope` supports with-statement contexts. For example:
 
             with tracer.start_active('...') as scope:
                 scope.span().set_tag('http.method', 'GET')
@@ -91,7 +89,7 @@ def start_active(self,
         :param start_time: an explicit Span start time as a unix timestamp per
             time.time().
         :param ignore_active_scope: an explicit flag that ignores the current
-            active `Span` and creates a root `Span`.
+            active `Scope` and creates a root `Span`.
         :param finish_on_close: whether span should automatically be finished
             when `Scope#close()` is called.
 
@@ -142,7 +140,7 @@ def start_manual(self,
         :param start_time: an explicit Span start time as a unix timestamp per
             time.time()
         :param ignore_active_scope: an explicit flag that ignores the current
-            active `Span` and creates a root `Span`.
+            active `Scope` and creates a root `Span`.
 
         :return: Returns an already-started Span instance.
         """

tests/test_scope.py

@@ -32,7 +32,6 @@ def test_scope_wrapper():
     # ensure `Scope` wraps the `Span` argument
     span = Span(tracer=Tracer(), context=SpanContext())
     scope = Scope(ScopeManager, span, finish_on_close=False)
-    assert scope._span == span
     assert scope.span() == span
 
 
@@ -45,10 +44,3 @@ def test_scope_context_manager():
         with scope:
             pass
         assert close.call_count == 1
-
-
-def test_scope_close():
-    # ensure `Scope` can be closed
-    span = Span(tracer=Tracer(), context=SpanContext())
-    scope = Scope(ScopeManager(), span)
-    scope.close()

tests/test_scope_manager.py

@@ -26,8 +26,7 @@
 
 
 def test_scope_manager():
-    # ensure the activation returns the noop `Scope`
-    # that is always active
+    # ensure the activation returns the noop `Scope` that is always active
     scope_manager = ScopeManager()
     span = Span(tracer=Tracer(), context=SpanContext())
     scope = scope_manager.activate(span)