Adding missing docstrings to twine/commands

twine/commands/check.py

@@ -1,3 +1,7 @@
+"""Module containing the check function in twine.
+This module checks file(s) that users are going to
+upload, and raises warnings when errors occurred.
+"""
 # Copyright 2018 Dustin Ingram
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -70,7 +74,6 @@ def __str__(self) -> str:
 def _check_file(
     filename: str, render_warning_stream: _WarningStream
 ) -> Tuple[List[str], bool]:
-    """Check given distribution."""
     warnings = []
     is_ok = True
 
@@ -106,6 +109,26 @@ def check(
     output_stream: IO[str] = sys.stdout,
     strict: bool = False,
 ) -> bool:
+    """Check the file(s) given by user.
+
+    If there are no files to check, False is returned with a output.
+
+    If the check is failed, error text is given and failure = True is returned.
+
+    If strict is set to True by user, the check will fail when there are warnings.
+    Otherwise, the check will pass with warnings.
+
+    If the check is passed, message for passing the check is given
+    and failure = False is returned.
+
+    Args:
+        dists (List[str]): the distribution files we are going to check
+        output_stream (IO[str], optional): Output stream of the check. Defaults to sys.stdout.
+        strict (bool, optional): Strict mode for the check. Defaults to False.
+
+    Returns:
+        bool: Determine whether the check has passed.
+    """    
     uploads = [i for i in commands._find_dists(dists) if not i.endswith(".asc")]
     if not uploads:  # Return early, if there are no files to check.
         output_stream.write("No files to check.\n")
@@ -146,6 +169,14 @@ def check(
 
 
 def main(args: List[str]) -> bool:
+    """Entry-point of check command.
+
+    Args:
+        args (List[str]): Arguments for the check command.
+
+    Returns:
+        bool: The result of the check function.
+    """
     parser = argparse.ArgumentParser(prog="twine check")
     parser.add_argument(
         "dists",

twine/commands/register.py

@@ -1,3 +1,6 @@
+"""Module containing the register function in twine.
+This module registers the package to the repository.
+"""
 # Copyright 2015 Ian Cordasco
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,6 +24,15 @@
 
 
 def register(register_settings: settings.Settings, package: str) -> None:
+    """Register package to repository.
+
+    Raises:
+        :class:`exceptions.PackageNotFound`: If the package is not existing.
+        :class:`exceptions.RedirectDetected.from_args`: If we get a redirect.
+
+    Finally, it raises for status. If error is occurred, it will print
+    a error message in verbose output.
+    """
     repository_url = cast(str, register_settings.repository_config["repository"])
     print(f"Registering package to {repository_url}")
     repository = register_settings.create_repository()
@@ -45,6 +57,11 @@ def register(register_settings: settings.Settings, package: str) -> None:
 
 
 def main(args: List[str]) -> None:
+    """Entry-point of register command.
+
+    Args:
+        args (List[str]): Arguments for the register command.
+    """
     parser = argparse.ArgumentParser(
         prog="twine register",
         description="register operation is not required with PyPI.org",

twine/commands/upload.py

@@ -1,3 +1,6 @@
+"""Module containing the upload function in twine.
+This module uploads the package to the repository.
+"""
 # Copyright 2013 Donald Stufft
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -30,6 +33,20 @@
 def skip_upload(
     response: requests.Response, skip_existing: bool, package: package_file.PackageFile
 ) -> bool:
+    """Return Boolean type(True or False) according to the status code that returned by
+    the repository when uploading the package to determine whether they should be uploaded.
+
+    If skip_existing is set to True, then return False.
+    If status code 400, 403, 409 is responded by the repository, return True.
+
+    Args:
+        response (requests.Response): Get the response from the repository.
+        skip_existing (bool): If this is set to True, then return False.
+        package (package_file.PackageFile): Get the package files.
+
+    Returns:
+        bool: Determine whether we should skip uploading the package.
+    """ 
     if not skip_existing:
         return False
 
@@ -57,7 +74,6 @@ def skip_upload(
 def _make_package(
     filename: str, signatures: Dict[str, str], upload_settings: settings.Settings
 ) -> package_file.PackageFile:
-    """Create and sign a package, based off of filename, signatures and settings."""
     package = package_file.PackageFile.from_filename(filename, upload_settings.comment)
 
     signed_name = package.signed_basefilename
@@ -75,6 +91,31 @@ def _make_package(
 
 
 def upload(upload_settings: settings.Settings, dists: List[str]) -> None:
+    """Upload distributions to repository.
+
+    This function will check if the user has passed in pre-signed distributions.
+    Then, it will check the repository url to verify that we are not using legacy
+    PyPI. If no error is occurred, it will make package, create repository and
+    upload distributions.
+
+    If skip_existing is set to True and the package is uploaded already,
+    it prints the skipping message to the user and continues uploading distributions.
+
+    If we get a redirect, exception :class:`RedirectDetected` is raised.
+
+    If skip_upload is True, it prints the skipping message to the user and continues
+    uploading distributions.
+
+    Then, it will check status code responded by the repository, and generate 
+    a helpful message. After that, it will add the distribution files uploaded to
+    the uploaded_packages.
+
+    Finally, it will show release urls to the user and close the session.
+
+    Args:
+        upload_settings(settings.Settings): The settings for the upload function.
+        dists(List[str]):  Get dists that are going to be uploaded.
+    """
     dists = commands._find_dists(dists)
     # Determine if the user has passed in pre-signed distributions
     signatures = {os.path.basename(d): d for d in dists if d.endswith(".asc")}
@@ -135,6 +176,11 @@ def upload(upload_settings: settings.Settings, dists: List[str]) -> None:
 
 
 def main(args: List[str]) -> None:
+    """Entry-point of upload command.
+
+    Args:
+        args (List[str]): Arguments for the upload command.
+    """
     parser = argparse.ArgumentParser(prog="twine upload")
     settings.Settings.register_argparse_arguments(parser)
     parser.add_argument(