From 3be41f65176a4ee4909b3307d3705f670dfb0330 Mon Sep 17 00:00:00 2001 From: meowmeowcat Date: Mon, 20 Sep 2021 09:29:05 +0800 Subject: [PATCH] Adding missing docstrings to `twine/commands` (#799) * Add missing docstrings * Better docstrings * Better docstrings * Remove `twine/commands/*` * Use reStructuredText style * Fix linting error * Fix a typo Co-authored-by: Ian Stapleton Cordasco * Use reStructuredText/Sphinx directive * Remove types from params * Update high-level command docstrings * Rewrite check docstring * Rewrite register docstring * Rewrite skip_existing docstring * Rewrite upload docstring * Simplify exceptions * Restore deleted docstrings Co-authored-by: Ian Stapleton Cordasco Co-authored-by: Brian Rutledge --- .flake8 | 1 - twine/commands/__init__.py | 5 +++++ twine/commands/check.py | 24 +++++++++++++++++++++++ twine/commands/register.py | 21 ++++++++++++++++++++ twine/commands/upload.py | 40 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 90 insertions(+), 1 deletion(-) diff --git a/.flake8 b/.flake8 index e09bd27e..32c14c0b 100644 --- a/.flake8 +++ b/.flake8 @@ -13,5 +13,4 @@ per-file-ignores = # D103 Missing docstring in public function # D104 Missing docstring in public package twine/*: D100,D101,D102,D103,D104 - twine/commands/*: D100,D101,D102,D103,D104 tests/*: D100,D101,D102,D103,D104 diff --git a/twine/commands/__init__.py b/twine/commands/__init__.py index 87e83fcc..080bae3e 100644 --- a/twine/commands/__init__.py +++ b/twine/commands/__init__.py @@ -1,3 +1,8 @@ +"""Module containing the logic for the ``twine`` sub-commands. + +The contents of this package are not a public API. For more details, see +https://github.com/pypa/twine/issues/194 and https://github.com/pypa/twine/issues/665. +""" # Copyright 2013 Donald Stufft # # Licensed under the Apache License, Version 2.0 (the "License"); diff --git a/twine/commands/check.py b/twine/commands/check.py index 53a2069c..246511d8 100644 --- a/twine/commands/check.py +++ b/twine/commands/check.py @@ -1,3 +1,4 @@ +"""Module containing the logic for ``twine check``.""" # Copyright 2018 Dustin Ingram # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -106,6 +107,21 @@ def check( output_stream: IO[str] = sys.stdout, strict: bool = False, ) -> bool: + """Check that a distribution will render correctly on PyPI and display the results. + + This is currently only validates ``long_description``, but more checks could be + added; see https://github.com/pypa/twine/projects/2. + + :param dists: + The distribution files to check. + :param output_stream: + The destination of the resulting output. + :param strict: + If ``True``, treat warnings as errors. + + :return: + ``True`` if there are rendering errors, otherwise ``False``. + """ 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 +162,14 @@ def check( def main(args: List[str]) -> bool: + """Execute the ``check`` command. + + :param args: + The command-line arguments. + + :return: + The exit status of the ``check`` command. + """ parser = argparse.ArgumentParser(prog="twine check") parser.add_argument( "dists", diff --git a/twine/commands/register.py b/twine/commands/register.py index e3cdf0be..19a6c3e2 100644 --- a/twine/commands/register.py +++ b/twine/commands/register.py @@ -1,3 +1,4 @@ +"""Module containing the logic for ``twine register``.""" # Copyright 2015 Ian Cordasco # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -21,6 +22,21 @@ def register(register_settings: settings.Settings, package: str) -> None: + """Pre-register a package name with a repository before uploading a distribution. + + Pre-registration is not supported on PyPI, so the ``register`` command is only + necessary if you are using a different repository that requires it. + + :param register_settings: + The configured options relating to repository registration. + :param package: + The path of the distribution to use for package metadata. + + :raises twine.exceptions.TwineException: + The registration failed due to a configuration error. + :raises requests.HTTPError: + The repository responded with an error. + """ repository_url = cast(str, register_settings.repository_config["repository"]) print(f"Registering package to {repository_url}") repository = register_settings.create_repository() @@ -45,6 +61,11 @@ def register(register_settings: settings.Settings, package: str) -> None: def main(args: List[str]) -> None: + """Execute the ``register`` command. + + :param args: + The command-line arguments. + """ parser = argparse.ArgumentParser( prog="twine register", description="register operation is not required with PyPI.org", diff --git a/twine/commands/upload.py b/twine/commands/upload.py index 3ac2ccb5..99d19f70 100644 --- a/twine/commands/upload.py +++ b/twine/commands/upload.py @@ -1,3 +1,4 @@ +"""Module containing the logic for ``twine upload``.""" # Copyright 2013 Donald Stufft # # Licensed under the Apache License, Version 2.0 (the "License"); @@ -30,6 +31,20 @@ def skip_upload( response: requests.Response, skip_existing: bool, package: package_file.PackageFile ) -> bool: + """Determine if a failed upload is an error or can be safely ignored. + + :param response: + The response from attempting to upload ``package`` to a repository. + :param skip_existing: + If ``True``, use the status and content of ``response`` to determine if the + package already exists on the repository. If so, then a failed upload is safe + to ignore. + :param package: + The package that was being uploaded. + + :return: + ``True`` if a failed upload can be safely ignored, otherwise ``False``. + """ if not skip_existing: return False @@ -75,6 +90,26 @@ def _make_package( def upload(upload_settings: settings.Settings, dists: List[str]) -> None: + """Upload one or more distributions to a repository, and display the progress. + + If a package already exists on the repository, most repositories will return an + error response. However, if ``upload_settings.skip_existing`` is ``True``, a message + will be displayed and any remaining distributions will be uploaded. + + For known repositories (like PyPI), the web URLs of successfully uploaded packages + will be displayed. + + :param upload_settings: + The configured options related to uploading to a repository. + :param dists: + The distribution files to upload to the repository. This can also include + ``.asc`` files; the GPG signatures will be added to the corresponding uploads. + + :raises twine.exceptions.TwineException: + The upload failed due to a configuration error. + :raises requests.HTTPError: + The repository responded with an error. + """ 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 +170,11 @@ def upload(upload_settings: settings.Settings, dists: List[str]) -> None: def main(args: List[str]) -> None: + """Execute the ``upload`` command. + + :param args: + The command-line arguments. + """ parser = argparse.ArgumentParser(prog="twine upload") settings.Settings.register_argparse_arguments(parser) parser.add_argument(