Upgrade docformatter to 1.7.0 to support Python 3.13

.git-blame-ignore-revs

@@ -15,3 +15,6 @@ dc8227b9841a1057b6ca8629c430f072dd9a190f
 
 # This commit formatted all Rust code
 3632a66bc7918ace25c0aa6f05b4b6a4253d908e
+
+# This commit ran docformatter over the whole codebase.
+ce5abb018207202bf9b80583890a6d85dfc2be47

docs/notes/2.24.x.md

@@ -17,7 +17,7 @@ We offer [formal sponsorship tiers for companies](https://www.pantsbuild.org/spo
 ### Deprecations
 
 - **Python 2.7**: As announced in the v2.23.x release series, Pants v2.24 and later are not proactively tested in CI with Python 2.7 since [Python 2.7 is no longer supported by its maintainers as of 1 January 2020](https://www.python.org/doc/sunset-python-2/). While Pants may continue to work with Python 2.7 in the near term, Pants no longer officially supports use of Python 2.7, and, consequently, any remaining support for Python 2.7 may "bit rot" and diverge over time. Contributions to fix issues with Python 2.7 support will continue to be accepted, but will depend on any community contributions and will not constitute continued official support for Python 2.7.
-- **macOS verisons**: as announced in the v2.23.x release series, Pants v2.24 is built on macOS 12 and so may not work on versions of macOS 10.15 and 11 (which Apple no longer supports).
+- **macOS versions**: as announced in the v2.23.x release series, Pants v2.24 is built on macOS 12 and so may not work on versions of macOS 10.15 and 11 (which Apple no longer supports).
 
 
 ### General
@@ -79,6 +79,8 @@ Version Updates:
 
 - The default version of the [Pyright](https://microsoft.github.io/pyright/#/) tool has been updated from 1.1.365 to [1.1.383](https://github.com/microsoft/pyright/releases/tag/1.1.383).
 
+- The default version of the [docformatter](https://github.com/PyCQA/docformatter) tool has been updated from 1.4 to 1.7.0. This adds support for Python 3.13.
+
 
 A new experimental [Python Provider](https://www.pantsbuild.org/blog/2023/03/31/two-hermetic-pythons) using [Python Build Standalone](https://gregoryszorc.com/docs/python-build-standalone/main/) is available as `pants.backend.python.providers.experimental.python_build_standalone`.  This joins the existing [pyenv provider](https://www.pantsbuild.org/stable/reference/subsystems/pyenv-python-provider) as a way for Pants to take care of providing an appropriate Python.
 

src/python/pants/backend/awslambda/python/register.py

@@ -1,6 +1,5 @@
 # Copyright 2019 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Create AWS Lambdas from Python code.
 
 See https://www.pantsbuild.org/docs/awslambda-python.

src/python/pants/backend/cc/lint/clangformat/subsystem.py

@@ -38,7 +38,7 @@ class ClangFormat(PythonToolBase):
     default_lockfile_resource = ("pants.backend.cc.lint.clangformat", "clangformat.lock")
 
     def config_request(self, dirs: Iterable[str]) -> ConfigFilesRequest:
-        """clang-format will use the closest configuration file to the file currently being
+        """Clang-format will use the closest configuration file to the file currently being
         formatted, so add all of them."""
         config_files = (
             ".clang-format",

src/python/pants/backend/codegen/protobuf/python/register.py

@@ -1,6 +1,5 @@
 # Copyright 2020 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Generate Python sources from Protocol Buffers (Protobufs).
 
 See https://www.pantsbuild.org/docs/protobuf.

src/python/pants/backend/docker/goals/package_image.py

@@ -152,12 +152,12 @@ def image_refs(
         separated with a colon. By introducing the image `ref` we can retain the use of `tag` for
         the version part of the image name.
 
-        This function returns all image refs to apply to the Docker image, grouped by
-        registry. Within each registry, the `tags` attribute contains a metadata about each tag in
-        the context of that registry, and the `full_name` attribute of each `ImageRefTag` provides
-        the image ref, of the following form:
+        This function returns all image refs to apply to the Docker image, grouped by registry.
+        Within each registry, the `tags` attribute contains a metadata about each tag in the context
+        of that registry, and the `full_name` attribute of each `ImageRefTag` provides the image
+        ref, of the following form:
 
-            [<registry>/]<repository-name>[:<tag>]
+        [<registry>/]<repository-name>[:<tag>]
 
         Where the `<repository-name>` may contain any number of separating slashes `/`, depending on
         the `default_repository` from configuration or the `repository` field on the target

src/python/pants/backend/experimental/cc/lint/clangformat/register.py

@@ -1,6 +1,5 @@
 # Copyright 2022 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """A formatter for C/C++ (and several other languages).
 
 See https://clang.llvm.org/docs/ClangFormat.html for details.

src/python/pants/backend/experimental/javascript/lint/prettier/register.py

@@ -1,6 +1,5 @@
 # Copyright 2022 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """A formatter for JS/TS (and several other languages).
 
 See https://prettier.io/ for details.

src/python/pants/backend/experimental/nfpm/register.py

@@ -1,6 +1,5 @@
 # Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Create apk, archlinux, deb, and rpm system packages.
 
 See https://nfpm.goreleaser.com/ for details on nFPM, including these descriptions of it:

src/python/pants/backend/experimental/python/framework/stevedore/register.py

@@ -1,6 +1,5 @@
 # Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """A python "framework" for apps to dynamically load plugins.
 
 See https://github.com/openstack/stevedore for details.

src/python/pants/backend/experimental/python/lint/add_trailing_comma/register.py

@@ -1,6 +1,5 @@
 # Copyright 2022 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Autoformatter to automatically add trailing commas to calls and literals.
 
 See https://github.com/asottile/add-trailing-comma for details.

src/python/pants/backend/experimental/python/lint/ruff/check/register.py

@@ -1,6 +1,5 @@
 # Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Linter & formatter for Python.
 
 See https://www.pantsbuild.org/docs/python-linters-and-formatters and https://docs.astral.sh/ruff/

src/python/pants/backend/experimental/python/lint/ruff/format/register.py

@@ -1,6 +1,5 @@
 # Copyright 2024 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Linter & formatter for Python.
 
 See https://www.pantsbuild.org/docs/python-linters-and-formatters and https://docs.astral.sh/ruff/

src/python/pants/backend/experimental/python/typecheck/pyright/register.py

@@ -1,6 +1,5 @@
 # Copyright 2022 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Static type checker for Python, running on NodeJS.
 
 See https://github.com/Microsoft/pyright for details.

src/python/pants/backend/experimental/tools/semgrep/register.py

@@ -1,6 +1,5 @@
 # Copyright 2023 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Lightweight static analysis for many languages. Find bug variants with patterns that look like
 source code.
 

src/python/pants/backend/experimental/tools/yamllint/register.py

@@ -1,6 +1,5 @@
 # Copyright 2022 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """A configurable linter for YAML files.
 
 See https://yamllint.readthedocs.io/ for details.

src/python/pants/backend/google_cloud_function/python/register.py

@@ -1,6 +1,5 @@
 # Copyright 2019 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Create Google Cloud Functions from Python code.
 
 See https://www.pantsbuild.org/docs/google-cloud-function-python.

src/python/pants/backend/helm/util_rules/renderer.py

@@ -97,7 +97,8 @@ class _HelmDeploymentProcessWrapper(EngineAwareParameter, EngineAwareReturnType)
     """Intermediate representation of a `HelmProcess` that will produce a fully rendered set of
     manifests from a given chart.
 
-    The encapsulated `process` will be side-effecting depending on the `cmd` that was originally requested.
+    The encapsulated `process` will be side-effecting depending on the `cmd` that was originally
+    requested.
 
     This is meant to only be used internally by this module.
     """

src/python/pants/backend/helm/utils/yaml.py

@@ -215,8 +215,8 @@ def transform_values(self, func: Callable[[T], Optional[R]]) -> FrozenYamlIndex[
 
         The items that map to `None` in the given function are not included in the result.
 
-        This is a combination of the `map` and `filter` higher-order functions into one so
-        both operations are performed in a single pass.
+        This is a combination of the `map` and `filter` higher-order functions into one so both
+        operations are performed in a single pass.
         """
 
         mutable_index: MutableYamlIndex[R] = MutableYamlIndex()

src/python/pants/backend/java/compile/javac_test.py

@@ -310,16 +310,16 @@ def test_compile_with_cycle(rule_runner: RuleRunner) -> None:
     """Test that javac can handle source-level cycles--even across build target boundaries--via
     graph coarsening.
 
-    This test has to set up a contrived dependency since build-target cycles are forbidden by the graph.  However,
-    file-target cycles are not forbidden, so we configure the graph like so:
+    This test has to set up a contrived dependency since build-target cycles are forbidden by the
+    graph.  However, file-target cycles are not forbidden, so we configure the graph like so:
 
     a:a has a single source file, which has file-target address a/A.java, and which inherits a:a's
-    explicit dependency on b/B.java.
-    b:b depends directly on a:a, and its source b/B.java inherits that dependency.
+    explicit dependency on b/B.java. b:b depends directly on a:a, and its source b/B.java inherits
+    that dependency.
 
     Therefore, after target expansion via Get(Targets, Addresses(...)), we get the cycle of:
 
-        a/A.java -> b/B.java -> a/A.java
+    a/A.java -> b/B.java -> a/A.java
     """
 
     rule_runner.write_files(

src/python/pants/backend/project_info/count_loc_test.py

@@ -84,7 +84,7 @@ def test_passthrough_args(rule_runner: RuleRunner) -> None:
 
 
 def test_files_without_owners(rule_runner: RuleRunner) -> None:
-    """cloc works on any readable file in the build root, regardless of whether it's declared in a
+    """Cloc works on any readable file in the build root, regardless of whether it's declared in a
     BUILD file."""
     rule_runner.write_files(
         {

src/python/pants/backend/project_info/register.py

@@ -1,6 +1,5 @@
 # Copyright 2014 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Information on your project, such as listing the targets in your project."""
 
 from pants.backend.project_info import (

src/python/pants/backend/python/dependency_inference/default_module_mapping.py

@@ -52,7 +52,7 @@ def two_groups_hyphens_two_replacements_with_suffix(
     second_group_replacement: PackageSeparator = PackageSeparator.NONE,
     custom_suffix: str = "",
 ) -> str:
-    """take two groups, and by default, the first will have '-' replaced with '.', the second will
+    """Take two groups, and by default, the first will have '-' replaced with '.', the second will
     have '-' replaced with '' e.g. google-cloud-foo-bar -> group1(google.cloud.)group2(foobar)
 
     >>> two_groups_hyphens_two_replacements_with_suffix(re.match(r"^(google-cloud-)([^.]+)", "google-cloud-foo-bar"))
@@ -74,14 +74,12 @@ def two_groups_hyphens_two_replacements_with_suffix(
 first_group_hyphen_to_underscore = partial(
     first_group_hyphen_to_separator, separator=PackageSeparator.UNDERSCORE
 )
+"""A mapping of Patterns and their replacements. will be used with `re.sub`. The match is either a
+string or a function`(str) -> str`; that takes a re.Match and returns the replacement. see re.sub
+for more information.
 
-"""
-A mapping of Patterns and their replacements. will be used with `re.sub`.
-The match is either a string or a function`(str) -> str`; that takes a re.Match and returns
-the replacement. see re.sub for more information
-
-then if an import in the python code is google.cloud.foo, then the package of
-google-cloud-foo will be used.
+then if an import in the python code is google.cloud.foo, then the package of google-cloud-foo will
+be used.
 """
 DEFAULT_MODULE_PATTERN_MAPPING: Dict[re.Pattern, List[Callable[[Match[str]], str]]] = {
     re.compile(r"""^azure-.+"""): [all_hyphen_to_dot],

src/python/pants/backend/python/dependency_inference/module_mapper.py

@@ -145,7 +145,6 @@ class FirstPartyPythonModuleMapping:
     resolves_to_modules_to_providers: FrozenDict[
         ResolveName, FrozenDict[str, Tuple[ModuleProvider, ...]]
     ]
-
     """A merged mapping of each resolve name to the first-party module names contained and their
     owning addresses.
 

src/python/pants/backend/python/dependency_inference/rules.py

@@ -210,12 +210,7 @@ def _remove_ignored_imports(
 ) -> frozenset[str]:
     """Remove unowned imports given a list of paths to ignore.
 
-    E.g. having
-    ```
-    import foo.bar
-    from foo.bar import baz
-    import foo.barley
-    ```
+    E.g. having ``` import foo.bar from foo.bar import baz import foo.barley ```
 
     and passing `ignored-paths=["foo.bar"]`, only `foo.bar` and `foo.bar.baz` will be ignored.
     """

src/python/pants/backend/python/lint/autoflake/register.py

@@ -1,6 +1,5 @@
 # Copyright 2021 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Autoformatter for removing unused Python imports.
 
 See https://github.com/myint/autoflake for details.

src/python/pants/backend/python/lint/bandit/register.py

@@ -1,6 +1,5 @@
 # Copyright 2020 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Security linter for Python.
 
 See https://www.pantsbuild.org/docs/python-linters-and-formatters and

src/python/pants/backend/python/lint/black/register.py

@@ -1,6 +1,5 @@
 # Copyright 2019 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
-
 """Autoformatter for Python.
 
 See https://www.pantsbuild.org/docs/python-linters-and-formatters and