Merge pull request #1317 from beeware/autoupdates/pre-commit/docforma…

…tter

Bump docformatter from v1.7.0 to v1.7.2

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
       - id: pyupgrade
         args: [--py38-plus]
   - repo: https://github.com/PyCQA/docformatter
-    rev: v1.7.0
+    rev: v1.7.2
     hooks:
       - id: docformatter
         args: [--in-place, --black]

changes/1317.misc.rst

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

src/briefcase/commands/base.py

@@ -137,8 +137,9 @@ def __init__(
         :param apps: Dictionary of project's Apps keyed by app name.
         :param base_path: Base directory for Briefcase project.
         :param data_path: Base directory for Briefcase tools, support packages, etc.
-        :param is_clone: Flag that Command was triggered by the user's requested Command;
-            for instance, RunCommand can invoke UpdateCommand and/or BuildCommand.
+        :param is_clone: Flag that Command was triggered by the user's requested
+            Command; for instance, RunCommand can invoke UpdateCommand and/or
+            BuildCommand.
         """
         if base_path is None:
             self.base_path = Path.cwd()
@@ -312,11 +313,10 @@ def dist_path(self) -> Path:
     def bundle_path(self, app) -> Path:
         """The path to the bundle for the app in the output format.
 
-        The bundle is the template-generated source form of the app.
-        The path will usually be a directory, the existence of which is
-        indicative that the template has been rolled out for an app.
-        The leaf of this path is the base of the content generated from
-        template.
+        The bundle is the template-generated source form of the app. The path will
+        usually be a directory, the existence of which is indicative that the template
+        has been rolled out for an app. The leaf of this path is the base of the content
+        generated from template.
 
         :param app: The app config
         """
@@ -326,11 +326,10 @@ def bundle_path(self, app) -> Path:
     def binary_path(self, app) -> Path:
         """The path to the executable artefact for the app in the output format.
 
-        This may be a binary file produced by compilation; however, if
-        the output format doesn't require compilation, it may be the same
-        as the bundle path (assuming the bundle path is inherently
-        "executable"), or a path that reasonably represents the thing that can
-        be executed.
+        This may be a binary file produced by compilation; however, if the output format
+        doesn't require compilation, it may be the same as the bundle path (assuming the
+        bundle path is inherently "executable"), or a path that reasonably represents
+        the thing that can be executed.
 
         :param app: The app config
         """
@@ -400,8 +399,8 @@ def cleanup_paths(self, app: AppConfig) -> list[str]:
         prior to release.
 
         :param app: The config object for the app
-        :return: The list of path globs inside the app template that should
-            be cleaned up.
+        :return: The list of path globs inside the app template that should be cleaned
+            up.
         """
         return self.path_index(app, "cleanup_paths")
 
@@ -495,15 +494,13 @@ def finalize_app_config(self, app: AppConfig):
         """Finalize the application config.
 
         Some app configurations (notably, Linux system packages like .deb) have
-        configurations that are deeper than other platforms, because they need
-        to include components that are dependent on command-line arguments. They
-        may also require the existence of system tools to complete
-        configuration.
+        configurations that are deeper than other platforms, because they need to
+        include components that are dependent on command-line arguments. They may also
+        require the existence of system tools to complete configuration.
 
         The final app configuration merges those "deep" properties into the app
-        configuration, and performs any other app-specific platform
-        configuration and verification that is required as a result of
-        command-line arguments.
+        configuration, and performs any other app-specific platform configuration and
+        verification that is required as a result of command-line arguments.
 
         :param app: The app configuration to finalize.
         """
@@ -538,9 +535,9 @@ def finalize(self, app: AppConfig | None = None):
     def verify_app(self, app: AppConfig):
         """Verify the app is compatible and the app tools are available.
 
-        This is the last step of verification for a Command before running the
-        Command's business logic. It runs _after_ pre-requisite Commands have been
-        verified and run.
+        This is the last step of verification for a Command before running the Command's
+        business logic. It runs _after_ pre-requisite Commands have been verified and
+        run.
 
         :param app: app configuration
         """
@@ -584,11 +581,11 @@ def verify_app_template(self, app: AppConfig):
     def parse_options(self, extra):
         """Parse the command line arguments for the Command.
 
-        After the initial ArgumentParser runs to choose the Command for the
-        selected platform and format, a new ArgumentParser is created here to
-        parse the remaining command line arguments specific to the Command.
-        Additionally, the default options for disabling input, log verbosity,
-        and log saving are parsed out and saved to the Command.
+        After the initial ArgumentParser runs to choose the Command for the selected
+        platform and format, a new ArgumentParser is created here to parse the remaining
+        command line arguments specific to the Command. Additionally, the default
+        options for disabling input, log verbosity, and log saving are parsed out and
+        saved to the Command.
 
         :param extra: the remaining command line arguments after the initial
             ArgumentParser runs over the command line.
@@ -700,9 +697,8 @@ def _add_update_options(
         """Internal utility method for adding common update options.
 
         :param parser: The parser to which options should be added.
-        :param context_label: Label text that will be added to the end of the
-            help text to describe when the update will be applied (e.g., "before
-            building")
+        :param context_label: Label text that will be added to the end of the help text
+            to describe when the update will be applied (e.g., "before building")
         :param update: Should the --update and --no-update options be exposed?
         """
         if update:

src/briefcase/commands/build.py

@@ -38,10 +38,10 @@ def _build_app(
 
         :param app: The application to build
         :param update: Should the application be updated before building?
-        :param update_requirements: Should the application requirements be
-            updated before building?
-        :param update_resources: Should the application resources be updated
+        :param update_requirements: Should the application requirements be updated
             before building?
+        :param update_resources: Should the application resources be updated before
+            building?
         :param update_support: Should the application support be updated?
         :param no_update: Should automated updates be disabled?
         :param test_mode: Is the app being build in test mode?

src/briefcase/commands/create.py

@@ -104,8 +104,8 @@ def icon_targets(self, app: AppConfig):
         """Obtain the dictionary of icon targets that the template requires.
 
         :param app: The config object for the app
-        :return: A dictionary of icons that the template supports. The keys
-            of the dictionary are the size of the icons.
+        :return: A dictionary of icons that the template supports. The keys of the
+            dictionary are the size of the icons.
         """
         # If the template specifies no icons, return an empty dictionary.
         # If the template specifies a single icon without a size specification,
@@ -125,8 +125,8 @@ def splash_image_targets(self, app: AppConfig):
         """Obtain the dictionary of splash image targets that the template requires.
 
         :param app: The config object for the app
-        :return: A dictionary of splash images that the template supports. The keys
-            of the dictionary are the size of the splash images.
+        :return: A dictionary of splash images that the template supports. The keys of
+            the dictionary are the size of the splash images.
         """
         # If the template specifies no splash images, return an empty dictionary.
         # If the template specifies a single splash image without a size specification,
@@ -276,8 +276,8 @@ def _unpack_support_package(self, support_file_path, support_path):
     def _cleanup_app_support_package(self, support_path):
         """The internal implementation of the app support cleanup method.
 
-        Guaranteed to only be invoked if the backend uses a support package,
-        and the support path exists.
+        Guaranteed to only be invoked if the backend uses a support package, and the
+        support path exists.
 
         :param support_path: The support path to clean up.
         """
@@ -396,8 +396,8 @@ def _write_requirements_file(
 
         :param app: The app configuration
         :param requires: The full list of requirements
-        :param requirements_path: The full path to a requirements.txt file that
-            will be written.
+        :param requirements_path: The full path to a requirements.txt file that will be
+            written.
         """
 
         with self.input.wait_bar("Writing requirements file..."):

src/briefcase/commands/new.py

@@ -113,8 +113,8 @@ def validate_app_name(self, candidate):
         """Determine if the app name is valid.
 
         :param candidate: The candidate name
-        :returns: True. If there are any validation problems, raises ValueError
-            with a diagnostic message.
+        :returns: True. If there are any validation problems, raises ValueError with a
+            diagnostic message.
         """
         if not is_valid_app_name(candidate):
             raise ValueError(
@@ -145,8 +145,8 @@ def validate_bundle(self, candidate):
         """Determine if the bundle identifier is valid.
 
         :param candidate: The candidate bundle identifier
-        :returns: True. If there are any validation problems, raises ValueError
-            with a diagnostic message.
+        :returns: True. If there are any validation problems, raises ValueError with a
+            diagnostic message.
         """
         if not is_valid_bundle_identifier(candidate):
             raise ValueError(
@@ -172,11 +172,11 @@ def make_author_email(self, author, bundle):
         identifier.
 
         The candidate is based on the assumption that the author's name is in
-        "first/last" format, or it a corporate name; the "first" part is split
-        off, and prepended to the domain extracted from the bundle.
+        "first/last" format, or it a corporate name; the "first" part is split off, and
+        prepended to the domain extracted from the bundle.
 
-        It's not a perfect system, but it's better than putting up
-        "me@example.com" as a candidate default value.
+        It's not a perfect system, but it's better than putting up "me@example.com" as a
+        candidate default value.
 
         :param author: The authors name.
         :param bundle: The bundle identifier.
@@ -188,8 +188,8 @@ def validate_email(self, candidate):
         """Determine if the email address is valid.
 
         :param candidate: The candidate email address
-        :returns: True. If there are any validation problems, raises ValueError
-            with a diagnostic message.
+        :returns: True. If there are any validation problems, raises ValueError with a
+            diagnostic message.
         """
         if parseaddr(candidate)[1] != candidate:
             raise ValueError("Not a valid email address")
@@ -211,8 +211,8 @@ def validate_url(self, candidate):
         """Determine if the URL is valid.
 
         :param candidate: The candidate URL
-        :returns: True. If there are any validation problems, raises ValueError
-            with a diagnostic message.
+        :returns: True. If there are any validation problems, raises ValueError with a
+            diagnostic message.
         """
         result = urlparse(candidate)
         if not all([result.scheme, result.netloc]):
@@ -260,11 +260,9 @@ def input_select(self, intro, variable, options):
 
         The first option is assumed to be the default.
 
-        :param intro: An introductory paragraph explaining the question being
-            asked.
+        :param intro: An introductory paragraph explaining the question being asked.
         :param variable: The variable to display to the user.
-        :param options: A list of text strings, describing the available
-            options.
+        :param options: A list of text strings, describing the available options.
         :returns: The string content of the selected option.
         """
         self.input.prompt(intro)
@@ -293,8 +291,7 @@ def input_select(self, intro, variable, options):
     def build_app_context(self):
         """Ask the user for details about the app to be created.
 
-        :returns: A context dictionary to be used in the cookiecutter project
-            template.
+        :returns: A context dictionary to be used in the cookiecutter project template.
         """
         formal_name = self.input_text(
             intro="""

src/briefcase/commands/package.py

@@ -26,13 +26,12 @@ def default_packaging_format(self):
     def distribution_path(self, app):
         """The path to the distributable artefact for the app.
 
-        Requires that the packaging format has been annotated onto
-        the application definition
+        Requires that the packaging format has been annotated onto the application
+        definition
 
-        This is the single file that should be uploaded for distribution.
-        This may be the binary (if the binary is a self-contained executable);
-        however, if the output format produces an installer, it will be the
-        path to the installer.
+        This is the single file that should be uploaded for distribution. This may be
+        the binary (if the binary is a self-contained executable); however, if the
+        output format produces an installer, it will be the path to the installer.
 
         :param app: The app config
         """

src/briefcase/commands/run.py

@@ -23,15 +23,14 @@ def __init__(
         """Create a filter for a log stream.
 
         :param log_popen: The Popen object for the stream producing the logs.
-        :param clean_filter: A function that will filter a line of logs,
-            returning a "clean" line without any log system preamble.
-        :param clean_output: Should the output displayed to the user be the
-            "clean" output? (Default: True).
-        :param exit_filter: A function that will operate on a string containing
-            the last 10 lines of "clean" (i.e., preamble filtered) logs,
-            returning the integer exit status of the process if an exit
-            condition has been detected, or None if the log stream should
-            continue.
+        :param clean_filter: A function that will filter a line of logs, returning a
+            "clean" line without any log system preamble.
+        :param clean_output: Should the output displayed to the user be the "clean"
+            output? (Default: True).
+        :param exit_filter: A function that will operate on a string containing the last
+            10 lines of "clean" (i.e., preamble filtered) logs, returning the integer
+            exit status of the process if an exit condition has been detected, or None
+            if the log stream should continue.
         """
         self.log_popen = log_popen
         self.returncode = None
@@ -89,10 +88,9 @@ def __call__(self, line):
     def test_filter(pattern):
         """A factory method for producing filter functions.
 
-        :param pattern: The multiline regex pattern that identifies content of
-            interest in a log (e.g., success/failure conditions)
-        :returns: A log filter function that returns True if the pattern was
-            found
+        :param pattern: The multiline regex pattern that identifies content of interest
+            in a log (e.g., success/failure conditions)
+        :returns: A log filter function that returns True if the pattern was found
         """
 
         def filter_func(recent):
@@ -213,8 +211,8 @@ def add_options(self, parser):
     def _prepare_app_env(self, app: AppConfig, test_mode: bool):
         """Prepare the environment for running an app as a log stream.
 
-        This won't be used by every backend; but it's a sufficiently common
-        default that it's been factored out.
+        This won't be used by every backend; but it's a sufficiently common default that
+        it's been factored out.
 
         :param app: The app to be launched
         :param test_mode: Are we launching in test mode?

src/briefcase/config.py

@@ -341,8 +341,8 @@ def main_module(self, test_mode: bool):
 def merge_config(config, data):
     """Merge a new set of configuration requirements into a base configuration.
 
-    :param config: the base configuration to update. This configuration
-        is modified in-situ.
+    :param config: the base configuration to update. This configuration is modified in-
+        situ.
     :param data: The new configuration data to merge into the configuration.
     """
     for option in ["requires", "sources", "test_requires", "test_sources"]: