Document response classes (#175)

docs/sphinx/conf.py

@@ -36,6 +36,7 @@
 ]
 
 pygments_style = "sphinx"
+pygments_dark_style = "monokai"
 
 templates_path = []
 exclude_patterns = []
@@ -44,5 +45,5 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "requests": ("https://docs.python-requests.org/en/master", None),
+    "requests": ("https://docs.python-requests.org/en/latest", None),
 }

docs/sphinx/index.rst

@@ -6,6 +6,7 @@ API Reference
 
    installation
    nodes
+   responses
    exceptions
    logging
    transport

docs/sphinx/responses.rst

@@ -0,0 +1,43 @@
+Responses
+=========
+
+.. py:currentmodule:: elastic_transport
+
+
+Response headers
+----------------
+
+.. autoclass:: elastic_transport::HttpHeaders
+   :members: freeze
+
+Metadata
+--------
+
+.. autoclass:: ApiResponseMeta
+   :members:
+
+Response classes
+----------------
+
+.. autoclass:: ApiResponse
+   :members:
+
+.. autoclass:: BinaryApiResponse
+   :members:
+   :show-inheritance:
+
+.. autoclass:: HeadApiResponse
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ListApiResponse
+   :members:
+   :show-inheritance:
+
+.. autoclass:: ObjectApiResponse
+   :members:
+   :show-inheritance:
+
+.. autoclass:: TextApiResponse
+   :members:
+   :show-inheritance:

elastic_transport/_models.py

@@ -68,7 +68,15 @@ def __str__(self) -> str:
 
 
 class HttpHeaders(MutableMapping[str, str]):
-    """HTTP headers"""
+    """HTTP headers
+
+    Behaves like a Python dictionary. Can be used like this::
+
+      headers = HttpHeaders()
+      headers["foo"] = "bar"
+      headers["foo"] = "baz"
+      print(headers["foo"])  # prints "baz"
+    """
 
     __slots__ = ("_internal", "_frozen")
 
@@ -180,26 +188,24 @@ def hide_auth(val: str) -> str:
 
 @dataclass
 class ApiResponseMeta:
-    """Metadata that is returned from Transport.perform_request()"""
+    """Metadata that is returned from Transport.perform_request()
+
+    :ivar int status: HTTP status code
+    :ivar str http_version: HTTP version being used
+    :ivar HttpHeaders headers: HTTP headers
+    :ivar float duration: Number of seconds from start of request to start of response
+    :ivar NodeConfig node: Node which handled the request
+    :ivar typing.Optional[str] mimetype: Mimetype to be used by the serializer to decode the raw response bytes.
+    """
 
-    #: HTTP status code
     status: int
-
-    #: HTTP version being used
     http_version: str
-
-    #: HTTP headers
     headers: HttpHeaders
-
-    #: Number of seconds from start of request to start of response
     duration: float
-
-    #: Node which handled the request
     node: "NodeConfig"
 
     @property
     def mimetype(self) -> Optional[str]:
-        """Mimetype to be used by the serializer to decode the raw response bytes."""
         try:
             content_type = self.headers["content-type"]
             return content_type.partition(";")[0] or None