[rest] GA in docs! (Azure#21545)

Author: iscai-msft

sdk/core/azure-core/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ### Features Added
 
+- GA `send_request` onto the `azure.core.PipelineClient` and `azure.core.AsyncPipelineClient`. This method takes in
+requests and sends them through our pipelines.
+- GA `azure.core.rest`. `azure.core.rest` is our new public simple HTTP library in `azure.core` that users will use to create requests, and consume responses.
+- GA errors `StreamConsumedError`, `StreamClosedError`, and `ResponseNotReadError` to `azure.core.exceptions`. These errors
+are thrown if you mishandle streamed responses from the `azure.core.rest` module
 - add kwargs to the methods for `iter_raw` and `iter_bytes`  #21529
 - Added new error type `IncompleteReadError` which is raised if peer closes the connection before we have received the complete message body.
 

sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md

@@ -14,7 +14,8 @@ When constructing an SDK, a developer may consume the pipeline like so:
 
 ```python
 from azure.core.pipeline import Pipeline
-from azure.core.transport import RequestsTransport, HttpRequest
+from azure.core.rest import HttpRequest
+from azure.core.transport import RequestsTransport
 from azure.core.pipeline.policies import (
     UserAgentPolicy,
     HeadersPolicy,
@@ -193,106 +194,126 @@ proxy_policy.proxies = {'https': 'http://user:[email protected]:1180/'}
 
 ### HttpRequest and HttpResponse
 
-The HttpRequest and HttpResponse objects represent a generic concept of HTTP request and response constructs and are in no way tied to a particular transport or HTTP library.
+The `HttpRequest` and `HttpResponse` objects represent a generic concept of HTTP request and response constructs and are in no way tied to a particular transport or HTTP library.
 
-The HttpRequest has the following API. It does not vary between transports:
+The `HttpRequest` has the following API. It does not vary between transports:
 
 ```python
-class HttpRequest(object):
-
-    def __init__(self, method, url, headers=None, files=None, data=None):
-        self.method = method
+class HttpRequest:
+
+    def __init__(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Optional[ParamsType] = None,
+        headers: Optional[MutableMapping[str, str]] = None,
+        json: Any = None,
+        content: Optional[ContentType] = None,
+        data: Optional[dict] = None,
+        files: Optional[FilesType] = None,
+        **kwargs
+    ):
         self.url = url
-        self.headers = CaseInsensitiveDict(headers)
-        self.files = files
-        self.data = data
+        self.method = method
+        self.headers = CaseInsensitiveDict(default_headers)
 
     @property
-    def body(self):
-        return self.data
-
-    @body.setter
-    def body(self, value):
-        self.data = value
-
-    def format_parameters(self, params):
-        """Format parameters into a valid query string.
-        It's assumed all parameters have already been quoted as
-        valid URL strings."""
-
-    def set_xml_body(self, data):
-        """Set an XML element tree as the body of the request."""
-
-    def set_json_body(self, data):
-        """Set a JSON-friendly object as the body of the request."""
-
-    def set_multipart_body(self, data=None):
-        """Set form-encoded data as the body of the request.
-        Supported content-types are:
-            - application/x-www-form-urlencoded
-            - multipart/form-data
-        """
-
-    def set_bytes_body(self, data):
-        """Set generic bytes as the body of the request."""
-
-    def set_multipart_mixed(self, *requests, **kwargs):
-        """Set requests for a multipart/mixed body.
-        Optionally apply "policies" in kwargs to each request.
-        """
+    def content(self) -> Any:
+        """Get's the request's content"""
 ```
 
-The HttpResponse object on the other hand will generally have a transport-specific derivative.
-This is to accomodate how the data is extracted for the object returned by the HTTP library.
-There is also an async flavor: AsyncHttpResponse. This is to allow for the asynchronous streaming of
-data from the response.
-For example:
+`HttpResponse` on the other hand is an abstract base class that will have to be implemented
+for a transport-specific derivative to accommodate how data is extracted from the object
+returned by the HTTP library.
+
+The API for each of these response types is identical, so the consumer of the `HttpResponse` need not know about these
+particular types.
+
+The `HttpResponse` has the following API. It does not vary between transports, and has the following surface area:
 
 ```python
-from azure.core.pipeline.transport import (
-    RequestsTransportResponse,  # HttpResponse
-    AioHttpTransportResponse, # AsyncHttpResponse
-    TrioRequestsTransportResponse,  # AsyncHttpResponse
-    AsyncioRequestsTransportResponse,  # AsyncHttpResponse
-)
-```
+class HttpResponse:
 
-The API for each of these response types is identical, so the consumer of the Response need not know about these
-particular types.
+    @property
+    def request(self) -> HttpRequest:
+        """The request that resulted in this response."""
 
-The HttpResponse has the following API. It does not vary between transports:
+    @property
+    def status_code(self) -> int:
+        """The status code of this response."""
+
+    @property
+    def headers(self) -> MutableMapping[str, str]:
+        """The response headers. Must be case-insensitive."""
+
+    @property
+    def reason(self) -> str:
+        """The reason phrase for this response."""
+
+    @property
+    def content_type(self) -> Optional[str]:
+        """The content type of the response."""
+
+    @property
+    def is_closed(self) -> bool:
+        """Whether the network connection has been closed yet."""
+
+    @property
+    def is_stream_consumed(self) -> bool:
+        """Whether the stream has been consumed."""
+
+    @property
+    def encoding(self) -> Optional[str]:
+        """Returns the response encoding."""
+
+    @encoding.setter
+    def encoding(self, value: Optional[str]) -> None:
+        """Sets the response encoding."""
+
+    @property
+    def url(self) -> str:
+        """The URL that resulted in this response."""
+
+    @property
+    def content(self) -> bytes:
+        """Return the response's content in bytes."""
+
+    def text(self, encoding: Optional[str] = None) -> str:
+        """Returns the response body as a string."""
+
+    def json(self) -> Any:
+        """Returns the whole body as a json object."""
+
+    def raise_for_status(self) -> None:
+        """Raises an HttpResponseError if the response has an error status code."""
+
+    def read(self) -> bytes:
+        """Read the response's bytes."""
+
+    def iter_raw(self, **kwargs: Any) -> Iterator[bytes]:
+        """Iterates over the response's bytes. Will not decompress in the process."""
+
+    def iter_bytes(self, **kwargs: Any) -> Iterator[bytes]:
+        """Iterates over the response's bytes. Will decompress in the process."""
+
+```
+
+Async calls to networks will return an `AsyncHttpResponse` instead. It shares most of its properties with an `HttpResponse` with the following exceptions:
 
 ```python
-class HttpResponse(object):
-
-    def __init__(self, request, internal_response):
-        self.request = request
-        self.internal_response = internal_response  # The object returned by the HTTP library
-        self.status_code = None
-        self.headers = CaseInsensitiveDict()
-        self.reason = None
-        self.content_type = None
-
-    def body(self):
-        """Return the whole body as bytes in memory."""
-
-    def text(self, encoding=None):
-        """Return the whole body as a string."""
-
-    def stream_download(self, pipeline, **kwargs):
-        """Generator for streaming request body data.
-        Should be implemented by sub-classes if streaming download
-        is supported.
-        For the AsyncHttpResponse object this function will return
-        and asynchronous generator.
-        """
-
-    def parts(self):
-        """An iterator of parts if content-type is multipart/mixed.
-        For the AsyncHttpResponse object this function will return
-        and asynchronous iterator.
-        """
+class AsyncHttpResponse:
+
+    ...
+
+    async def read(self) -> bytes:
+        """Read the response's bytes into memory."""
+
+    async def iter_raw(self, **kwargs: Any) -> AsyncIterator[bytes]:
+        """Asynchronously iterates over the response's bytes. Will not decompress in the process."""
 
+    async def iter_bytes(self, **kwargs: Any) -> AsyncIterator[bytes]:
+        """Asynchronously iterates over the response's bytes. Will decompress in the process."""
 ```
 
 ### PipelineRequest and PipelineResponse
@@ -467,7 +488,7 @@ A pipeline can either be synchronous or asynchronous.
 The pipeline does not expose the policy chain, so individual policies cannot/should not be further
 configured once the pipeline has been instantiated.
 
-The pipeline has a single exposed operation: `run(request)` which will send a new HttpRequest object down
+The pipeline has a single exposed operation: `run(request)` which will send a new `HttpRequest` object down
 the pipeline. This operation returns a `PipelineResponse` object.
 
 ```python

sdk/core/azure-core/README.md

@@ -116,19 +116,16 @@ class TooManyRedirectsError(HttpResponseError):
 
 *kwargs* are keyword arguments to include with the exception.
 
-#### **Provisional** StreamConsumedError
-A **provisional** error thrown if you try to access the stream of the **provisional**
-responses `azure.core.rest.HttpResponse` or `azure.core.rest.AsyncHttpResponse` once
+#### StreamConsumedError
+An error thrown if you try to access the stream of `azure.core.rest.HttpResponse` or `azure.core.rest.AsyncHttpResponse` once
 the response stream has been consumed.
 
-#### **Provisional** StreamClosedError
-A **provisional** error thrown if you try to access the stream of the **provisional**
-responses `azure.core.rest.HttpResponse` or `azure.core.rest.AsyncHttpResponse` once
+#### StreamClosedError
+An error thrown if you try to access the stream of the `azure.core.rest.HttpResponse` or `azure.core.rest.AsyncHttpResponse` once
 the response stream has been closed.
 
-#### **Provisional** ResponseNotReadError
-A **provisional** error thrown if you try to access the `content` of the **provisional**
-responses `azure.core.rest.HttpResponse` or `azure.core.rest.AsyncHttpResponse` before
+#### ResponseNotReadError
+An error thrown if you try to access the `content` of `azure.core.rest.HttpResponse` or `azure.core.rest.AsyncHttpResponse` before
 reading in the response's bytes first.
 
 ### Configurations

sdk/core/azure-core/azure/core/_pipeline_client.py

@@ -176,9 +176,7 @@ def _build_pipeline(self, config, **kwargs): # pylint: disable=no-self-use
 
     def send_request(self, request, **kwargs):
         # type: (HTTPRequestType, Any) -> HTTPResponseType
-        """**Provisional** method that runs the network request through the client's chained policies.
-
-        This method is marked as **provisional**, meaning it may be changed in a future release.
+        """Method that runs the network request through the client's chained policies.
 
         >>> from azure.core.rest import HttpRequest
         >>> request = HttpRequest('GET', 'http://www.example.com')

sdk/core/azure-core/azure/core/_pipeline_client_async.py

@@ -208,9 +208,7 @@ def send_request(
         stream: bool = False,
         **kwargs: Any
     ) -> Awaitable[AsyncHTTPResponseType]:
-        """**Provisional** method that runs the network request through the client's chained policies.
-
-        This method is marked as **provisional**, meaning it may be changed in a future release.
+        """Method that runs the network request through the client's chained policies.
 
         >>> from azure.core.rest import HttpRequest
         >>> request = HttpRequest('GET', 'http://www.example.com')

sdk/core/azure-core/azure/core/exceptions.py

@@ -442,10 +442,9 @@ def __str__(self):
         return super(ODataV4Error, self).__str__()
 
 class StreamConsumedError(AzureError):
-    """**Provisional** error thrown if you try to access the stream of a response once consumed.
+    """Error thrown if you try to access the stream of a response once consumed.
 
-    This error is marked as **provisional**, meaning it may be changed in a future release. It is
-    thrown if you try to read / stream an ~azure.core.rest.HttpResponse or
+    It is thrown if you try to read / stream an ~azure.core.rest.HttpResponse or
     ~azure.core.rest.AsyncHttpResponse once the response's stream has been consumed.
     """
     def __init__(self, response):
@@ -458,10 +457,9 @@ def __init__(self, response):
         super(StreamConsumedError, self).__init__(message)
 
 class StreamClosedError(AzureError):
-    """**Provisional** error thrown if you try to access the stream of a response once closed.
+    """Error thrown if you try to access the stream of a response once closed.
 
-    This error is marked as **provisional**, meaning it may be changed in a future release. It is
-    thrown if you try to read / stream an ~azure.core.rest.HttpResponse or
+    It is thrown if you try to read / stream an ~azure.core.rest.HttpResponse or
     ~azure.core.rest.AsyncHttpResponse once the response's stream has been closed.
     """
     def __init__(self, response):
@@ -472,10 +470,9 @@ def __init__(self, response):
         super(StreamClosedError, self).__init__(message)
 
 class ResponseNotReadError(AzureError):
-    """**Provisional** error thrown if you try to access a response's content without reading first.
+    """Error thrown if you try to access a response's content without reading first.
 
-    This error is marked as **provisional**, meaning it may be changed in a future release. It is
-    thrown if you try to access an ~azure.core.rest.HttpResponse or
+    It is thrown if you try to access an ~azure.core.rest.HttpResponse or
     ~azure.core.rest.AsyncHttpResponse's content without first reading the response's bytes in first.
     """
 

sdk/core/azure-core/azure/core/polling/async_base_polling.py

@@ -131,7 +131,6 @@ async def request_status(self, status_link):  # pylint:disable=invalid-overridde
         # if I am a azure.core.pipeline.transport.HttpResponse
         request = self._client.get(status_link)
 
-        # can't use send_request in this case, because send_request is still provisional
         return await self._client._pipeline.run(  # pylint: disable=protected-access
             request, stream=False, **self._operation_config
         )

sdk/core/azure-core/azure/core/polling/base_polling.py

@@ -588,8 +588,6 @@ def request_status(self, status_link):
             )
         # if I am a azure.core.pipeline.transport.HttpResponse
         request = self._client.get(status_link)
-
-        # can't use send_request in this case, because send_request is still provisional
         return self._client._pipeline.run(  # pylint: disable=protected-access
             request, stream=False, **self._operation_config
         )

sdk/core/azure-core/azure/core/rest/_rest.py

@@ -60,9 +60,7 @@
 ################################## CLASSES ######################################
 
 class HttpRequest(HttpRequestBackcompatMixin):
-    """Provisional object that represents an HTTP request.
-
-    **This object is provisional**, meaning it may be changed in a future release.
+    """HTTP request.
 
     It should be passed to your client's `send_request` method.
 
@@ -321,9 +319,8 @@ def content(self):
 
 
 class HttpResponse(_HttpResponseBase):
-    """**Provisional** abstract base class for HTTP responses.
+    """Abstract base class for HTTP responses.
 
-    **This object is provisional**, meaning it may be changed in a future release.
     Use this abstract base class to create your own transport responses.
 
     Responses implementing this ABC are returned from your client's `send_request` method