Merge #87

87: Cleanup docstrings and generated html pages for API r=ashley-cui a=jwhonce

* Overused Notes in docstrings.
* Change Literal import to not mask which Literal is being used
* Reduced number of warnings from sphinx-build
* Fixed type hints for @properties

Signed-off-by: Jhon Honce <[email protected]>

Co-authored-by: Jhon Honce <[email protected]>

Author: bors[bot]

docs/source/_static/about.html

@@ -36,19 +36,19 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 # isort: unique-list
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.viewcode',
-]
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['**/api_connection.py']
+# isort: unique-list
+exclude_patterns = [
+    'podman.api.*rst',
+    'podman.rst',
+]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -103,7 +103,7 @@
 napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = False
-napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_examples = True
 napoleon_use_admonition_for_notes = True
 napoleon_use_admonition_for_references = False
 napoleon_use_ivar = False

docs/source/conf.py

@@ -22,8 +22,7 @@
 def _api_version(release: str, significant: int = 3) -> str:
     """Return API version removing any additional identifiers from the release version.
 
-    Notes:
-        This is a simple lexicographical parsing, no semantics are applied, e.g. semver checking.
+    This is a simple lexicographical parsing, no semantics are applied, e.g. semver checking.
     """
     items = re.split(r"\.|-|\+", release)
     parts = items[0:significant]

podman/api/__init__.py

@@ -10,16 +10,15 @@ def _key_normalizer(key_class: NamedTuple, request_context: Mapping) -> Mapping:
     key for an HTTPS request. If you wish to change this behaviour, provide
     alternate callables to ``key_fn_by_scheme``.
 
+    Copied from urllib3.poolmanager._default_key_normalizer.
+
     Args:
         key_class: The class to use when constructing the key. This should be a namedtuple
             with the scheme and host keys at a minimum.
         request_context: An object that contain the context for a request.
 
     Returns:
         A namedtuple that can be used as a connection pool key.
-
-    Notes:
-        Copied from urllib3.poolmanager._default_key_normalizer.
     """
     # Since we mutate the dictionary, make a copy first
     context = request_context.copy()

podman/api/adapter_utils.py

@@ -56,8 +56,7 @@ def _format_string(filters, criteria):
 def prepare_body(body: Mapping[str, Any]) -> str:
     """Returns JSON payload to be uploaded to server.
 
-    Notes:
-        Values of None and empty Iterables are removed, False and zero-values are retained.
+    Values of None and empty Iterables are removed, False and zero-values are retained.
     """
     if body is None:
         return ""
@@ -69,8 +68,7 @@ def prepare_body(body: Mapping[str, Any]) -> str:
 def _filter_values(mapping: Mapping[str, Any]) -> Dict[str, Any]:
     """Returns a canonical dictionary with values == None or empty Iterables removed.
 
-    Notes:
-        Dictionary is walked using recursion.
+    Dictionary is walked using recursion.
     """
     canonical = dict()
     for key, value in mapping.items():

podman/api/http_utils.py

@@ -57,17 +57,15 @@ def prepare_timestamp(value: Union[datetime, int, None]) -> Optional[int]:
 def prepare_cidr(value: Union[ipaddress.IPv4Network, ipaddress.IPv6Network]) -> (str, str):
     """Returns network address and Base64 encoded netmask from CIDR.
 
-    Notes:
-        The return values are dictated by the Go JSON decoder.
+    The return values are dictated by the Go JSON decoder.
     """
     return str(value.network_address), base64.b64encode(value.netmask.packed).decode("utf-8")
 
 
 def frames(response: Response) -> Iterator[bytes]:
     """Returns each frame from multiplexed payload, all results are expected in the payload.
 
-    Notes:
-        The stdout and stderr frames are undifferentiated as they are returned.
+    The stdout and stderr frames are undifferentiated as they are returned.
     """
     length = len(response.content)
     index = 0

podman/api/parse_utils.py

@@ -40,8 +40,7 @@ def __init__(self, uri: str, identity: Optional[str] = None):
 
         Examples:
             SSHSocket("http+ssh://[email protected]:2222/run/user/1000/podman/podman.sock",
-                      "~alice/.ssh/api_ed25519"
-            )
+                      "~alice/.ssh/api_ed25519")
         """
         super().__init__(socket.AF_UNIX, socket.SOCK_STREAM)
         self.uri = uri
@@ -130,8 +129,7 @@ def recv(self, buffersize, flags=None) -> bytes:  # pylint: disable=unused-argum
     def close(self):
         """Release resources held by SSHSocket.
 
-        Notes:
-            - SSH client is first sent SIGTERM, then a SIGKILL 20 seconds later if needed.
+        The SSH client is first sent SIGTERM, then a SIGKILL 20 seconds later if needed.
         """
         if not self._proc or self._proc.stdin.closed:
             return

podman/api/ssh.py

@@ -13,8 +13,7 @@
 def prepare_containerignore(anchor: str) -> List[str]:
     """Return the list of patterns for filenames to exclude.
 
-    Notes:
-       .containerignore takes precedence over .dockerignore.
+    .containerignore takes precedence over .dockerignore.
     """
     for filename in (".containerignore", ".dockerignore"):
         ignore = pathlib.Path(anchor) / filename

podman/api/tar_utils.py

@@ -155,8 +155,7 @@ def __init__(
 
         Examples:
             requests.Session.mount(
-                "http://", UDSAdapater("http+unix:///run/user/1000/podman/podman.sock")
-            )
+                "http://", UDSAdapater("http+unix:///run/user/1000/podman/podman.sock"))
         """
         self.poolmanager: Optional[UDSPoolManager] = None
 

podman/api/uds.py

@@ -29,8 +29,7 @@ class PodmanClient(AbstractContextManager):
     Examples:
 
         with PodmanClient("ssh://[email protected]:22/run/podman/podman.sock?secure=True",
-            identity="~alice/.ssh/api_ed25519"
-        )
+            identity="~alice/.ssh/api_ed25519")
     """
 
     def __init__(self, *args, **kwargs) -> None:
@@ -53,6 +52,7 @@ def __init__(self, *args, **kwargs) -> None:
 
         Examples:
             base_url:
+
                 - http+ssh://<user>@<host>[:port]</run/podman/podman.sock>[?secure=True]
                 - http+unix://</run/podman/podman.sock>
                 - tcp://<localhost>[:<port>]
@@ -210,7 +210,7 @@ def swarm(self):
         """Swarm not supported.
 
         Raises:
-            NotImplemented: Always, swarm not supported by Podman service
+            NotImplemented: Swarm not supported by Podman service
         """
         raise NotImplementedError("Swarm operations are not supported by Podman service.")