Bump docformatter from v1.7.7 to v1.7.8

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/PyCQA/docformatter
-    rev: v1.7.7
+    rev: v1.7.8
     hooks:
       - id: docformatter
         args: [--in-place, --black]

changes/2815.misc.md

@@ -0,0 +1 @@
+The `pre-commit` hook for `docformatter` was updated to its latest version.

debugger/setup.py

@@ -9,11 +9,11 @@
 class install_with_pth(install):
     """Custom install command to install a .pth file for distutils patching.
 
-    This hack is necessary because there's no standard way to install behavior
-    on startup (and it's debatable if there should be one). This hack (ab)uses
-    the `extra_path` behavior in Setuptools to install a `.pth` file with
-    implicit behavior on startup to give higher precedence to the local version
-    of `distutils` over the version from the standard library.
+    This hack is necessary because there's no standard way to install behavior on
+    startup (and it's debatable if there should be one). This hack (ab)uses the
+    `extra_path` behavior in Setuptools to install a `.pth` file with implicit behavior
+    on startup to give higher precedence to the local version of `distutils` over the
+    version from the standard library.
 
     Please do not replicate this behavior.
     """

src/briefcase/bootstraps/console.py

@@ -22,12 +22,10 @@ def main():
 """
 
     def app_start_source(self):
-        return """\
-from {{ cookiecutter.module_name }}.app import main
+        return r"""\ from {{ cookiecutter.module_name }}.app import main.
 
-if __name__ == "__main__":
-    main()
-"""
+               if __name__ == "__main__":     main()
+               """
 
     def pyproject_table_briefcase_app_extra_content(self):
         return """

src/briefcase/bootstraps/empty.py

@@ -13,12 +13,10 @@ def main():
 """
 
     def app_start_source(self):
-        return """\
-from {{ cookiecutter.module_name }}.app import main
+        return r"""\ from {{ cookiecutter.module_name }}.app import main.
 
-if __name__ == "__main__":
-    main()
-"""
+               if __name__ == "__main__":     main()
+               """
 
     def pyproject_table_briefcase_app_extra_content(self):
         return """

src/briefcase/bootstraps/toga.py

@@ -28,12 +28,10 @@ def main():
 '''
 
     def app_start_source(self):
-        return """\
-from {{ cookiecutter.module_name }}.app import main
+        return r"""\ from {{ cookiecutter.module_name }}.app import main.
 
-if __name__ == "__main__":
-    main().main_loop()
-"""
+               if __name__ == "__main__":     main().main_loop()
+               """
 
     def pyproject_table_briefcase_app_extra_content(self):
         return """

src/briefcase/channels/base.py

@@ -14,8 +14,8 @@
 class PublishCommandAPI(Protocol):
     """Stable API surface exposed to publication channel plugins.
 
-    This defines the minimal set of attributes and methods that a plugin
-    can rely on from the ``command`` parameter passed to ``publish_app()``.
+    This defines the minimal set of attributes and methods that a plugin can rely on
+    from the ``command`` parameter passed to ``publish_app()``.
     """
 
     console: Console

src/briefcase/commands/base.py

@@ -79,8 +79,8 @@ def full_options(state, options):
 
     :param state: The current command state. Can be ``None``.
     :param options: The base options.
-    :returns: A dictionary containing all of ``options``, with any values
-        provided in ``state`` overriding the base ``options`` values.
+    :returns: A dictionary containing all of ``options``, with any values provided in
+        ``state`` overriding the base ``options`` values.
     """
     if state is not None:
         full = options.copy()
@@ -446,7 +446,6 @@ def unbuilt_executable_path(self, app) -> Path:
 
         :param app: The app config
         """
-
         if sys.platform == "win32":  # pragma: no-cover-if-not-windows
             suffix = self.binary_executable_path(app).suffix
         else:  # pragma: no-cover-if-is-windows
@@ -691,8 +690,8 @@ def finalize_app_config(self, app: DraftAppConfig, **kwargs) -> FinalizedAppConf
         configuration, and performs any other app-specific platform configuration and
         verification that is required as a result of command-line arguments.
 
-        Platform overrides should call ``super().finalize_app_config(app, **kwargs)``
-        to construct the ``FinalizedAppConfig``.
+        Platform overrides should call ``super().finalize_app_config(app, **kwargs)`` to
+        construct the ``FinalizedAppConfig``.
 
         :param app: The app configuration to finalize.
         :param kwargs: Runtime attributes forwarded to the FinalizedAppConfig
@@ -812,7 +811,6 @@ def verify_app_template(self, app: FinalizedAppConfig):
 
         :param app: app configuration
         """
-
         # Skip this check if the template isn't rolled out
         # or if the command doesn't support templates
         try:
@@ -841,7 +839,6 @@ def verify_app_template(self, app: FinalizedAppConfig):
     def verify_required_python(self, app: FinalizedAppConfig):
         """Verify that the running version of Python meets the project's
         specifications."""
-
         requires_python = getattr(self.global_config, "requires_python", None)
         if not requires_python:
             return
@@ -1149,8 +1146,8 @@ def update_cookiecutter_cache(self, template: str, branch="master"):
 
         :param template: The template URL or path.
         :param branch: The template branch to use. Default: ``master``
-        :return: The path to the cached template. This may be the originally
-            provided path if the template was a file path.
+        :return: The path to the cached template. This may be the originally provided
+            path if the template was a file path.
         """
         if is_repo_url(template):
             # The app template is a repository URL.
@@ -1235,17 +1232,17 @@ def update_cookiecutter_cache(self, template: str, branch="master"):
                     # warn the user that the template may be stale.
                     self.console.debug(str(e))
                     self.console.warning(
-                        """
-*************************************************************************
-** WARNING: Unable to update template                                  **
-*************************************************************************
+                        """*************************************************************
+                        ************ ** WARNING: Unable to update template
+                        ** *************************************************************
+                        ************
 
-    Briefcase is unable the update the application template. This
-    may be because your computer is currently offline. Briefcase will
-    use existing template without updating.
+                            Briefcase is unable the update the application template. This
+                            may be because your computer is currently offline. Briefcase will
+                            use existing template without updating.
 
-*************************************************************************
-"""
+                        *************************************************************************
+                        """
                     )
 
                 try:

src/briefcase/commands/build.py

@@ -32,6 +32,7 @@ def build_app(self, app: FinalizedAppConfig, **options):
 
         :param app: The application to build
         """
+
         # Default implementation; nothing to build.
 
     def _build_app(
@@ -45,9 +46,10 @@ def _build_app(
         no_update: bool,
         **options,
     ) -> dict | None:
-        """Internal method to invoke a build on a single app. Ensures the app exists,
-        and has been updated (if requested) before attempting to issue the actual build
-        command.
+        """Internal method to invoke a build on a single app.
+
+        Ensures the app exists, and has been updated (if requested) before attempting to
+        issue the actual build command.
 
         :param app: The application to build
         :param update: Should the application be updated before building?

src/briefcase/commands/convert.py

@@ -722,12 +722,10 @@ def convert_app(
             prefix=context["app_name"],
         )
         self.console.info(
-            """
-To run your application, type:
-
-    $ briefcase dev
+            """To run your application, type:
 
-"""
+            $ briefcase dev
+            """
         )
 
     def validate_pyproject_file(self) -> None:

src/briefcase/commands/create.py

@@ -36,8 +36,7 @@ def cookiecutter_cache_path(template):
 
     This will return a valid path, regardless of whether `template`
 
-    :param template: The template to use. This can be a filesystem path or
-        a URL.
+    :param template: The template to use. This can be a filesystem path or a URL.
     :returns: The path that cookiecutter would use for the given template name.
     """
     template = template.rstrip("/")
@@ -191,8 +190,8 @@ def _x_permissions(self, app: FinalizedAppConfig):
         """Extract the known cross-platform permission definitions from the app's
         permissions definitions.
 
-        After calling this method, the ``permissions`` declaration for the app will
-        only contain keys that are *not* cross-platform keys.
+        After calling this method, the ``permissions`` declaration for the app will only
+        contain keys that are *not* cross-platform keys.
 
         :param app: The config object for the app
         :returns: A dictionary of known cross-platform permission definitions.
@@ -548,7 +547,6 @@ def _write_requirements_file(
             additional requirement installer argumentss should be written if the
             template supports it.
         """
-
         with self.console.wait_bar("Writing requirements file..."):
             with requirements_path.open("w", encoding="utf-8") as f:
                 # Add timestamp so build systems (such as Gradle) detect a change

src/briefcase/commands/dev.py

@@ -102,7 +102,6 @@ def install_dev_requirements(
         :param venv: The context object used to run commands inside the virtual
             environment.
         """
-
         requires = app.requires or []
         if app.test_requires:
             requires.extend(app.test_requires)
@@ -214,7 +213,6 @@ def get_environment(self, app: FinalizedAppConfig):
 
         :param app: The config object for the app
         """
-
         env = {
             "PYTHONPATH": os.pathsep.join(
                 os.fsdecode(Path.cwd() / path) for path in app.PYTHONPATH()
@@ -237,10 +235,9 @@ def get_environment(self, app: FinalizedAppConfig):
     def venv_name(self) -> str:
         """Returns the name of the virtual environment directory.
 
-        The environment name is platform and Python version specific, so
-        that multiple OSes and Python versions can share a `.briefcase`
-        folder. The name is based on the extension module filename that the
-        platform uses (e.g., cpython-313-darwin).
+        The environment name is platform and Python version specific, so that multiple
+        OSes and Python versions can share a `.briefcase` folder. The name is based on
+        the extension module filename that the platform uses (e.g., cpython-313-darwin).
 
         :returns: Name for virtual environment directory
         """

src/briefcase/commands/new.py

@@ -475,7 +475,6 @@ def build_gui_context(
         project_overrides: dict[str, str],
     ) -> dict[str, str]:
         """Build context specific to the GUI toolkit."""
-
         gui_context = {}
 
         # Iterate over the Bootstrap interface to build the context.

src/briefcase/commands/package.py

@@ -62,6 +62,7 @@ def package_app(self, app: FinalizedAppConfig, **options):
 
         :param app: The application to package
         """
+
         # Default implementation; nothing to do.
 
     def _package_app(
@@ -71,9 +72,10 @@ def _package_app(
         packaging_format: str,
         **options,
     ) -> dict | None:
-        """Internal method to invoke packaging on a single app. Ensures the app exists,
-        and has been updated (if requested) before attempting to issue the actual
-        package command.
+        """Internal method to invoke packaging on a single app.
+
+        Ensures the app exists, and has been updated (if requested) before attempting to
+        issue the actual package command.
 
         :param app: The application to package
         :param update: Should the application be updated (and rebuilt) first?

src/briefcase/commands/run.py

@@ -148,16 +148,16 @@ def _stream_app_logs(
         :param app: The app to be launched
         :param popen: The Popen object for the stream we are monitoring; this Popen
             process will be closed after log streaming completes.
-        :param clean_filter: The log cleaning filter to use; see ``LogFilter``
-            for details.
+        :param clean_filter: The log cleaning filter to use; see ``LogFilter`` for
+            details.
         :param clean_output: Should the cleaned output be presented to the user?
-        :param stop_func: (Optional) A function that will be invoked to determine
-            if the log stream should be terminated.
-        :param log_stream: Is this a log stream, rather than a literal app stream?
-            On some platforms (especially mobile), we monitor a log stream,
-            rather that the output of the app itself. If this case, the cleanup
-            process is different, as the reported exit status of the popen object
-            is of the log, not the app itself.
+        :param stop_func: (Optional) A function that will be invoked to determine if the
+            log stream should be terminated.
+        :param log_stream: Is this a log stream, rather than a literal app stream? On
+            some platforms (especially mobile), we monitor a log stream, rather that the
+            output of the app itself. If this case, the cleanup process is different, as
+            the reported exit status of the popen object is of the log, not the app
+            itself.
         """
         try:
             exit_filter = LogFilter.test_filter(

src/briefcase/commands/update.py

@@ -45,7 +45,6 @@ def update_app(
         :param update_support: Should app support be updated?
         :param update_stub: Should stub binary be updated?
         """
-
         if app.external_package_path:
             raise BriefcaseCommandError(
                 f"{app.app_name!r} is declared as an external app. External apps "