py2docfx 0.1.16rc2051518__py3-none-any.whl → 0.1.17__py3-none-any.whl

py2docfx/venv/venv1/Lib/site-packages/azure/core/rest/_rest_py3.py

@@ -303,7 +303,7 @@ class _HttpResponseBase(abc.ABC):
 
         :return: The JSON deserialized response body
         :rtype: any
-        :raises json.decoder.JSONDecodeError or ValueError (in python 2.7) if object is not JSON decodable:
+        :raises json.decoder.JSONDecodeError: if the body is not valid JSON.
         """
 
     @abc.abstractmethod
@@ -312,7 +312,7 @@ class _HttpResponseBase(abc.ABC):
 
         If response is good, does nothing.
 
-        :raises ~azure.core.HttpResponseError if the object has an error status code.:
+        :raises ~azure.core.HttpResponseError: if the object has an error status code.
         """
 
 

py2docfx/venv/venv1/Lib/site-packages/azure/core/settings.py

@@ -30,7 +30,6 @@ from collections import namedtuple
 from enum import Enum
 import logging
 import os
-import sys
 from typing import (
     Type,
     Optional,
@@ -43,10 +42,13 @@ from typing import (
     Generic,
     Mapping,
     List,
+    TYPE_CHECKING,
 )
-from azure.core.tracing import AbstractSpan
 from ._azure_clouds import AzureClouds
 
+if TYPE_CHECKING:
+    from azure.core.tracing import AbstractSpan
+
 ValidInputType = TypeVar("ValidInputType")
 ValueType = TypeVar("ValueType")
 
@@ -88,6 +90,24 @@ def convert_bool(value: Union[str, bool]) -> bool:
     raise ValueError("Cannot convert {} to boolean value".format(value))
 
 
+def convert_tracing_enabled(value: Optional[Union[str, bool]]) -> bool:
+    """Convert tracing value to bool with regard to tracing implementation.
+
+    :param value: the value to convert
+    :type value: str or bool or None
+    :returns: A boolean value matching the intent of the input
+    :rtype: bool
+    :raises ValueError: If conversion to bool fails
+    """
+    if value is None:
+        # If tracing_enabled was not explicitly set to a boolean, determine tracing enablement
+        # based on tracing_implementation being set.
+        if settings.tracing_implementation():
+            return True
+        return False
+    return convert_bool(value)
+
+
 _levels = {
     "CRITICAL": logging.CRITICAL,
     "ERROR": logging.ERROR,
@@ -181,18 +201,6 @@ def _get_opentelemetry_span() -> Optional[Type[AbstractSpan]]:
         return None
 
 
-def _get_opencensus_span_if_opencensus_is_imported() -> Optional[Type[AbstractSpan]]:
-    if "opencensus" not in sys.modules:
-        return None
-    return _get_opencensus_span()
-
-
-def _get_opentelemetry_span_if_opentelemetry_is_imported() -> Optional[Type[AbstractSpan]]:
-    if "opentelemetry" not in sys.modules:
-        return None
-    return _get_opentelemetry_span()
-
-
 _tracing_implementation_dict: Dict[str, Callable[[], Optional[Type[AbstractSpan]]]] = {
     "opencensus": _get_opencensus_span,
     "opentelemetry": _get_opentelemetry_span,
@@ -215,9 +223,7 @@ def convert_tracing_impl(value: Optional[Union[str, Type[AbstractSpan]]]) -> Opt
 
     """
     if value is None:
-        return (
-            _get_opentelemetry_span_if_opentelemetry_is_imported() or _get_opencensus_span_if_opencensus_is_imported()
-        )
+        return None
 
     if not isinstance(value, str):
         return value
@@ -299,7 +305,7 @@ class PrioritizedSetting(Generic[ValidInputType, ValueType]):
         :type value: str or int or float or None
         :returns: the value of the setting
         :rtype: str or int or float
-        :raises: RuntimeError if no value can be determined
+        :raises RuntimeError: if no value can be determined
         """
 
         # 4. immediate values
@@ -501,11 +507,11 @@ class Settings:
         default=logging.INFO,
     )
 
-    tracing_enabled: PrioritizedSetting[Union[str, bool], bool] = PrioritizedSetting(
+    tracing_enabled: PrioritizedSetting[Optional[Union[str, bool]], bool] = PrioritizedSetting(
         "tracing_enabled",
         env_var="AZURE_TRACING_ENABLED",
-        convert=convert_bool,
-        default=False,
+        convert=convert_tracing_enabled,
+        default=None,
     )
 
     tracing_implementation: PrioritizedSetting[

py2docfx/venv/venv1/Lib/site-packages/azure/core/tracing/__init__.py

@@ -2,11 +2,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-from azure.core.tracing._abstract_span import (
-    AbstractSpan,
-    SpanKind,
-    HttpSpanMixin,
-    Link,
-)
+from ._abstract_span import AbstractSpan, HttpSpanMixin
+from ._models import Link, SpanKind, TracingOptions
 
-__all__ = ["AbstractSpan", "SpanKind", "HttpSpanMixin", "Link"]
+__all__ = ["AbstractSpan", "HttpSpanMixin", "Link", "SpanKind", "TracingOptions"]

py2docfx/venv/venv1/Lib/site-packages/azure/core/tracing/_abstract_span.py

@@ -4,12 +4,10 @@
 # ------------------------------------
 """Protocol that defines what functions wrappers of tracing libraries should implement."""
 from __future__ import annotations
-from enum import Enum
 from urllib.parse import urlparse
 
 from typing import (
     Any,
-    Sequence,
     Optional,
     Union,
     Callable,
@@ -26,33 +24,16 @@ from azure.core.rest import (
     AsyncHttpResponse as AsyncRestHttpResponse,
     HttpRequest as RestHttpRequest,
 )
+from ._models import AttributeValue, SpanKind
+
 
 HttpResponseType = Union[HttpResponse, AsyncHttpResponse, RestHttpResponse, AsyncRestHttpResponse]
 HttpRequestType = Union[HttpRequest, RestHttpRequest]
 
-AttributeValue = Union[
-    str,
-    bool,
-    int,
-    float,
-    Sequence[str],
-    Sequence[bool],
-    Sequence[int],
-    Sequence[float],
-]
 Attributes = Dict[str, AttributeValue]
 SpanType = TypeVar("SpanType")
 
 
-class SpanKind(Enum):
-    UNSPECIFIED = 1
-    SERVER = 2
-    CLIENT = 3
-    PRODUCER = 4
-    CONSUMER = 5
-    INTERNAL = 6
-
-
 @runtime_checkable
 class AbstractSpan(Protocol, Generic[SpanType]):
     """Wraps a span from a distributed tracing implementation.
@@ -305,17 +286,3 @@ class HttpSpanMixin:
         else:
             self.add_attribute(HttpSpanMixin._HTTP_STATUS_CODE, 504)
             self.add_attribute(HttpSpanMixin._ERROR_TYPE, "504")
-
-
-class Link:
-    """
-    This is a wrapper class to link the context to the current tracer.
-    :param headers: A dictionary of the request header as key value pairs.
-    :type headers: dict
-    :param attributes: Any additional attributes that should be added to link
-    :type attributes: dict
-    """
-
-    def __init__(self, headers: Dict[str, str], attributes: Optional[Attributes] = None) -> None:
-        self.headers = headers
-        self.attributes = attributes

py2docfx/venv/venv1/Lib/site-packages/azure/core/tracing/_models.py

@@ -0,0 +1,71 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from enum import Enum
+from typing import Dict, Mapping, Optional, Union, Sequence, TypedDict
+
+from .._enum_meta import CaseInsensitiveEnumMeta
+
+
+AttributeValue = Union[
+    str,
+    bool,
+    int,
+    float,
+    Sequence[str],
+    Sequence[bool],
+    Sequence[int],
+    Sequence[float],
+]
+Attributes = Mapping[str, AttributeValue]
+
+
+class SpanKind(Enum, metaclass=CaseInsensitiveEnumMeta):
+    """Describes the role or kind of a span within a distributed trace.
+
+    This helps to categorize spans based on their relationship to other spans and the type
+    of operation they represent.
+    """
+
+    UNSPECIFIED = 1
+    """Unspecified span kind."""
+
+    SERVER = 2
+    """Indicates that the span describes an operation that handles a remote request."""
+
+    CLIENT = 3
+    """Indicates that the span describes a request to some remote service."""
+
+    PRODUCER = 4
+    """Indicates that the span describes the initiation or scheduling of a local or remote operation."""
+
+    CONSUMER = 5
+    """Indicates that the span represents the processing of an operation initiated by a producer."""
+
+    INTERNAL = 6
+    """Indicates that the span is used internally in the application."""
+
+
+class Link:
+    """Represents a reference from one span to another span.
+
+    :param headers: A dictionary of the request header as key value pairs.
+    :type headers: dict
+    :param attributes: Any additional attributes that should be added to link
+    :type attributes: dict
+    """
+
+    def __init__(self, headers: Dict[str, str], attributes: Optional[Attributes] = None) -> None:
+        self.headers = headers
+        self.attributes = attributes
+
+
+class TracingOptions(TypedDict, total=False):
+    """Options to configure tracing behavior for operations."""
+
+    enabled: bool
+    """Whether tracing is enabled for the operation. By default, if the global setting is enabled, tracing is
+    enabled for all operations. This option can be used to override the global setting for a specific operation."""
+    attributes: Attributes
+    """Attributes to include in the spans emitted for the operation."""

py2docfx/venv/venv1/Lib/site-packages/azure/core/tracing/common.py

@@ -29,6 +29,7 @@ from typing import Any, Optional, Callable, Type, Generator
 import warnings
 
 from ._abstract_span import AbstractSpan
+from ..instrumentation import get_tracer
 from ..settings import settings
 
 
@@ -72,10 +73,11 @@ def change_context(span: Optional[AbstractSpan]) -> Generator:
     :rtype: contextmanager
     :return: A context manager that will run the given span in the new context
     """
-    span_impl_type: Optional[Type[AbstractSpan]] = settings.tracing_implementation()
+    span_impl_type = settings.tracing_implementation()
     if span_impl_type is None or span is None:
         yield
     else:
+
         try:
             with span_impl_type.change_context(span):
                 yield
@@ -101,8 +103,14 @@ def with_current_context(func: Callable) -> Any:
     :return: The func wrapped with correct context
     :rtype: callable
     """
-    span_impl_type: Optional[Type[AbstractSpan]] = settings.tracing_implementation()
-    if span_impl_type is None:
+    if not settings.tracing_enabled():
         return func
 
-    return span_impl_type.with_current_context(func)
+    span_impl_type: Optional[Type[AbstractSpan]] = settings.tracing_implementation()
+    if span_impl_type:
+        return span_impl_type.with_current_context(func)
+
+    tracer = get_tracer()
+    if not tracer:
+        return func
+    return tracer.with_current_context(func)

py2docfx/venv/venv1/Lib/site-packages/azure/core/tracing/decorator.py

@@ -24,22 +24,28 @@
 #
 # --------------------------------------------------------------------------
 """The decorator to apply if you want the given function traced."""
-
+from contextvars import ContextVar
 import functools
 
 from typing import Callable, Any, TypeVar, overload, Optional, Mapping, TYPE_CHECKING
 from typing_extensions import ParamSpec
-from .common import change_context, get_function_and_class_name
-from . import SpanKind as _SpanKind
+from .common import change_context
 from ..settings import settings
+from ..instrumentation import get_tracer as _get_tracer
+from ._models import SpanKind as _SpanKind
 
 if TYPE_CHECKING:
-    from azure.core.tracing import SpanKind
+    from azure.core.tracing import TracingOptions, SpanKind
+
 
 P = ParamSpec("P")
 T = TypeVar("T")
 
 
+# This context variable is used to determine if we are already in the span context of a decorated function.
+_in_span_context = ContextVar("in_span_context", default=False)
+
+
 @overload
 def distributed_trace(__func: Callable[P, T]) -> Callable[P, T]:
     pass
@@ -97,24 +103,71 @@ def distributed_trace(
             merge_span = kwargs.pop("merge_span", False)
             passed_in_parent = kwargs.pop("parent_span", None)
 
-            # Assume this will be popped in DistributedTracingPolicy.
-            func_tracing_attributes = kwargs.pop("tracing_attributes", tracing_attributes)
+            # If we are already in the span context of a decorated function, don't trace.
+            if _in_span_context.get():
+                return func(*args, **kwargs)
 
-            span_impl_type = settings.tracing_implementation()
-            if span_impl_type is None:
+            # This will be popped in the pipeline or transport runner.
+            tracing_options: TracingOptions = kwargs.get("tracing_options", {})
+            tracing_enabled = settings.tracing_enabled()
+
+            # User can explicitly disable tracing for this request.
+            user_enabled = tracing_options.get("enabled")
+
+            # If tracing is disabled globally and user didn't explicitly enable it, don't trace.
+            if user_enabled is False or (not tracing_enabled and user_enabled is None):
                 return func(*args, **kwargs)
 
             # Merge span is parameter is set, but only if no explicit parent are passed
             if merge_span and not passed_in_parent:
                 return func(*args, **kwargs)
 
-            with change_context(passed_in_parent):
-                name = name_of_span or get_function_and_class_name(func, *args)
-                with span_impl_type(name=name, kind=kind) as span:
-                    for key, value in func_tracing_attributes.items():
-                        span.add_attribute(key, value)
+            # Assume this will be popped in DistributedTracingPolicy.
+            func_tracing_attributes = kwargs.get("tracing_attributes", tracing_attributes)
+            span_attributes = {**func_tracing_attributes, **tracing_options.get("attributes", {})}
+
+            span_impl_type = settings.tracing_implementation()
+
+            name = name_of_span or func.__qualname__
+            if span_impl_type:
+                # Plugin path
+                with change_context(passed_in_parent):
+                    with span_impl_type(name=name, kind=kind) as span:
+                        for key, value in span_attributes.items():
+                            span.add_attribute(key, value)  # type: ignore
+                        return func(*args, **kwargs)
+            else:
+                # Native path
+                config = {}
+                if args and hasattr(args[0], "_instrumentation_config"):
+                    config = args[0]._instrumentation_config  # pylint: disable=protected-access
+                method_tracer = _get_tracer(
+                    library_name=config.get("library_name"),
+                    library_version=config.get("library_version"),
+                    schema_url=config.get("schema_url"),
+                    attributes=config.get("attributes"),
+                )
+                if not method_tracer:
                     return func(*args, **kwargs)
 
+                span_suppression_token = _in_span_context.set(True)
+                try:
+                    with method_tracer.start_as_current_span(
+                        name=name,
+                        kind=kind,
+                        attributes=span_attributes,
+                    ) as span:
+                        try:
+                            return func(*args, **kwargs)
+                        except Exception as err:  # pylint: disable=broad-except
+                            ex_type = type(err)
+                            module = ex_type.__module__ if ex_type.__module__ != "builtins" else ""
+                            error_type = f"{module}.{ex_type.__qualname__}" if module else ex_type.__qualname__
+                            span.set_attribute("error.type", error_type)
+                            raise
+                finally:
+                    _in_span_context.reset(span_suppression_token)
+
         return wrapper_use_tracer
 
     return decorator if __func is None else decorator(__func)

py2docfx/venv/venv1/Lib/site-packages/azure/core/tracing/decorator_async.py

@@ -24,31 +24,28 @@
 #
 # --------------------------------------------------------------------------
 """The decorator to apply if you want the given function traced."""
-
+from contextvars import ContextVar
 import functools
 
-from typing import (
-    Awaitable,
-    Callable,
-    Any,
-    TypeVar,
-    overload,
-    Optional,
-    Mapping,
-    TYPE_CHECKING,
-)
+from typing import Awaitable, Callable, Any, TypeVar, overload, Optional, Mapping, TYPE_CHECKING
 from typing_extensions import ParamSpec
-from .common import change_context, get_function_and_class_name
-from . import SpanKind as _SpanKind
+from .common import change_context
+from ._models import SpanKind as _SpanKind
+from ..instrumentation import get_tracer as _get_tracer
 from ..settings import settings
 
 if TYPE_CHECKING:
-    from azure.core.tracing import SpanKind
+    from azure.core.tracing import TracingOptions, SpanKind
+
 
 P = ParamSpec("P")
 T = TypeVar("T")
 
 
+# This context variable is used to determine if we are already in the span context of a decorated function.
+_in_span_context = ContextVar("in_span_context", default=False)
+
+
 @overload
 def distributed_trace_async(__func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
     pass
@@ -106,24 +103,66 @@ def distributed_trace_async(  # pylint: disable=unused-argument
             merge_span = kwargs.pop("merge_span", False)
             passed_in_parent = kwargs.pop("parent_span", None)
 
-            # Assume this will be popped in DistributedTracingPolicy.
-            func_tracing_attributes = kwargs.get("tracing_attributes", tracing_attributes)
+            # If we are already in the span context of a decorated function, don't trace.
+            if _in_span_context.get():
+                return await func(*args, **kwargs)
 
-            span_impl_type = settings.tracing_implementation()
-            if span_impl_type is None:
+            # This will be popped in the pipeline or transport runner.
+            tracing_options: TracingOptions = kwargs.get("tracing_options", {})
+            tracing_enabled = settings.tracing_enabled()
+
+            # User can explicitly disable tracing for this request.
+            user_enabled = tracing_options.get("enabled")
+
+            # If tracing is disabled globally and user didn't explicitly enable it, don't trace.
+            if user_enabled is False or (not tracing_enabled and user_enabled is None):
                 return await func(*args, **kwargs)
 
             # Merge span is parameter is set, but only if no explicit parent are passed
             if merge_span and not passed_in_parent:
                 return await func(*args, **kwargs)
 
-            with change_context(passed_in_parent):
-                name = name_of_span or get_function_and_class_name(func, *args)
-                with span_impl_type(name=name, kind=kind) as span:
-                    for key, value in func_tracing_attributes.items():
-                        span.add_attribute(key, value)
+            # Assume this will be popped in DistributedTracingPolicy.
+            func_tracing_attributes = kwargs.get("tracing_attributes", tracing_attributes)
+            span_attributes = {**func_tracing_attributes, **tracing_options.get("attributes", {})}
+
+            span_impl_type = settings.tracing_implementation()
+
+            name = name_of_span or func.__qualname__
+            if span_impl_type:
+                # Plugin path
+                with change_context(passed_in_parent):
+                    with span_impl_type(name=name, kind=kind) as span:
+                        for key, value in span_attributes.items():
+                            span.add_attribute(key, value)  # type: ignore
+                        return await func(*args, **kwargs)
+            else:
+                # Native path
+                config = {}
+                if args and hasattr(args[0], "_instrumentation_config"):
+                    config = args[0]._instrumentation_config  # pylint: disable=protected-access
+                method_tracer = _get_tracer(**config)
+                if not method_tracer:
                     return await func(*args, **kwargs)
 
+                span_suppression_token = _in_span_context.set(True)
+                try:
+                    with method_tracer.start_as_current_span(
+                        name=name,
+                        kind=kind,
+                        attributes=span_attributes,
+                    ) as span:
+                        try:
+                            return await func(*args, **kwargs)
+                        except Exception as err:  # pylint: disable=broad-except
+                            ex_type = type(err)
+                            module = ex_type.__module__ if ex_type.__module__ != "builtins" else ""
+                            error_type = f"{module}.{ex_type.__qualname__}" if module else ex_type.__qualname__
+                            span.set_attribute("error.type", error_type)
+                            raise
+                finally:
+                    _in_span_context.reset(span_suppression_token)
+
         return wrapper_use_tracer
 
     return decorator if __func is None else decorator(__func)