Skip to content

Commit

Permalink
improve docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@iscai-msft
iscai-msft committed Aug 30, 2021
1 parent 312b0fc commit 90da0a4
Show file tree
Hide file tree
Showing 3 changed files with 115 additions and 37 deletions.
14 changes: 12 additions & 2 deletions sdk/core/azure-core/azure/core/rest/_http_response_impl.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,18 +62,28 @@ def __init__(self, **kwargs):
@property
def request(self):
# type: (...) -> _HttpRequest
"""The request that resulted in this response.
:rtype: ~azure.core.rest.HttpRequest
"""
return self._request

@property
def url(self):
# type: (...) -> str
"""Returns the URL that resulted in this response"""
"""The URL that resulted in this response.
:rtype: str
"""
return self.request.url

@property
def is_closed(self):
# type: (...) -> bool
"""Whether the network connection has been closed yet"""
"""Whether the network connection has been closed yet.
:rtype: bool
"""
return self._is_closed

@property
Expand Down
64 changes: 49 additions & 15 deletions sdk/core/azure-core/azure/core/rest/_rest.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,43 +194,64 @@ class _HttpResponseBase(ABC):
@abc.abstractmethod
def request(self):
# type: (...) -> HttpRequest
"""The request that resulted in this response."""
"""The request that resulted in this response.
:rtype: ~azure.core.rest.HttpRequest
"""

@property
@abc.abstractmethod
def status_code(self):
# type: (...) -> int
"""The status code of this response"""
"""The status code of this response.
:rtype: int
"""

@property
@abc.abstractmethod
def headers(self):
# type: (...) -> Optional[MutableMapping[str, str]]
"""The response headers"""
"""The response headers.
:rtype: MutableMapping[str, str]
"""

@property
@abc.abstractmethod
def reason(self):
# type: (...) -> str
"""The reason phrase for this response"""
"""The reason phrase for this response.
:rtype: str
"""

@property
@abc.abstractmethod
def content_type(self):
# type: (...) -> str
"""The content type of the response"""
"""The content type of the response.
:rtype: str
"""

@property
@abc.abstractmethod
def is_closed(self):
# type: (...) -> bool
"""Whether the network connection has been closed yet"""
"""Whether the network connection has been closed yet.
:rtype: bool
"""

@property
@abc.abstractmethod
def is_stream_consumed(self):
# type: (...) -> bool
"""Whether the stream has been fully consumed"""
"""Whether the stream has been fully consumed.
:rtype: bool
"""

@property
@abc.abstractmethod
Expand All @@ -247,22 +268,29 @@ def encoding(self):
@encoding.setter
def encoding(self, value):
# type: (str) -> None
"""Sets the response encoding"""
"""Sets the response encoding.
:rtype: None
"""

@property
@abc.abstractmethod
def url(self):
# type: (...) -> str
"""Returns the URL that resulted in this response"""
"""The URL that resulted in this response.
:rtype: str
"""

@abc.abstractmethod
def text(self, encoding=None):
# type: (Optional[str]) -> str
"""Returns the response body as a string
"""Returns the response body as a string.
: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
"""

@abc.abstractmethod
Expand All @@ -281,13 +309,19 @@ def raise_for_status(self):
"""Raises an HttpResponseError if the response has an error status code.
If response is good, does nothing.
:rtype: None
:raises ~azure.core.HttpResponseError if the object has an error status code.:
"""

@property
@abc.abstractmethod
def content(self):
# type: (...) -> bytes
"""Return the response's content in bytes."""
"""Return the response's content in bytes.
:rtype: bytes
"""


class HttpResponse(_HttpResponseBase):
Expand Down Expand Up @@ -333,7 +367,7 @@ def read(self):
@abc.abstractmethod
def iter_raw(self):
# type: () -> Iterator[bytes]
"""Iterates over the response's bytes. Will not decompress in the process
"""Iterates over the response's bytes. Will not decompress in the process.
:return: An iterator of bytes from the response
:rtype: Iterator[str]
Expand All @@ -342,7 +376,7 @@ def iter_raw(self):
@abc.abstractmethod
def iter_bytes(self):
# type: () -> Iterator[bytes]
"""Iterates over the response's bytes. Will decompress in the process
"""Iterates over the response's bytes. Will decompress in the process.
:return: An iterator of bytes from the response
:rtype: Iterator[str]
Expand All @@ -353,7 +387,7 @@ def iter_text(self):
# type: () -> Iterator[str]
"""Iterates over the text in the response.
:return: An iterator of string. Each string chunk will be a text from the response
:return: An iterator of string. Each string chunk will be a text from the response.
:rtype: Iterator[str]
"""

Expand All @@ -362,6 +396,6 @@ def iter_lines(self):
# type: () -> Iterator[str]
"""Iterates over the lines in the response.
:return: An iterator of string. Each string chunk will be a line from the response
:return: An iterator of string. Each string chunk will be a line from the response.
:rtype: Iterator[str]
"""
74 changes: 54 additions & 20 deletions sdk/core/azure-core/azure/core/rest/_rest_py3.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,49 +186,70 @@ def _from_pipeline_transport_request(cls, pipeline_transport_request):
return from_pipeline_transport_request_helper(cls, pipeline_transport_request)

class _HttpResponseBase(abc.ABC):
"""Base abstract base class for HttpResponses
"""Base abstract base class for HttpResponses.
"""

@property
@abc.abstractmethod
def request(self) -> HttpRequest:
"""The request that resulted in this response."""
"""The request that resulted in this response.
:rtype: ~azure.core.rest.HttpRequest
"""
...

@property
@abc.abstractmethod
def status_code(self) -> int:
"""The status code of this response"""
"""The status code of this response.
:rtype: int
"""
...

@property
@abc.abstractmethod
def headers(self) -> Optional[MutableMapping[str, str]]:
"""The response headers"""
def headers(self) -> MutableMapping[str, str]:
"""The response headers.
:rtype: MutableMapping[str, str]
"""
...

@property
@abc.abstractmethod
def reason(self) -> str:
"""The reason phrase for this response"""
"""The reason phrase for this response.
:rtype: str
"""
...

@property
@abc.abstractmethod
def content_type(self) -> str:
"""The content type of the response"""
"""The content type of the response.
:rtype: str
"""
...

@property
@abc.abstractmethod
def is_closed(self) -> bool:
"""Whether the network connection has been closed yet"""
"""Whether the network connection has been closed yet.
:rtype: bool
"""
...

@property
@abc.abstractmethod
def is_stream_consumed(self) -> bool:
"""Whether the stream has been fully consumed"""
"""Whether the stream has been fully consumed.
:rtype: bool
"""
...

@property
Expand All @@ -245,27 +266,37 @@ def encoding(self) -> Optional[str]:

@encoding.setter
def encoding(self, value: Optional[str]) -> None:
"""Sets the response encoding"""
"""Sets the response encoding.
:rtype: None
"""

@property
@abc.abstractmethod
def url(self) -> str:
"""The URL that resulted in this response"""
"""The URL that resulted in this response.
:rtype: str
"""
...

@property
@abc.abstractmethod
def content(self) -> bytes:
"""Return the response's content in bytes."""
"""Return the response's content in bytes.
:rtype: bytes
"""
...

@abc.abstractmethod
def text(self, encoding: Optional[str] = None) -> str:
"""Returns the response body as a string
"""Returns the response body as a string.
: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
"""
...

Expand All @@ -284,6 +315,9 @@ def raise_for_status(self) -> None:
"""Raises an HttpResponseError if the response has an error status code.
If response is good, does nothing.
:rtype: None
:raises ~azure.core.HttpResponseError if the object has an error status code.:
"""
...

Expand Down Expand Up @@ -326,7 +360,7 @@ def read(self) -> bytes:

@abc.abstractmethod
def iter_raw(self) -> Iterator[bytes]:
"""Iterates over the response's bytes. Will not decompress in the process
"""Iterates over the response's bytes. Will not decompress in the process.
:return: An iterator of bytes from the response
:rtype: Iterator[str]
Expand All @@ -335,7 +369,7 @@ def iter_raw(self) -> Iterator[bytes]:

@abc.abstractmethod
def iter_bytes(self) -> Iterator[bytes]:
"""Iterates over the response's bytes. Will decompress in the process
"""Iterates over the response's bytes. Will decompress in the process.
:return: An iterator of bytes from the response
:rtype: Iterator[str]
Expand All @@ -346,7 +380,7 @@ def iter_bytes(self) -> Iterator[bytes]:
def iter_text(self) -> Iterator[str]:
"""Iterates over the text in the response.
:return: An iterator of string. Each string chunk will be a text from the response
:return: An iterator of string. Each string chunk will be a text from the response.
:rtype: Iterator[str]
"""
...
Expand All @@ -355,7 +389,7 @@ def iter_text(self) -> Iterator[str]:
def iter_lines(self) -> Iterator[str]:
"""Iterates over the lines in the response.
:return: An iterator of string. Each string chunk will be a line from the response
:return: An iterator of string. Each string chunk will be a line from the response.
:rtype: Iterator[str]
"""
...
Expand Down Expand Up @@ -387,7 +421,7 @@ async def read(self) -> bytes:

@abc.abstractmethod
async def iter_raw(self) -> AsyncIterator[bytes]:
"""Asynchronously iterates over the response's bytes. Will not decompress in the process
"""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]
Expand All @@ -398,7 +432,7 @@ async def iter_raw(self) -> AsyncIterator[bytes]:

@abc.abstractmethod
async def iter_bytes(self) -> AsyncIterator[bytes]:
"""Asynchronously iterates over the response's bytes. Will decompress in the process
"""Asynchronously iterates over the response's bytes. Will decompress in the process.
:return: An async iterator of bytes from the response
:rtype: AsyncIterator[bytes]
Expand All @@ -422,7 +456,7 @@ async def iter_text(self) -> AsyncIterator[str]:
async def iter_lines(self) -> AsyncIterator[str]:
"""Asynchronously iterates over the lines in the response.
:return: An async iterator of string. Each string chunk will be a line from the response
:return: An async iterator of string. Each string chunk will be a line from the response.
:rtype: AsyncIterator[str]
"""
raise NotImplementedError()
Expand Down

0 comments on commit 90da0a4

Please sign in to comment.