Add per-app pip install argument configuration

Author: sarayourfriend

changes/1270.feature.rst

@@ -0,0 +1 @@
+Briefcase now supports per-app configuration of ``pip install`` command line arguments using ``pip_install_arguments``.

docs/reference/configuration.rst

@@ -309,6 +309,56 @@ multiple paragraphs, if necessary. The long description *must not* be a copy of
 the ``description``, or include the ``description`` as the first line of the
 ``long_description``.
 
+``pip_install_arguments``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A list of strings of arguments to pass to ``pip install`` when building the app.
+
+To facilitate references to items included in ``sources``, entries are treated as
+format strings. The variable ``app_path`` represents the location ``sources``
+are copied to.
+
+For compatibility with all build targets, arguments and values should be defined
+together in a single string per argument. The following is a correct example:
+
+.. code-block:: TOML
+
+    pip_install_arguments = [
+        "--extra-index-url=https://example.com",
+        "-f{app_path}/wheels",
+    ]
+
+The following examples are **incorrect** and may unexpectedly fail for some build targets:
+
+.. code-block:: TOML
+
+    pip_install_arguments = [
+        "--extra-index-url", "https://example.com",
+        "-f", "{app_path}/wheels",
+    ]
+
+    pip_install_arguments = [
+        "--extra-index-url https://example.com",
+        "-f {app_path}/wheels",
+    ]
+
+.. admonition:: Referencing local paths
+
+    Use the ``app_path`` template variable to build paths based on directories copied from ``sources``.
+
+    This facilitates a local packages directory as used for the ``--find-links`` option. Given a directory
+    in the repository root named ``wheels``, the following will make it available to ``pip install``
+    regardless of the build context:
+
+    .. code-block:: TOML
+
+        sources = [
+            "src/<my-app>",
+            "wheels",
+        ]
+
+        pip_install_arguments = ["--find-links={app_path}/wheels"]
+
 ``primary_color``
 ~~~~~~~~~~~~~~~~~
 

src/briefcase/commands/create.py

@@ -515,10 +515,14 @@ def _write_requirements_file(
 
         with self.input.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
+                # in the file and perform a re-installation of all requirements.
+                f.write(f"# Generated {datetime.now()}\n")
+
+                for arg in self._extra_pip_args(app):
+                    f.write(f"{arg}\n")
+
                 if requires:
-                    # Add timestamp so build systems (such as Gradle) detect a change
-                    # in the file and perform a re-installation of all requirements.
-                    f.write(f"# Generated {datetime.now()}\n")
                     for requirement in requires:
                         # If the requirement is a local path, convert it to
                         # absolute, because Flatpak moves the requirements file
@@ -544,7 +548,10 @@ def _extra_pip_args(self, app: AppConfig):
         :param app: The app configuration
         :returns: A list of additional arguments
         """
-        return []
+        return [
+            argument.format(app_path=self.app_path(app))
+            for argument in app.pip_install_arguments
+        ]
 
     def _pip_install(
         self,
@@ -618,7 +625,7 @@ def _install_app_requirements(
             self.tools.os.mkdir(app_packages_path)
 
         # Install requirements
-        if requires:
+        if requires or app.pip_install_arguments:
             with self.input.wait_bar(progress_message):
                 self._pip_install(
                     app,

src/briefcase/config.py

@@ -266,6 +266,7 @@ def __init__(
         supported=True,
         long_description=None,
         console_app=False,
+        pip_install_arguments: list[str] | None = None,
         **kwargs,
     ):
         super().__init__(**kwargs)
@@ -295,6 +296,9 @@ def __init__(
         self.long_description = long_description
         self.license = license
         self.console_app = console_app
+        self.pip_install_arguments = (
+            [] if pip_install_arguments is None else pip_install_arguments
+        )
 
         if not is_valid_app_name(self.app_name):
             raise BriefcaseConfigError(

src/briefcase/platforms/iOS/xcode.py

@@ -305,7 +305,7 @@ def _extra_pip_args(self, app: AppConfig):
         :param app: The app configuration
         :returns: A list of additional arguments
         """
-        return [
+        return super()._extra_pip_args(app) + [
             "--prefer-binary",
             "--extra-index-url",
             "https://pypi.anaconda.org/beeware/simple",

tests/commands/create/test_install_app_requirements.py

@@ -162,6 +162,46 @@ def test_app_packages_valid_requires(
     assert myapp.test_requires is None
 
 
+def test_app_packages_pip_install_arguments(
+    create_command,
+    myapp,
+    app_packages_path,
+    app_path,
+    app_packages_path_index,
+):
+    """If an app has a valid list of requirements, pip is invoked."""
+    myapp.pip_install_arguments = ["--extra-index-url={app_path}/packages"]
+    myapp.requires = ["my-special-package"]
+
+    create_command.install_app_requirements(myapp, test_mode=False)
+
+    # A request was made to install requirements
+    create_command.tools[myapp].app_context.run.assert_called_with(
+        [
+            sys.executable,
+            "-u",
+            "-X",
+            "utf8",
+            "-m",
+            "pip",
+            "install",
+            "--disable-pip-version-check",
+            "--no-python-version-warning",
+            "--upgrade",
+            "--no-user",
+            f"--target={app_packages_path}",
+            f"--extra-index-url={app_path}/packages",
+            "my-special-package",
+        ],
+        check=True,
+        encoding="UTF-8",
+    )
+
+    # Original app definitions haven't changed
+    assert myapp.requires == ["my-special-package"]
+    assert myapp.test_requires is None
+
+
 def test_app_packages_valid_requires_no_support_package(
     create_command,
     myapp,
@@ -427,6 +467,7 @@ def test_app_requirements_no_requires(
     myapp,
     app_requirements_path,
     app_requirements_path_index,
+    mock_now,
 ):
     """If an app has no requirements, a requirements file is still written."""
     myapp.requires = None
@@ -437,7 +478,7 @@ def test_app_requirements_no_requires(
     # requirements.txt doesn't exist either
     assert app_requirements_path.exists()
     with app_requirements_path.open(encoding="utf-8") as f:
-        assert f.read() == ""
+        assert f.read() == f"{GENERATED_DATETIME}\n"
 
     # Original app definitions haven't changed
     assert myapp.requires is None
@@ -449,6 +490,7 @@ def test_app_requirements_empty_requires(
     myapp,
     app_requirements_path,
     app_requirements_path_index,
+    mock_now,
 ):
     """If an app has an empty requirements list, a requirements file is still
     written."""
@@ -460,7 +502,7 @@ def test_app_requirements_empty_requires(
     # requirements.txt doesn't exist either
     assert app_requirements_path.exists()
     with app_requirements_path.open(encoding="utf-8") as f:
-        assert f.read() == ""
+        assert f.read() == f"{GENERATED_DATETIME}\n"
 
     # Original app definitions haven't changed
     assert myapp.requires == []
@@ -491,6 +533,35 @@ def test_app_requirements_requires(
     assert myapp.test_requires is None
 
 
+def test_app_requirements_pip_install_arguments(
+    create_command,
+    myapp,
+    app_path,
+    app_requirements_path,
+    mock_now,
+    app_requirements_path_index,
+):
+    """If an app has an empty requirements list, a requirements file is still
+    written."""
+    myapp.pip_install_arguments = ["--extra-index-url={app_path}/packages"]
+    myapp.requires = ["my-favourite-package"]
+
+    # Install requirements into the bundle
+    create_command.install_app_requirements(myapp, test_mode=False)
+
+    # requirements.txt doesn't exist either
+    assert app_requirements_path.exists()
+    with app_requirements_path.open(encoding="utf-8") as f:
+        assert (
+            f.read()
+            == f"{GENERATED_DATETIME}\n--extra-index-url={app_path}/packages\nmy-favourite-package\n"
+        )
+
+    # Original app definitions haven't changed
+    assert myapp.requires == ["my-favourite-package"]
+    assert myapp.test_requires is None
+
+
 @pytest.mark.parametrize(
     "altsep, requirement, expected",
     [