corehttp 1.0.0b6__py3-none-any.whl → 1.0.0b7__py3-none-any.whl

corehttp/instrumentation/tracing/utils.py

@@ -0,0 +1,31 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+"""Common tracing functionality for SDK libraries."""
+from typing import Any, Callable
+
+from ._tracer import get_tracer
+from ...settings import settings
+
+
+__all__ = [
+    "with_current_context",
+]
+
+
+def with_current_context(func: Callable) -> Any:
+    """Passes the current spans to the new context the function will be run in.
+
+    :param func: The function that will be run in the new context
+    :type func: callable
+    :return: The func wrapped with correct context
+    :rtype: callable
+    """
+    if not settings.tracing_enabled:
+        return func
+
+    tracer = get_tracer()
+    if not tracer:
+        return func
+    return tracer.with_current_context(func)

corehttp/paging.py

@@ -80,6 +80,13 @@ class PageIterator(Iterator[Iterator[ReturnType]]):
         return self
 
     def __next__(self) -> Iterator[ReturnType]:
+        """Get the next page in the iterator.
+
+        :returns: An iterator of objects in the next page.
+        :rtype: iterator[ReturnType]
+        :raises StopIteration: If there are no more pages to return.
+        :raises ~corehttp.exceptions.BaseError: If the request to get the next page fails.
+        """
         if self.continuation_token is None and self._did_a_call_already:
             raise StopIteration("End of paging")
         try:
@@ -129,6 +136,12 @@ class ItemPaged(Iterator[ReturnType]):
         return self
 
     def __next__(self) -> ReturnType:
+        """Get the next item in the iterator.
+
+        :returns: The next item in the iterator.
+        :rtype: ReturnType
+        :raises StopIteration: If there are no more items to return.
+        """
         if self._page_iterator is None:
             self._page_iterator = itertools.chain.from_iterable(self.by_page())
         return next(self._page_iterator)

corehttp/rest/_aiohttp.py

@@ -38,6 +38,7 @@ from ..exceptions import (
     ServiceRequestError,
     ServiceResponseError,
     IncompleteReadError,
+    ServiceResponseTimeoutError,
 )
 from ..runtime.pipeline import AsyncPipeline
 from ..transport._base_async import _ResponseStopIteration
@@ -224,7 +225,18 @@ class RestAioHttpTransportResponse(AsyncHttpResponseImpl):
         """
         if not self._content:
             self._stream_download_check()
-            self._content = await self._internal_response.read()
+            try:
+                self._content = await self._internal_response.read()
+            except aiohttp.client_exceptions.ClientPayloadError as err:
+                # This is the case that server closes connection before we finish the reading. aiohttp library
+                # raises ClientPayloadError.
+                raise IncompleteReadError(err, error=err) from err
+            except aiohttp.client_exceptions.ClientResponseError as err:
+                raise ServiceResponseError(err, error=err) from err
+            except asyncio.TimeoutError as err:
+                raise ServiceResponseTimeoutError(err, error=err) from err
+            except aiohttp.client_exceptions.ClientError as err:
+                raise ServiceRequestError(err, error=err) from err
         await self._set_read_checks()
         return _aiohttp_content_helper(self)
 
@@ -300,16 +312,16 @@ class AioHttpStreamDownloadGenerator(collections.abc.AsyncIterator):
         except aiohttp.client_exceptions.ClientPayloadError as err:
             # This is the case that server closes connection before we finish the reading. aiohttp library
             # raises ClientPayloadError.
-            _LOGGER.warning("Incomplete download: %s", err)
+            _LOGGER.warning("Incomplete download.")
             internal_response.close()
             raise IncompleteReadError(err, error=err) from err
         except aiohttp.client_exceptions.ClientResponseError as err:
             raise ServiceResponseError(err, error=err) from err
         except asyncio.TimeoutError as err:
-            raise ServiceResponseError(err, error=err) from err
+            raise ServiceResponseTimeoutError(err, error=err) from err
         except aiohttp.client_exceptions.ClientError as err:
             raise ServiceRequestError(err, error=err) from err
-        except Exception as err:
-            _LOGGER.warning("Unable to stream download: %s", err)
+        except Exception:
+            _LOGGER.warning("Unable to stream download.")
             internal_response.close()
             raise

corehttp/rest/_http_response_impl.py

@@ -54,7 +54,7 @@ class _HttpResponseBaseImpl(_HttpResponseBase):  # pylint: disable=too-many-inst
     :type request: ~corehttp.rest.HttpRequest
     :keyword any internal_response: The response we get directly from the transport. For example, for our requests
      transport, this will be a requests.Response.
-    :keyword optional[int] block_size: The block size we are using in our transport
+    :keyword Optional[int] block_size: The block size we are using in our transport
     :keyword int status_code: The status code of the response
     :keyword str reason: The HTTP reason
     :keyword str content_type: The content type of the response
@@ -136,7 +136,7 @@ class _HttpResponseBaseImpl(_HttpResponseBase):  # pylint: disable=too-many-inst
     def content_type(self) -> Optional[str]:
         """The content type of the response.
 
-        :rtype: optional[str]
+        :rtype: Optional[str]
         :return: The content type of the response.
         """
         return self._content_type
@@ -157,7 +157,7 @@ class _HttpResponseBaseImpl(_HttpResponseBase):  # pylint: disable=too-many-inst
         :return: The response encoding. We either return the encoding set by the user,
          or try extracting the encoding from the response's content type. If all fails,
          we return `None`.
-        :rtype: optional[str]
+        :rtype: Optional[str]
         """
         try:
             return self._encoding
@@ -166,10 +166,10 @@ class _HttpResponseBaseImpl(_HttpResponseBase):  # pylint: disable=too-many-inst
             return self._encoding
 
     @encoding.setter
-    def encoding(self, value: str) -> None:
+    def encoding(self, value: Optional[str]) -> None:
         """Sets the response encoding.
 
-        :param str value: Sets the response encoding.
+        :param Optional[str] value: Sets the response encoding.
         """
         self._encoding = value
         self._text = None  # clear text cache
@@ -178,7 +178,7 @@ class _HttpResponseBaseImpl(_HttpResponseBase):  # pylint: disable=too-many-inst
     def text(self, encoding: Optional[str] = None) -> str:
         """Returns the response body as a string
 
-        :param optional[str] encoding: The encoding you want to decode the text with. Can
+        :param Optional[str] encoding: The encoding you want to decode the text with. Can
          also be set independently through our encoding property
         :return: The response's content decoded as a string.
         :rtype: str
@@ -246,7 +246,7 @@ class HttpResponseImpl(_HttpResponseBaseImpl, _HttpResponse):
     :type request: ~corehttp.rest.HttpRequest
     :keyword any internal_response: The response we get directly from the transport. For example, for our requests
      transport, this will be a requests.Response.
-    :keyword optional[int] block_size: The block size we are using in our transport
+    :keyword Optional[int] block_size: The block size we are using in our transport
     :keyword int status_code: The status code of the response
     :keyword str reason: The HTTP reason
     :keyword str content_type: The content type of the response

corehttp/rest/_http_response_impl_async.py

@@ -69,6 +69,7 @@ class AsyncHttpResponseImpl(_HttpResponseBaseImpl, _AsyncHttpResponse):
 
     async def iter_raw(self, **kwargs: Any) -> AsyncIterator[bytes]:
         """Asynchronously iterates over the response's bytes. Will not decompress in the process
+
         :return: An async iterator of bytes from the response
         :rtype: AsyncIterator[bytes]
         """
@@ -79,6 +80,7 @@ class AsyncHttpResponseImpl(_HttpResponseBaseImpl, _AsyncHttpResponse):
 
     async def iter_bytes(self, **kwargs: Any) -> AsyncIterator[bytes]:
         """Asynchronously iterates over the response's bytes. Will decompress in the process
+
         :return: An async iterator of bytes from the response
         :rtype: AsyncIterator[bytes]
         """

corehttp/rest/_httpx.py

@@ -96,10 +96,10 @@ class HttpXStreamDownloadGenerator:
         except httpx.RemoteProtocolError as ex:
             msg = ex.__str__()
             if "complete message" in msg:
-                _LOGGER.warning("Incomplete download: %s", ex)
+                _LOGGER.warning("Incomplete download.")
                 internal_response.close()
                 raise IncompleteReadError(ex, error=ex) from ex
-            _LOGGER.warning("Unable to stream download: %s", ex)
+            _LOGGER.warning("Unable to stream download.")
             internal_response.close()
             raise HttpResponseError(ex, error=ex) from ex
         except httpx.DecodingError as ex:
@@ -108,8 +108,8 @@ class HttpXStreamDownloadGenerator:
             raise DecodeError("Failed to decode.", error=ex) from ex
         except httpx.RequestError as err:
             raise ServiceRequestError(err, error=err) from err
-        except Exception as err:
-            _LOGGER.warning("Unable to stream download: %s", err)
+        except Exception:
+            _LOGGER.warning("Unable to stream download.")
             internal_response.close()
             raise
 
@@ -186,10 +186,10 @@ class AsyncHttpXStreamDownloadGenerator(AsyncIterator):
         except httpx.RemoteProtocolError as ex:
             msg = ex.__str__()
             if "complete message" in msg:
-                _LOGGER.warning("Incomplete download: %s", ex)
+                _LOGGER.warning("Incomplete download.")
                 await internal_response.aclose()
                 raise IncompleteReadError(ex, error=ex) from ex
-            _LOGGER.warning("Unable to stream download: %s", ex)
+            _LOGGER.warning("Unable to stream download.")
             await internal_response.aclose()
             raise HttpResponseError(ex, error=ex) from ex
         except httpx.DecodingError as ex:
@@ -198,7 +198,7 @@ class AsyncHttpXStreamDownloadGenerator(AsyncIterator):
             raise DecodeError("Failed to decode.", error=ex) from ex
         except httpx.RequestError as err:
             raise ServiceRequestError(err, error=err) from err
-        except Exception as err:
-            _LOGGER.warning("Unable to stream download: %s", err)
+        except Exception:
+            _LOGGER.warning("Unable to stream download.")
             await internal_response.aclose()
             raise

corehttp/rest/_requests_basic.py

@@ -38,8 +38,8 @@ from urllib3.exceptions import (
 from ..runtime.pipeline import Pipeline
 from ._http_response_impl import _HttpResponseBaseImpl, HttpResponseImpl
 from ..exceptions import (
-    ServiceRequestError,
     ServiceResponseError,
+    ServiceResponseTimeoutError,
     IncompleteReadError,
     HttpResponseError,
     DecodeError,
@@ -156,14 +156,22 @@ class StreamDownloadGenerator:
         except requests.exceptions.ChunkedEncodingError as err:
             msg = err.__str__()
             if "IncompleteRead" in msg:
-                _LOGGER.warning("Incomplete download: %s", err)
+                _LOGGER.warning("Incomplete download.")
                 internal_response.close()
                 raise IncompleteReadError(err, error=err) from err
-            _LOGGER.warning("Unable to stream download: %s", err)
+            _LOGGER.warning("Unable to stream download.")
             internal_response.close()
             raise HttpResponseError(err, error=err) from err
+        except requests.ConnectionError as err:
+            internal_response.close()
+            if err.args and isinstance(err.args[0], ReadTimeoutError):
+                raise ServiceResponseTimeoutError(err, error=err) from err
+            raise ServiceResponseError(err, error=err) from err
+        except requests.RequestException as err:
+            internal_response.close()
+            raise ServiceResponseError(err, error=err) from err
         except Exception as err:
-            _LOGGER.warning("Unable to stream download: %s", err)
+            _LOGGER.warning("Unable to stream download.")
             internal_response.close()
             raise
 
@@ -178,7 +186,7 @@ def _read_raw_stream(response, chunk_size=1):
         except CoreDecodeError as e:
             raise DecodeError(e, error=e) from e
         except ReadTimeoutError as e:
-            raise ServiceRequestError(e, error=e) from e
+            raise ServiceResponseTimeoutError(e, error=e) from e
     else:
         # Standard file-like object.
         while True:

corehttp/rest/_rest_py3.py

@@ -300,7 +300,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
@@ -309,7 +309,7 @@ class _HttpResponseBase(abc.ABC):
 
         If response is good, does nothing.
 
-        :raises ~corehttp.HttpResponseError if the object has an error status code.:
+        :raises ~corehttp.HttpResponseError: if the object has an error status code.
         """
 
 

corehttp/runtime/pipeline/__init__.py

@@ -97,7 +97,7 @@ class PipelineContext(Dict[str, Any]):
     def clear(self) -> None:  # pylint: disable=docstring-missing-return, docstring-missing-rtype
         """Context objects cannot be cleared.
 
-        :raises: TypeError
+        :raises TypeError: If context objects cannot be cleared.
         """
         raise TypeError("Context objects cannot be cleared.")
 
@@ -106,7 +106,7 @@ class PipelineContext(Dict[str, Any]):
     ) -> None:
         """Context objects cannot be updated.
 
-        :raises: TypeError
+        :raises TypeError: If context objects cannot be updated.
         """
         raise TypeError("Context objects cannot be updated.")
 

corehttp/runtime/pipeline/_base.py

@@ -34,7 +34,7 @@ from . import (
     PipelineContext,
 )
 from ..policies import HTTPPolicy, SansIOHTTPPolicy
-from ._tools import await_result as _await_result
+from ._tools import sanitize_transport_options, await_result as _await_result
 from ...transport import HttpTransport
 
 HTTPResponseType = TypeVar("HTTPResponseType")
@@ -103,6 +103,7 @@ class _TransportRunner(HTTPPolicy[HTTPRequestType, HTTPResponseType]):
         :return: The PipelineResponse object.
         :rtype: ~corehttp.runtime.pipeline.PipelineResponse
         """
+        sanitize_transport_options(request.context.options)
         return PipelineResponse(
             request.http_request,
             self._sender.send(request.http_request, **request.context.options),

corehttp/runtime/pipeline/_base_async.py

@@ -33,6 +33,7 @@ from . import PipelineRequest, PipelineResponse, PipelineContext
 from ..policies import AsyncHTTPPolicy, SansIOHTTPPolicy
 from ..pipeline._base import is_sansio_http_policy
 from ._tools_async import await_result as _await_result
+from ._tools import sanitize_transport_options
 from ...transport import AsyncHttpTransport
 
 AsyncHTTPResponseType = TypeVar("AsyncHTTPResponseType")
@@ -97,6 +98,7 @@ class _AsyncTransportRunner(AsyncHTTPPolicy[HTTPRequestType, AsyncHTTPResponseTy
         :return: The PipelineResponse object.
         :rtype: ~corehttp.runtime.pipeline.PipelineResponse
         """
+        sanitize_transport_options(request.context.options)
         return PipelineResponse(
             request.http_request,
             await self._sender.send(request.http_request, **request.context.options),

corehttp/runtime/pipeline/_tools.py

@@ -23,7 +23,7 @@
 # IN THE SOFTWARE.
 #
 # --------------------------------------------------------------------------
-from typing import Callable, TypeVar
+from typing import Callable, TypeVar, Dict
 from typing_extensions import ParamSpec
 
 P = ParamSpec("P")
@@ -39,9 +39,25 @@ def await_result(func: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> T:
     :type args: list
     :rtype: any
     :return: The result of the function
-    :raises: TypeError
+    :raises TypeError: If the function returns an awaitable object.
     """
     result = func(*args, **kwargs)
     if hasattr(result, "__await__"):
         raise TypeError("Policy {} returned awaitable object in non-async pipeline.".format(func))
     return result
+
+
+def sanitize_transport_options(options: Dict[str, str]) -> None:
+    """Remove options that could potentially make it to the transport layer.
+
+    - "tracing_options" is used in the DistributedHttpTracingPolicy and tracing decorators
+
+    :param options: The options.
+    :type options: dict
+    """
+    if not options:
+        return
+
+    options_to_remove = ["tracing_options"]
+    for key in options_to_remove:
+        options.pop(key, None)

corehttp/runtime/policies/__init__.py

@@ -29,6 +29,7 @@ from ._authentication import (
     BearerTokenCredentialPolicy,
     ServiceKeyCredentialPolicy,
 )
+from ._distributed_tracing import DistributedHttpTracingPolicy
 from ._retry import RetryPolicy, RetryMode
 from ._universal import (
     HeadersPolicy,
@@ -57,4 +58,5 @@ __all__ = [
     "AsyncHTTPPolicy",
     "AsyncBearerTokenCredentialPolicy",
     "AsyncRetryPolicy",
+    "DistributedHttpTracingPolicy",
 ]

corehttp/runtime/policies/_authentication.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Optional, TypeVar, MutableMapping, Any, Union
 from ...credentials import TokenRequestOptions
 from ...rest import HttpResponse, HttpRequest
 from . import HTTPPolicy, SansIOHTTPPolicy
-from ...exceptions import ServiceRequestError
+from ...exceptions import ServiceRequestError, HttpResponseError
 
 if TYPE_CHECKING:
 
@@ -93,7 +93,7 @@ class BearerTokenCredentialPolicy(_BearerTokenCredentialPolicyBase, HTTPPolicy[H
     :param str scopes: Lets you specify the type of access needed.
     :keyword auth_flows: A list of authentication flows to use for the credential.
     :paramtype auth_flows: list[dict[str, Union[str, list[dict[str, str]]]]]
-    :raises: :class:`~corehttp.exceptions.ServiceRequestError`
+    :raises ~corehttp.exceptions.ServiceRequestError: If the request fails.
     """
 
     def on_request(
@@ -110,6 +110,9 @@ class BearerTokenCredentialPolicy(_BearerTokenCredentialPolicyBase, HTTPPolicy[H
         :keyword auth_flows: A list of authentication flows to use for the credential.
         :paramtype auth_flows: list[dict[str, Union[str, list[dict[str, str]]]]]
         """
+        # If auth_flows is an empty list, we should not attempt to authorize the request.
+        if auth_flows is not None and len(auth_flows) == 0:
+            return
         self._enforce_https(request)
 
         if self._token is None or self._need_new_token:
@@ -142,7 +145,9 @@ class BearerTokenCredentialPolicy(_BearerTokenCredentialPolicyBase, HTTPPolicy[H
         :return: The pipeline response object
         :rtype: ~corehttp.runtime.pipeline.PipelineResponse
         """
-        self.on_request(request, auth_flows=self._auth_flows)
+        op_auth_flows = request.context.options.pop("auth_flows", None)
+        auth_flows = op_auth_flows if op_auth_flows is not None else self._auth_flows
+        self.on_request(request, auth_flows=auth_flows)
         try:
             response = self.next.send(request)
         except Exception:
@@ -153,7 +158,19 @@ class BearerTokenCredentialPolicy(_BearerTokenCredentialPolicyBase, HTTPPolicy[H
         if response.http_response.status_code == 401:
             self._token = None  # any cached token is invalid
             if "WWW-Authenticate" in response.http_response.headers:
-                request_authorized = self.on_challenge(request, response)
+                try:
+                    request_authorized = self.on_challenge(request, response)
+                except Exception as ex:
+                    # If the response is streamed, read it so the error message is immediately available to the user.
+                    # Otherwise, a generic error message will be given and the user will have to read the response
+                    # body to see the actual error.
+                    if response.context.options.get("stream"):
+                        try:
+                            response.http_response.read()  # type: ignore
+                        except Exception:  # pylint:disable=broad-except
+                            pass
+                    # Raise the exception from the token request with the original 401 response.
+                    raise ex from HttpResponseError(response=response.http_response)
                 if request_authorized:
                     try:
                         response = self.next.send(request)
@@ -210,7 +227,8 @@ class ServiceKeyCredentialPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseT
     :type credential: ~corehttp.credentials.ServiceKeyCredential
     :param str name: The name of the key header used for the credential.
     :keyword str prefix: The name of the prefix for the header value if any.
-    :raises: ValueError or TypeError
+    :raises ValueError: if name is None or empty.
+    :raises TypeError: if name is not a string or if credential is not an instance of ServiceKeyCredential.
     """
 
     def __init__(  # pylint: disable=unused-argument
@@ -233,4 +251,9 @@ class ServiceKeyCredentialPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseT
         self._prefix = prefix + " " if prefix else ""
 
     def on_request(self, request: PipelineRequest[HTTPRequestType]) -> None:
+        """Called before the policy sends a request.
+
+        :param request: The request to be modified before sending.
+        :type request: ~corehttp.runtime.pipeline.PipelineRequest
+        """
         request.http_request.headers[self._name] = f"{self._prefix}{self._credential.key}"

corehttp/runtime/policies/_authentication_async.py

@@ -13,6 +13,7 @@ from ..pipeline._tools_async import await_result
 from ._base_async import AsyncHTTPPolicy
 from ._authentication import _BearerTokenCredentialPolicyBase
 from ...rest import AsyncHttpResponse, HttpRequest
+from ...exceptions import HttpResponseError
 from ...utils._utils import get_running_async_lock
 
 if TYPE_CHECKING:
@@ -66,8 +67,11 @@ class AsyncBearerTokenCredentialPolicy(AsyncHTTPPolicy[HTTPRequestType, AsyncHTT
         :type request: ~corehttp.runtime.pipeline.PipelineRequest
         :keyword auth_flows: A list of authentication flows to use for the credential.
         :paramtype auth_flows: list[dict[str, Union[str, list[dict[str, str]]]]]
-        :raises: :class:`~corehttp.exceptions.ServiceRequestError`
+        :raises ~corehttp.exceptions.ServiceRequestError: If the request fails.
         """
+        # If auth_flows is an empty list, we should not attempt to authorize the request.
+        if auth_flows is not None and len(auth_flows) == 0:
+            return
         _BearerTokenCredentialPolicyBase._enforce_https(request)  # pylint:disable=protected-access
 
         if self._token is None or self._need_new_token:
@@ -107,7 +111,9 @@ class AsyncBearerTokenCredentialPolicy(AsyncHTTPPolicy[HTTPRequestType, AsyncHTT
         :return: The pipeline response object
         :rtype: ~corehttp.runtime.pipeline.PipelineResponse
         """
-        await await_result(self.on_request, request, auth_flows=self._auth_flows)
+        op_auth_flows = request.context.options.pop("auth_flows", None)
+        auth_flows = op_auth_flows if op_auth_flows is not None else self._auth_flows
+        await await_result(self.on_request, request, auth_flows=auth_flows)
         try:
             response = await self.next.send(request)
         except Exception:
@@ -118,7 +124,20 @@ class AsyncBearerTokenCredentialPolicy(AsyncHTTPPolicy[HTTPRequestType, AsyncHTT
         if response.http_response.status_code == 401:
             self._token = None  # any cached token is invalid
             if "WWW-Authenticate" in response.http_response.headers:
-                request_authorized = await self.on_challenge(request, response)
+                try:
+                    request_authorized = await self.on_challenge(request, response)
+                except Exception as ex:
+                    # If the response is streamed, read it so the error message is immediately available to the user.
+                    # Otherwise, a generic error message will be given and the user will have to read the response
+                    # body to see the actual error.
+                    if response.context.options.get("stream"):
+                        try:
+                            await response.http_response.read()  # type: ignore
+                        except Exception:  # pylint:disable=broad-except
+                            pass
+
+                    # Raise the exception from the token request with the original 401 response
+                    raise ex from HttpResponseError(response=response.http_response)
                 if request_authorized:
                     try:
                         response = await self.next.send(request)