Skip to content
This repository has been archived by the owner on May 23, 2023. It is now read-only.

Commit

Permalink
Fix some v2.0.0 docs (#82)
Browse files Browse the repository at this point in the history
* Lint doc line lengths.
* More formatting.
* Apply a similar formatting as the requests library.
  • Loading branch information
Kyle-Verhoog authored and carlosalberto committed Jun 14, 2018
1 parent 306aff6 commit cb3eb7b
Show file tree
Hide file tree
Showing 8 changed files with 270 additions and 192 deletions.
4 changes: 2 additions & 2 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ History
1.2.1 (2016-09-22)
------------------

- Make Span.log(self, **kwargs) smarter
- Make Span.log(self, \**kwargs) smarter


1.2.0 (2016-09-21)
Expand Down Expand Up @@ -115,7 +115,7 @@ History
------------------

- Change inheritance to match api-go: TraceContextSource extends codecs,
Tracer extends TraceContextSource
Tracer extends TraceContextSource
- Create API harness


Expand Down
2 changes: 1 addition & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@

html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']
html_static_path = []
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

intersphinx_mapping = {
Expand Down
8 changes: 4 additions & 4 deletions opentracing/ext/scope.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,16 +31,16 @@ def __init__(self, manager, span, finish_on_close):
"""Initialize a `Scope` for the given `Span` object.
:param span: the `Span` wrapped by this `Scope`.
:param finish_on_close: whether span should automatically be
finished when `Scope#close()` is called.
:param finish_on_close: whether :class:`Span` should automatically be
finished when :meth:`Scope.close()` is called.
"""
super(ThreadLocalScope, self).__init__(manager, span)
self._finish_on_close = finish_on_close
self._to_restore = manager.active

def close(self):
"""Mark the end of the active period for this {@link Scope},
updating ScopeManager#active in the process.
"""Mark the end of the active period for this :class:`Scope`,
updating :attr:`ScopeManager.active` in the process.
"""
if self.manager.active is not self:
return
Expand Down
46 changes: 23 additions & 23 deletions opentracing/propagation.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@

class UnsupportedFormatException(Exception):
"""UnsupportedFormatException should be used when the provided format
value is unknown or disallowed by the Tracer.
value is unknown or disallowed by the :class:`Tracer`.
See Tracer.inject() and Tracer.extract().
See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
"""
pass

Expand All @@ -34,25 +34,25 @@ class InvalidCarrierException(Exception):
"""InvalidCarrierException should be used when the provided carrier
instance does not match what the `format` argument requires.
See Tracer.inject() and Tracer.extract().
See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
"""
pass


class SpanContextCorruptedException(Exception):
"""SpanContextCorruptedException should be used when the underlying span
context state is seemingly present but not well-formed.
"""SpanContextCorruptedException should be used when the underlying
:class:`SpanContext` state is seemingly present but not well-formed.
See Tracer.inject() and Tracer.extract().
See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
"""
pass


class Format(object):
"""A namespace for builtin carrier formats.
These static constants are intended for use in the Tracer.inject() and
Tracer.extract() methods. E.g.::
These static constants are intended for use in the :meth:`Tracer.inject()`
and :meth:`Tracer.extract()` methods. E.g.::
tracer.inject(span.context, Format.BINARY, binary_carrier)
Expand All @@ -62,38 +62,38 @@ class Format(object):
"""
The BINARY format represents SpanContexts in an opaque bytearray carrier.
For both Tracer.inject() and Tracer.extract() the carrier should be a
bytearray instance. Tracer.inject() must append to the bytearray carrier
(rather than replace its contents).
For both :meth:`Tracer.inject()` and :meth:`Tracer.extract()` the carrier
should be a bytearray instance. :meth:`Tracer.inject()` must append to the
bytearray carrier (rather than replace its contents).
"""

TEXT_MAP = 'text_map'
"""
The TEXT_MAP format represents SpanContexts in a python dict mapping from
strings to strings.
The TEXT_MAP format represents :class:`SpanContext`\ s in a python ``dict``
mapping from strings to strings.
Both the keys and the values have unrestricted character sets (unlike the
HTTP_HEADERS format).
NOTE: The TEXT_MAP carrier dict may contain unrelated data (e.g.,
arbitrary gRPC metadata). As such, the Tracer implementation should use a
prefix or other convention to distinguish Tracer-specific key:value
pairs.
NOTE: The TEXT_MAP carrier ``dict`` may contain unrelated data (e.g.,
arbitrary gRPC metadata). As such, the :class:`Tracer` implementation
should use a prefix or other convention to distinguish tracer-specific
key:value pairs.
"""

HTTP_HEADERS = 'http_headers'
"""
The HTTP_HEADERS format represents SpanContexts in a python dict mapping
from character-restricted strings to strings.
The HTTP_HEADERS format represents :class:`SpanContext`\ s in a python
``dict`` mapping from character-restricted strings to strings.
Keys and values in the HTTP_HEADERS carrier must be suitable for use as
HTTP headers (without modification or further escaping). That is, the
keys have a greatly restricted character set, casing for the keys may not
be preserved by various intermediaries, and the values should be
URL-escaped.
NOTE: The HTTP_HEADERS carrier dict may contain unrelated data (e.g.,
arbitrary gRPC metadata). As such, the Tracer implementation should use a
prefix or other convention to distinguish Tracer-specific key:value
pairs.
NOTE: The HTTP_HEADERS carrier ``dict`` may contain unrelated data (e.g.,
arbitrary gRPC metadata). As such, the :class:`Tracer` implementation
should use a prefix or other convention to distinguish tracer-specific
key:value pairs.
"""
44 changes: 26 additions & 18 deletions opentracing/scope.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,38 +22,46 @@


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
`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.
"""A scope formalizes the activation and deactivation of a :class:`Span`,
usually from a CPU standpoint. Many times a :class:`Span` will be extant
(in that :meth:`Span.finish()` has not been called) despite being in a
non-runnable state from a CPU/scheduler standpoint. For instance, a
:class:`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 :class:`Span` is scheduled and on the path.
:param manager: the :class:`ScopeManager` that created this :class:`Scope`.
:type manager: ScopeManager
:param span: the :class:`Span` used for this :class:`Scope`.
:type span: Span
"""
def __init__(self, manager, span):
"""Initializes a `Scope` for the given `Span` object.
:param manager: the `ScopeManager` that created this `Scope`
:param span: the `Span` used for this `Scope`
"""
"""Initializes a scope for *span*."""
self._manager = manager
self._span = span

@property
def span(self):
"""Returns the `Span` wrapped by this `Scope`."""
"""Returns the :class:`Span` wrapped by this :class:`Scope`.
:rtype: Span
"""
return self._span

@property
def manager(self):
"""Returns the `ScopeManager` that created this `Scope`."""
"""Returns the :class:`ScopeManager` that created this :class:`Scope`.
:rtype: ScopeManager
"""
return self._manager

def close(self):
"""Marks the end of the active period for this `Scope`,
updating `ScopeManager#active` in the process.
"""Marks the end of the active period for this :class:`Scope`, updating
:attr:`ScopeManager.active` in the process.
NOTE: Calling `close()` more than once on a single `Scope` instance
NOTE: Calling this method more than once on a single :class:`Scope`
leads to undefined behavior.
"""
pass
Expand All @@ -63,7 +71,7 @@ def __enter__(self):
return self

def __exit__(self, exc_type, exc_val, exc_tb):
"""Calls `close()` when the execution is outside the Python
"""Calls :meth:`close()` when the execution is outside the Python
Context Manager.
"""
self.close()
34 changes: 18 additions & 16 deletions opentracing/scope_manager.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,8 @@


class ScopeManager(object):
"""The `ScopeManager` interface abstracts both the activation of `Span`
instances (via `ScopeManager#activate(span, finish_on_close)`) and
access to an active `Span` / `Scope` (via `ScopeManager#active`).
"""The :class:`ScopeManager` interface abstracts both the activation of
a :class:`Span` and access to an active :class:`Span`/:class:`Scope`.
"""
def __init__(self):
# TODO: `tracer` should not be None, but we don't have a reference;
Expand All @@ -37,27 +36,30 @@ def __init__(self):
self._noop_scope = Scope(self, self._noop_span)

def activate(self, span, finish_on_close):
"""Makes a `Span` instance active.
"""Makes a :class:`Span` active.
:param span: the `Span` that should become active.
:param finish_on_close: whether span should be automatically
finished when `Scope#close()` is called.
:param span: the :class:`Span` that should become active.
:param finish_on_close: whether :class:`Span` should be automatically
finished when :meth:`Scope.close()` is called.
:return: a `Scope` instance to control the end of the active period for
the `Span`. It is a programming error to neglect to call
`Scope#close()` on the returned instance.
:rtype: Scope
:return: a :class:`Scope` to control the end of the active period for
*span*. It is a programming error to neglect to call
:meth:`Scope.close()` on the returned instance.
"""
return self._noop_scope

@property
def active(self):
"""Returns the currently active `Scope` which can be used to access the
currently active `Scope#span`.
"""Returns the currently active :class:`Scope` which can be used to access the
currently active :attr:`Scope.span`.
If there is a non-null `Scope`, its wrapped `Span` becomes an implicit
parent of any newly-created `Span` at `Tracer#start_active_span()`
time.
If there is a non-null :class:`Scope`, its wrapped :class:`Span`
becomes an implicit parent of any newly-created :class:`Span` at
:meth:`Tracer.start_active_span()` time.
:return: the `Scope` that is active, or `None` if not available.
:rtype: Scope
:return: the :class:`Scope` that is active, or ``None`` if not
available.
"""
return self._noop_scope

0 comments on commit cb3eb7b

Please sign in to comment.