Update existing Sphinx docstrings (#811)

* Reformat existing Sphinx docstrings

* Rewrite get_userpass_value docstring

* Use doc comments for partial functions

twine/settings.py

@@ -64,60 +64,46 @@ def __init__(
     ) -> None:
         """Initialize our settings instance.
 
-        :param bool sign:
+        :param sign:
             Configure whether the package file should be signed.
-
-            This defaults to ``False``.
-        :param str sign_with:
+        :param sign_with:
             The name of the executable used to sign the package with.
-
-            This defaults to ``gpg``.
-        :param str identity:
+        :param identity:
             The GPG identity that should be used to sign the package file.
-        :param str username:
+        :param username:
             The username used to authenticate to the repository (package
             index).
-        :param str password:
+        :param password:
             The password used to authenticate to the repository (package
             index).
-        :param bool non_interactive:
+        :param non_interactive:
             Do not interactively prompt for username/password if the required
             credentials are missing.
-
-            This defaults to ``False``.
-        :param str comment:
+        :param comment:
             The comment to include with each distribution file.
-        :param str config_file:
+        :param config_file:
             The path to the configuration file to use.
-
-            This defaults to ``~/.pypirc``.
-        :param bool skip_existing:
+        :param skip_existing:
             Specify whether twine should continue uploading files if one
             of them already exists. This primarily supports PyPI. Other
             package indexes may not be supported.
-
-            This defaults to ``False``.
-        :param str cacert:
+        :param cacert:
             The path to the bundle of certificates used to verify the TLS
             connection to the package index.
-        :param str client_cert:
-            The path to the client certificate used to perform authentication
-            to the index.
-
-            This must be a single file that contains both the private key and
+        :param client_cert:
+            The path to the client certificate used to perform authentication to the
+            index. This must be a single file that contains both the private key and
             the PEM-encoded certificate.
-        :param str repository_name:
+        :param repository_name:
             The name of the repository (package index) to interact with. This
             should correspond to a section in the config file.
-        :param str repository_url:
+        :param repository_url:
             The URL of the repository (package index) to interact with. This
             will override the settings inferred from ``repository_name``.
-        :param bool verbose:
+        :param verbose:
             Show verbose output.
-        :param bool disable_progress_bar:
+        :param disable_progress_bar:
             Disable the progress bar.
-
-            This defaults to ``False``
         """
         self.config_file = config_file
         self.comment = comment
@@ -326,8 +312,8 @@ def _handle_certificates(
     def check_repository_url(self) -> None:
         """Verify we are not using legacy PyPI.
 
-        :raises:
-            :class:`~twine.exceptions.UploadToDeprecatedPyPIDetected`
+        :raises twine.exceptions.UploadToDeprecatedPyPIDetected:
+            The configured repository URL is for legacy PyPI.
         """
         repository_url = cast(str, self.repository_config["repository"])
 

twine/utils.py

@@ -212,25 +212,27 @@ def get_userpass_value(
     key: str,
     prompt_strategy: Optional[Callable[[], str]] = None,
 ) -> Optional[str]:
-    """Get the username / password from config.
+    """Get a credential (e.g. a username or password) from the configuration.
 
     Uses the following rules:
 
-    1. If it is specified on the cli (`cli_value`), use that.
-    2. If `config[key]` is specified, use that.
-    3. If `prompt_strategy`, prompt using `prompt_strategy`.
-    4. Otherwise return None
-
-    :param cli_value: The value supplied from the command line or `None`.
-    :type cli_value: unicode or `None`
-    :param config: Config dictionary
-    :type config: dict
-    :param key: Key to find the config value.
-    :type key: unicode
-    :prompt_strategy: Argumentless function to return fallback value.
-    :type prompt_strategy: function
-    :returns: The value for the username / password
-    :rtype: unicode
+    1. If ``cli_value`` is specified, use that.
+    2. If ``config[key]`` is specified, use that.
+    3. If ``prompt_strategy`` is specified, use its return value.
+    4. Otherwise return ``None``
+
+    :param cli_value:
+        The value supplied from the command line.
+    :param config:
+        A dictionary of repository configuration values.
+    :param key:
+        The credential to look up in ``config``, e.g. ``"username"`` or ``"password"``.
+    :param prompt_strategy:
+        An argumentless function to get the value, e.g. from keyring or by prompting
+        the user.
+
+    :return:
+        The credential value, i.e. the username or password.
     """
     if cli_value is not None:
         logger.info(f"{key} set by command options")
@@ -244,7 +246,10 @@ def get_userpass_value(
         return None
 
 
+#: Get the CA bundle via :func:`get_userpass_value`.
 get_cacert = functools.partial(get_userpass_value, key="ca_cert")
+
+#: Get the client certificate via :func:`get_userpass_value`.
 get_clientcert = functools.partial(get_userpass_value, key="client_cert")