corehttp 1.0.0b6__tar.gz → 1.0.0b7__tar.gz

{corehttp-1.0.0b6 → corehttp-1.0.0b7}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Release History
 
+## 1.0.0b7 (2026-02-05)
+
+### Features Added
+
+- Native tracing support was added. [#39172](https://github.com/Azure/azure-sdk-for-python/pull/39172)
+  - The `OpenTelemetryTracer` class was added to the `corehttp.instrumentation.tracing.opentelemetry` module. This is a wrapper around the OpenTelemetry tracer that is used to create spans for SDK operations.
+  - Added a `get_tracer` method to the new `corehttp.instrumentation` module. This method returns an instance of the `OpenTelemetryTracer` class if OpenTelemetry is available.
+  - A `TracingOptions` TypedDict class was added to define the options that SDK users can use to configure tracing per-operation. These options include the ability to enable or disable tracing and set additional attributes on spans.
+    - Example usage: `client.method(tracing_options={"enabled": True, "attributes": {"foo": "bar"}})`
+  - `DistributedHttpTracingPolicy` and `distributed_trace`/`distributed_trace_async` decorators were added to support OpenTelemetry tracing for SDK operations.
+    - SDK clients can define an `_instrumentation_config` class variable to configure the OpenTelemetry tracer used in method span creation. Possible configuration options are `library_name`, `library_version`, `schema_url`, and `attributes`.
+- Added a global settings object, `corehttp.settings`, to the `corehttp` package. This object can be used to set global settings for the `corehttp` package. Currently the only setting is `tracing_enabled` for enabling/disabling tracing. [#39172](https://github.com/Azure/azure-sdk-for-python/pull/39172)
+- Added `start_time` and `context` keyword arguments to `OpenTelemetryTracer.start_span` and `start_as_current_span` methods.
+- Added `set_span_error_status` static method to `OpenTelemetryTracer` for setting a span's status to ERROR.
+- Added `is_generated_model`, `attribute_list`, and `TypeHandlerRegistry` to `corehttp.serialization` module for SDK model handling.
+
+### Bugs Fixed
+
+- Fixed `retry_backoff_max` being ignored in retry policies when configuring retries.
+- Raise correct exception if transport is used while already closed.
+- A timeout error when using the `aiohttp` transport will now be raised as a `corehttp.exceptions.ServiceResponseTimeoutError`, a subtype of the previously raised `ServiceResponseError`.
+- When using with `aiohttp` 3.10 or later, a connection timeout error will now be raised as a `corehttp.exceptions.ServiceRequestTimeoutError`, which can be retried.
+- Fixed leaked requests and aiohttp exceptions for streamed responses.
+- Improved granularity of `ServiceRequestError` and `ServiceResponseError` exceptions raised in timeout scenarios from the requests and aiohttp transports.
+- `BearerTokenCredentialPolicy` and `AsyncBearerTokenCredentialPolicy` will now properly chain exceptions raised during claims challenge handling. If a credential raises an exception when attempting to acquire a token in response to a claims challenge, that exception will be raised with the original 401 response as the cause.
+
+### Other Changes
+
+- Added `opentelemetry-api` as an optional dependency for tracing. [#39172](https://github.com/Azure/azure-sdk-for-python/pull/39172)
+
 ## 1.0.0b6 (2025-03-27)
 
 ### Features Added

{corehttp-1.0.0b6/corehttp.egg-info → corehttp-1.0.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: corehttp
-Version: 1.0.0b6
+Version: 1.0.0b7
 Summary: CoreHTTP Library for Python
 Home-page: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/core/corehttp
 Author: Microsoft Corporation
@@ -11,13 +11,14 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: License :: OSI Approved :: MIT License
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4.6.0
@@ -27,6 +28,21 @@ Provides-Extra: aiohttp
 Requires-Dist: aiohttp>=3.0; extra == "aiohttp"
 Provides-Extra: httpx
 Requires-Dist: httpx>=0.25.0; extra == "httpx"
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-api~=1.26; extra == "tracing"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 
 # Core HTTP shared client library for Python
@@ -87,6 +103,36 @@ additional questions or comments.
 
 # Release History
 
+## 1.0.0b7 (2026-02-05)
+
+### Features Added
+
+- Native tracing support was added. [#39172](https://github.com/Azure/azure-sdk-for-python/pull/39172)
+  - The `OpenTelemetryTracer` class was added to the `corehttp.instrumentation.tracing.opentelemetry` module. This is a wrapper around the OpenTelemetry tracer that is used to create spans for SDK operations.
+  - Added a `get_tracer` method to the new `corehttp.instrumentation` module. This method returns an instance of the `OpenTelemetryTracer` class if OpenTelemetry is available.
+  - A `TracingOptions` TypedDict class was added to define the options that SDK users can use to configure tracing per-operation. These options include the ability to enable or disable tracing and set additional attributes on spans.
+    - Example usage: `client.method(tracing_options={"enabled": True, "attributes": {"foo": "bar"}})`
+  - `DistributedHttpTracingPolicy` and `distributed_trace`/`distributed_trace_async` decorators were added to support OpenTelemetry tracing for SDK operations.
+    - SDK clients can define an `_instrumentation_config` class variable to configure the OpenTelemetry tracer used in method span creation. Possible configuration options are `library_name`, `library_version`, `schema_url`, and `attributes`.
+- Added a global settings object, `corehttp.settings`, to the `corehttp` package. This object can be used to set global settings for the `corehttp` package. Currently the only setting is `tracing_enabled` for enabling/disabling tracing. [#39172](https://github.com/Azure/azure-sdk-for-python/pull/39172)
+- Added `start_time` and `context` keyword arguments to `OpenTelemetryTracer.start_span` and `start_as_current_span` methods.
+- Added `set_span_error_status` static method to `OpenTelemetryTracer` for setting a span's status to ERROR.
+- Added `is_generated_model`, `attribute_list`, and `TypeHandlerRegistry` to `corehttp.serialization` module for SDK model handling.
+
+### Bugs Fixed
+
+- Fixed `retry_backoff_max` being ignored in retry policies when configuring retries.
+- Raise correct exception if transport is used while already closed.
+- A timeout error when using the `aiohttp` transport will now be raised as a `corehttp.exceptions.ServiceResponseTimeoutError`, a subtype of the previously raised `ServiceResponseError`.
+- When using with `aiohttp` 3.10 or later, a connection timeout error will now be raised as a `corehttp.exceptions.ServiceRequestTimeoutError`, which can be retried.
+- Fixed leaked requests and aiohttp exceptions for streamed responses.
+- Improved granularity of `ServiceRequestError` and `ServiceResponseError` exceptions raised in timeout scenarios from the requests and aiohttp transports.
+- `BearerTokenCredentialPolicy` and `AsyncBearerTokenCredentialPolicy` will now properly chain exceptions raised during claims challenge handling. If a credential raises an exception when attempting to acquire a token in response to a claims challenge, that exception will be raised with the original 401 response as the cause.
+
+### Other Changes
+
+- Added `opentelemetry-api` as an optional dependency for tracing. [#39172](https://github.com/Azure/azure-sdk-for-python/pull/39172)
+
 ## 1.0.0b6 (2025-03-27)
 
 ### Features Added

{corehttp-1.0.0b6 → corehttp-1.0.0b7}/corehttp/_version.py

@@ -9,4 +9,4 @@
 # regenerated.
 # --------------------------------------------------------------------------
 
-VERSION = "1.0.0b6"
+VERSION = "1.0.0b7"

{corehttp-1.0.0b6 → corehttp-1.0.0b7}/corehttp/credentials.py

@@ -68,7 +68,11 @@ class TokenCredential(Protocol, ContextManager["TokenCredential"]):
         ...
 
     def close(self) -> None:
-        pass
+        """Close the credential, releasing any resources it holds.
+
+        :return: None
+        :rtype: None
+        """
 
 
 class ServiceNamedKey(NamedTuple):
@@ -93,7 +97,7 @@ class ServiceKeyCredential:
     It provides the ability to update the key without creating a new client.
 
     :param str key: The key used to authenticate to a service
-    :raises: TypeError
+    :raises TypeError: If the key is not a string.
     """
 
     def __init__(self, key: str) -> None:
@@ -117,7 +121,8 @@ class ServiceKeyCredential:
         to update long-lived clients.
 
         :param str key: The key used to authenticate to a service
-        :raises: ValueError or TypeError
+        :raises ValueError: If the key is None or empty.
+        :raises TypeError: If the key is not a string.
         """
         if not key:
             raise ValueError("The key used for updating can not be None or empty")
@@ -132,7 +137,7 @@ class ServiceNamedKeyCredential:
 
     :param str name: The name of the credential used to authenticate to a service.
     :param str key: The key used to authenticate to a service.
-    :raises: TypeError
+    :raises TypeError: If the name or key is not a string.
     """
 
     def __init__(self, name: str, key: str) -> None:
@@ -180,7 +185,11 @@ class AsyncTokenCredential(Protocol, AsyncContextManager["AsyncTokenCredential"]
         ...
 
     async def close(self) -> None:
-        pass
+        """Close the credential, releasing any resources.
+
+        :return: None
+        :rtype: None
+        """
 
     async def __aexit__(
         self,

corehttp-1.0.0b7/corehttp/instrumentation/__init__.py

@@ -0,0 +1,9 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from .tracing._tracer import get_tracer
+
+__all__ = [
+    "get_tracer",
+]

corehttp-1.0.0b7/corehttp/instrumentation/tracing/__init__.py

@@ -0,0 +1,14 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from ._models import SpanKind, Link, TracingOptions
+from ._decorator import distributed_trace, distributed_trace_async
+
+__all__ = [
+    "Link",
+    "SpanKind",
+    "TracingOptions",
+    "distributed_trace",
+    "distributed_trace_async",
+]

corehttp-1.0.0b7/corehttp/instrumentation/tracing/_decorator.py

@@ -0,0 +1,189 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+"""The decorator to apply if you want the given method traced."""
+from contextvars import ContextVar
+import functools
+from typing import Awaitable, Any, TypeVar, overload, Optional, Callable, TYPE_CHECKING
+from typing_extensions import ParamSpec
+
+from ._models import SpanKind
+from ._tracer import get_tracer
+from ...settings import settings
+
+if TYPE_CHECKING:
+    from ._models import TracingOptions
+
+
+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
+
+
+@overload
+def distributed_trace(**kwargs: Any) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    pass
+
+
+def distributed_trace(__func: Optional[Callable[P, T]] = None, **kwargs: Any) -> Any:  # pylint: disable=unused-argument
+    """Decorator to apply to an SDK method to have it traced automatically.
+
+    Span will use the method's qualified name.
+
+    Note: This decorator SHOULD NOT be used by application developers. It's intended to be called by client
+    libraries only. Application developers should use OpenTelemetry directly to instrument their applications.
+
+    :param callable __func: A function to decorate
+
+    :return: The decorated function
+    :rtype: Any
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+
+        @functools.wraps(func)
+        def wrapper_use_tracer(*args: Any, **kwargs: Any) -> T:
+            # If we are already in the span context of a decorated function, don't trace.
+            if _in_span_context.get():
+                return func(*args, **kwargs)
+
+            # This will be popped in the pipeline or transport runner.
+            tracing_options: TracingOptions = kwargs.get("tracing_options", {})
+
+            # User can explicitly disable tracing for this call
+            user_enabled = tracing_options.get("enabled")
+            if user_enabled is False:
+                return func(*args, **kwargs)
+
+            # If tracing is disabled globally and user didn't explicitly enable it, don't trace.
+            if not settings.tracing_enabled and user_enabled is None:
+                return func(*args, **kwargs)
+
+            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)
+
+            name = func.__qualname__
+            span_suppression_token = _in_span_context.set(True)
+            try:
+                with method_tracer.start_as_current_span(
+                    name=name,
+                    kind=SpanKind.INTERNAL,
+                    attributes=tracing_options.get("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)
+
+
+@overload
+def distributed_trace_async(__func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+    pass
+
+
+@overload
+def distributed_trace_async(**kwargs: Any) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
+    pass
+
+
+def distributed_trace_async(  # pylint: disable=unused-argument
+    __func: Optional[Callable[P, Awaitable[T]]] = None,
+    **kwargs: Any,
+) -> Any:
+    """Decorator to apply to an SDK method to have it traced automatically.
+
+    Span will use the method's qualified name.
+
+    Note: This decorator SHOULD NOT be used by application developers. It's intended to be called by client
+    libraries only. Application developers should use OpenTelemetry directly to instrument their applications.
+
+    :param callable __func: A function to decorate
+
+    :return: The decorated function
+    :rtype: Any
+    """
+
+    def decorator(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+
+        @functools.wraps(func)
+        async def wrapper_use_tracer(*args: Any, **kwargs: Any) -> T:
+            # 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)
+
+            # This will be popped in the pipeline or transport runner.
+            tracing_options: TracingOptions = kwargs.get("tracing_options", {})
+
+            # User can explicitly disable tracing for this call
+            user_enabled = tracing_options.get("enabled")
+            if user_enabled is False:
+                return await func(*args, **kwargs)
+
+            # If tracing is disabled globally and user didn't explicitly enable it, don't trace.
+            if not settings.tracing_enabled and user_enabled is None:
+                return await func(*args, **kwargs)
+
+            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 await func(*args, **kwargs)
+
+            name = func.__qualname__
+            span_suppression_token = _in_span_context.set(True)
+            try:
+                with method_tracer.start_as_current_span(
+                    name=name,
+                    kind=SpanKind.INTERNAL,
+                    attributes=tracing_options.get("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)

corehttp-1.0.0b7/corehttp/instrumentation/tracing/_models.py

@@ -0,0 +1,72 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from __future__ import annotations
+from enum import Enum
+from typing import Dict, Mapping, Optional, Union, Sequence, TypedDict
+
+from ...utils 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."""

corehttp-1.0.0b7/corehttp/instrumentation/tracing/_tracer.py

@@ -0,0 +1,69 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+from typing import Optional, Union, Mapping, TYPE_CHECKING
+from functools import lru_cache
+
+if TYPE_CHECKING:
+    try:
+        from .opentelemetry import OpenTelemetryTracer
+    except ImportError:
+        pass
+
+
+def _get_tracer_impl():
+    # Check if OpenTelemetry is available/installed.
+    try:
+        from .opentelemetry import OpenTelemetryTracer
+
+        return OpenTelemetryTracer
+    except ImportError:
+        return None
+
+
+@lru_cache
+def _get_tracer_cached(
+    library_name: Optional[str],
+    library_version: Optional[str],
+    schema_url: Optional[str],
+    attributes_key: Optional[frozenset],
+) -> Optional["OpenTelemetryTracer"]:
+    tracer_impl = _get_tracer_impl()
+    if tracer_impl:
+        # Convert attributes_key back to dict if needed
+        attributes = dict(attributes_key) if attributes_key else None
+        return tracer_impl(
+            library_name=library_name,
+            library_version=library_version,
+            schema_url=schema_url,
+            attributes=attributes,
+        )
+    return None
+
+
+def get_tracer(
+    *,
+    library_name: Optional[str] = None,
+    library_version: Optional[str] = None,
+    schema_url: Optional[str] = None,
+    attributes: Optional[Mapping[str, Union[str, bool, int, float]]] = None,
+) -> Optional["OpenTelemetryTracer"]:
+    """Get the OpenTelemetry tracer instance if available.
+
+    If OpenTelemetry is not available, this method will return None. This method caches
+    the tracer instance for each unique set of parameters.
+
+    :keyword library_name: The name of the library to use in the tracer.
+    :paramtype library_name: str
+    :keyword library_version: The version of the library to use in the tracer.
+    :paramtype library_version: str
+    :keyword schema_url: Specifies the Schema URL of the emitted spans.
+    :paramtype schema_url: str
+    :keyword attributes: Attributes to add to the emitted spans.
+    :paramtype attributes: Mapping[str, Union[str, bool, int, float]]
+    :return: The OpenTelemetry tracer instance if available.
+    :rtype: Optional[~corehttp.instrumentation.tracing.opentelemetry.OpenTelemetryTracer]
+    """
+    attributes_key = frozenset(attributes.items()) if attributes else None
+    return _get_tracer_cached(library_name, library_version, schema_url, attributes_key)