briefcase-debugger 0.3.26__tar.gz

briefcase_debugger-0.3.26/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2015 Russell Keith-Magee.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Briefcase-Debugger nor the names of its contributors may
+       be used to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

briefcase_debugger-0.3.26/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: briefcase-debugger
+Version: 0.3.26
+Summary: A Briefcase plugin adding remote debugging support for PDB and Visual Studio Code.
+License-Expression: BSD-3-Clause
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdb
+Requires-Dist: remote-pdb<3.0.0,>=2.1.0; extra == "pdb"
+Provides-Extra: debugpy
+Requires-Dist: debugpy<2.0.0,>=1.8.17; extra == "debugpy"
+Dynamic: license-file
+
+# Briefcase Debugger Support
+[![Python Versions](https://img.shields.io/pypi/pyversions/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![PyPI Version](https://img.shields.io/pypi/v/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![Maturity](https://img.shields.io/pypi/status/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![BSD License](https://img.shields.io/pypi/l/briefcase-debugger.svg)](https://github.com/beeware/briefcase/blob/main/debugger/LICENSE)
+[![Build Status](https://github.com/beeware/briefcase/workflows/CI/badge.svg?branch=main)](https://github.com/beeware/briefcase/actions)
+[![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/)
+
+This package contains the debugger support package for the `pdb` and `debugpy` debuggers.
+
+It starts the remote debugger automatically at startup through an .pth file, if a `BRIEFCASE_DEBUGGER` environment variable is set.
+
+## Installation
+As an end-user, you won't normally need to install this package. It will be installed automatically by Briefcase if you specify the `--debug=pdb` or `--debug=debugpy` option when running your application.
+
+## Financial support
+
+The BeeWare project would not be possible without the generous support
+of our financial members:
+
+[![Anaconda logo](https://beeware.org/community/members/anaconda/anaconda-large.png)](https://anaconda.com/)
+
+Anaconda Inc. - Advancing AI through open source.
+
+Plus individual contributions from [users like
+you](https://beeware.org/community/members/). If you find Briefcase, or
+other BeeWare tools useful, please consider becoming a financial member.
+
+## Documentation
+
+Documentation for Briefcase can be found on [Read The
+Docs](https://briefcase.readthedocs.io).
+
+## Community
+
+Briefcase is part of the [BeeWare suite](https://beeware.org). You can
+talk to the community through:
+
+- [@beeware@fosstodon.org on Mastodon](https://fosstodon.org/@beeware)
+- [Discord](https://beeware.org/bee/chat/)
+- The Briefcase [GitHub Discussions
+  forum](https://github.com/beeware/briefcase/discussions)
+
+We foster a welcoming and respectful community as described in our
+[BeeWare Community Code of
+Conduct](https://beeware.org/community/behavior/).
+
+## Contributing
+
+If you experience problems with Briefcase, [log them on
+GitHub](https://github.com/beeware/briefcase/issues).
+
+If you'd like to contribute to Briefcase development, our [contribution
+guide](https://briefcase.readthedocs.io/en/latest/how-to/contribute/index.html)
+details how to set up a development environment, and other requirements
+we have as part of our contribution process.

briefcase_debugger-0.3.26/README.md

@@ -0,0 +1,56 @@
+# Briefcase Debugger Support
+[![Python Versions](https://img.shields.io/pypi/pyversions/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![PyPI Version](https://img.shields.io/pypi/v/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![Maturity](https://img.shields.io/pypi/status/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![BSD License](https://img.shields.io/pypi/l/briefcase-debugger.svg)](https://github.com/beeware/briefcase/blob/main/debugger/LICENSE)
+[![Build Status](https://github.com/beeware/briefcase/workflows/CI/badge.svg?branch=main)](https://github.com/beeware/briefcase/actions)
+[![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/)
+
+This package contains the debugger support package for the `pdb` and `debugpy` debuggers.
+
+It starts the remote debugger automatically at startup through an .pth file, if a `BRIEFCASE_DEBUGGER` environment variable is set.
+
+## Installation
+As an end-user, you won't normally need to install this package. It will be installed automatically by Briefcase if you specify the `--debug=pdb` or `--debug=debugpy` option when running your application.
+
+## Financial support
+
+The BeeWare project would not be possible without the generous support
+of our financial members:
+
+[![Anaconda logo](https://beeware.org/community/members/anaconda/anaconda-large.png)](https://anaconda.com/)
+
+Anaconda Inc. - Advancing AI through open source.
+
+Plus individual contributions from [users like
+you](https://beeware.org/community/members/). If you find Briefcase, or
+other BeeWare tools useful, please consider becoming a financial member.
+
+## Documentation
+
+Documentation for Briefcase can be found on [Read The
+Docs](https://briefcase.readthedocs.io).
+
+## Community
+
+Briefcase is part of the [BeeWare suite](https://beeware.org). You can
+talk to the community through:
+
+- [@beeware@fosstodon.org on Mastodon](https://fosstodon.org/@beeware)
+- [Discord](https://beeware.org/bee/chat/)
+- The Briefcase [GitHub Discussions
+  forum](https://github.com/beeware/briefcase/discussions)
+
+We foster a welcoming and respectful community as described in our
+[BeeWare Community Code of
+Conduct](https://beeware.org/community/behavior/).
+
+## Contributing
+
+If you experience problems with Briefcase, [log them on
+GitHub](https://github.com/beeware/briefcase/issues).
+
+If you'd like to contribute to Briefcase development, our [contribution
+guide](https://briefcase.readthedocs.io/en/latest/how-to/contribute/index.html)
+details how to set up a development environment, and other requirements
+we have as part of our contribution process.

briefcase_debugger-0.3.26/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = [
+    # keep versions in sync with automation/pyproject.toml and ../pyproject.toml
+    "setuptools==80.9.0",
+    "setuptools_scm==9.2.2",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "briefcase-debugger"
+description = "A Briefcase plugin adding remote debugging support for PDB and Visual Studio Code."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+dependencies = [
+    # see "pdb" or "debugpy" optional dependencies below
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+pdb = ["remote-pdb>=2.1.0,<3.0.0"]
+debugpy = ["debugpy>=1.8.17,<2.0.0"]
+
+[dependency-groups]
+test = [
+    "coverage[toml] == 7.12.0",
+    "pytest == 9.0.1",
+    "pytest-xdist == 3.8.0",
+]
+
+[tool.coverage.run]
+parallel = true
+branch = true
+relative_files = true
+source_pkgs = ["briefcase_debugger"]
+
+[tool.coverage.paths]
+source = [
+    "src",
+    "**/site-packages",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+skip_empty = true
+precision = 1
+
+[tool.ruff.lint]
+ignore = [
+    "T20",    # flake8-print (useful for briefcase, but not in the debugger)
+]
+
+[tool.setuptools_scm]
+root = "../"

briefcase_debugger-0.3.26/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

briefcase_debugger-0.3.26/setup.py

@@ -0,0 +1,44 @@
+import os
+
+import setuptools
+from setuptools.command.install import install
+
+
+# Copied from setuptools:
+# (https://github.com/pypa/setuptools/blob/7c859e017368360ba66c8cc591279d8964c031bc/setup.py#L40C6-L82)
+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.
+
+    Please do not replicate this behavior.
+    """
+
+    _pth_name = "briefcase_debugger"
+    _pth_contents = (
+        "import briefcase_debugger; briefcase_debugger.start_remote_debugger()"
+    )
+
+    def initialize_options(self):
+        install.initialize_options(self)
+        self.extra_path = self._pth_name, self._pth_contents
+
+    def finalize_options(self):
+        install.finalize_options(self)
+        self._restore_install_lib()
+
+    def _restore_install_lib(self):
+        """Undo secondary effect of `extra_path` adding to `install_lib`"""
+        suffix = os.path.relpath(self.install_lib, self.install_libbase)
+
+        if suffix.strip() == self._pth_contents.strip():
+            self.install_lib = self.install_libbase
+
+
+setuptools.setup(
+    cmdclass={"install": install_with_pth},
+)

briefcase_debugger-0.3.26/src/briefcase_debugger/__init__.py

@@ -0,0 +1,44 @@
+import json
+import os
+import sys
+import traceback
+
+
+def start_remote_debugger():
+    try:
+        # check verbose output
+        verbose = os.environ.get("BRIEFCASE_DEBUG", "0") == "1"
+
+        # reading config
+        config_str = os.environ.get("BRIEFCASE_DEBUGGER", None)
+
+        # skip debugger if no config is set
+        if config_str is None:
+            if verbose:
+                print(
+                    "No 'BRIEFCASE_DEBUGGER' environment variable found. Debugger not starting."
+                )
+            return  # If BRIEFCASE_DEBUGGER is not set, this packages does nothing...
+
+        if verbose:
+            print(f"'BRIEFCASE_DEBUGGER'={config_str}")
+
+        # Parsing config json
+        config = json.loads(config_str)
+
+        # start debugger
+        print("Starting remote debugger...")
+        if config["debugger"] == "debugpy":
+            from briefcase_debugger.debugpy import start_debugpy
+
+            start_debugpy(config, verbose)
+        elif config["debugger"] == "pdb":
+            from briefcase_debugger.pdb import start_pdb
+
+            start_pdb(config, verbose)
+        else:
+            raise ValueError(f"Unknown debugger '{config['debugger']}'")
+    except Exception:
+        # Show exception and stop the whole application when an error occurs
+        print(traceback.format_exc())
+        sys.exit(-1)

briefcase_debugger-0.3.26/src/briefcase_debugger/config.py

@@ -0,0 +1,21 @@
+from typing import TypedDict
+
+
+class AppPathMappings(TypedDict):
+    device_sys_path_regex: str
+    device_subfolders: list[str]
+    host_folders: list[str]
+
+
+class AppPackagesPathMappings(TypedDict):
+    sys_path_regex: str
+    host_folder: str
+
+
+class DebuggerConfig(TypedDict):
+    debugger: str
+    host: str
+    port: int
+    host_os: str
+    app_path_mappings: AppPathMappings | None
+    app_packages_path_mappings: AppPackagesPathMappings | None

briefcase_debugger-0.3.26/src/briefcase_debugger/debugpy.py

@@ -0,0 +1,108 @@
+import re
+import sys
+from pathlib import Path
+
+import debugpy
+
+from briefcase_debugger.config import DebuggerConfig
+
+
+def find_first_matching_path(regex: str) -> str:
+    """Returns the first element of sys.paths that matches regex, otherwise None."""
+    for path in sys.path:
+        if re.search(regex, path):
+            return path
+    raise ValueError(f"No sys.path entry matches regex '{regex}'")
+
+
+def load_path_mappings(config: DebuggerConfig, verbose: bool) -> list[tuple[str, str]]:
+    app_path_mappings = config.get("app_path_mappings", None)
+    app_packages_path_mappings = config.get("app_packages_path_mappings", None)
+
+    mappings_list = []
+    if app_path_mappings:
+        device_app_folder = find_first_matching_path(
+            app_path_mappings["device_sys_path_regex"]
+        )
+        for app_subfolder_device, app_subfolder_host in zip(
+            app_path_mappings["device_subfolders"],
+            app_path_mappings["host_folders"],
+            strict=False,
+        ):
+            mappings_list.append(
+                (
+                    app_subfolder_host,
+                    str(Path(device_app_folder) / app_subfolder_device),
+                )
+            )
+    if app_packages_path_mappings:
+        device_app_packages_folder = find_first_matching_path(
+            app_packages_path_mappings["sys_path_regex"]
+        )
+        mappings_list.append(
+            (
+                app_packages_path_mappings["host_folder"],
+                str(Path(device_app_packages_folder)),
+            )
+        )
+
+    if verbose:
+        print("Extracted path mappings:")
+        for idx, mapping in enumerate(mappings_list):
+            print(f"[{idx}] host =   {mapping[0]}")
+            print(f"[{idx}] device = {mapping[1]}")
+
+    return mappings_list
+
+
+def start_debugpy(config: DebuggerConfig, verbose: bool):
+    host = config["host"]
+    port = config["port"]
+    path_mappings = load_path_mappings(config, verbose)
+
+    # Starting remote debugger...
+    print(f"Starting debugpy in server mode at {host}:{port}...")
+    debugpy.listen((host, port), in_process_debug_adapter=True)
+
+    if verbose:
+        # pydevd is dynamically loaded and only available after debugpy is started
+        import pydevd
+
+        pydevd.DebugInfoHolder.DEBUG_TRACE_LEVEL = 3
+
+    if len(path_mappings) > 0:
+        if verbose:
+            print("Adding path mappings...")
+
+        # pydevd is dynamically loaded and only available after a debugger has connected
+        import pydevd_file_utils
+
+        pydevd_file_utils.setup_client_server_paths(path_mappings)
+
+    print("The debugpy server started. Waiting for debugger to attach...")
+    print(
+        f"""
+To connect to debugpy using VS Code add the following configuration to '.vscode/launch.json':
+{{
+    "version": "0.2.0",
+    "configurations": [
+        {{
+            "name": "Briefcase: Attach (Connect)",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {{
+                "host": "{host}",
+                "port": {port}
+            }},
+            "justMyCode": false
+        }}
+    ]
+}}
+
+For more information see: https://briefcase.beeware.org/en/stable/how-to/debugging/vscode/#bundled-app
+"""
+    )
+    debugpy.wait_for_client()
+
+    print("Debugger attached.")
+    print("-" * 75)

briefcase_debugger-0.3.26/src/briefcase_debugger/pdb.py

@@ -0,0 +1,44 @@
+import sys
+
+from remote_pdb import RemotePdb
+
+from briefcase_debugger.config import DebuggerConfig
+
+
+def start_pdb(config: DebuggerConfig, verbose: bool):
+    """Start remote PDB server."""
+    # Parsing host/port
+    host = config["host"]
+    port = config["port"]
+
+    # Print help message
+    host_os = config["host_os"]
+    telnet_cmd = f"telnet {host} {port}"
+    nc_cmd = f"nc {host} {port}"
+    if host_os == "Windows":
+        cmds_hint = f"    {telnet_cmd}"
+    elif host_os in ("Linux", "Darwin"):
+        cmds_hint = f"    {nc_cmd}"
+    else:
+        cmds_hint = f"""\
+ - {telnet_cmd}
+ - {nc_cmd}
+"""
+    print(f"""
+Remote PDB server opened at {host}:{port}.
+Waiting for debugger to attach...
+To connect to remote PDB use for example:
+
+{cmds_hint}
+
+For more information see: https://briefcase.beeware.org/en/stable/how-to/debugging/pdb/#bundled-app
+""")
+
+    # Create a RemotePdb instance
+    remote_pdb = RemotePdb(host, port, quiet=True)
+
+    # Connect the remote PDB with the "breakpoint()" function
+    sys.breakpointhook = remote_pdb.set_trace
+
+    print("Debugger client attached.")
+    print("-" * 75)

briefcase_debugger-0.3.26/src/briefcase_debugger.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: briefcase-debugger
+Version: 0.3.26
+Summary: A Briefcase plugin adding remote debugging support for PDB and Visual Studio Code.
+License-Expression: BSD-3-Clause
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdb
+Requires-Dist: remote-pdb<3.0.0,>=2.1.0; extra == "pdb"
+Provides-Extra: debugpy
+Requires-Dist: debugpy<2.0.0,>=1.8.17; extra == "debugpy"
+Dynamic: license-file
+
+# Briefcase Debugger Support
+[![Python Versions](https://img.shields.io/pypi/pyversions/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![PyPI Version](https://img.shields.io/pypi/v/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![Maturity](https://img.shields.io/pypi/status/briefcase-debugger.svg)](https://pypi.python.org/pypi/briefcase-debugger)
+[![BSD License](https://img.shields.io/pypi/l/briefcase-debugger.svg)](https://github.com/beeware/briefcase/blob/main/debugger/LICENSE)
+[![Build Status](https://github.com/beeware/briefcase/workflows/CI/badge.svg?branch=main)](https://github.com/beeware/briefcase/actions)
+[![Discord server](https://img.shields.io/discord/836455665257021440?label=Discord%20Chat&logo=discord&style=plastic)](https://beeware.org/bee/chat/)
+
+This package contains the debugger support package for the `pdb` and `debugpy` debuggers.
+
+It starts the remote debugger automatically at startup through an .pth file, if a `BRIEFCASE_DEBUGGER` environment variable is set.
+
+## Installation
+As an end-user, you won't normally need to install this package. It will be installed automatically by Briefcase if you specify the `--debug=pdb` or `--debug=debugpy` option when running your application.
+
+## Financial support
+
+The BeeWare project would not be possible without the generous support
+of our financial members:
+
+[![Anaconda logo](https://beeware.org/community/members/anaconda/anaconda-large.png)](https://anaconda.com/)
+
+Anaconda Inc. - Advancing AI through open source.
+
+Plus individual contributions from [users like
+you](https://beeware.org/community/members/). If you find Briefcase, or
+other BeeWare tools useful, please consider becoming a financial member.
+
+## Documentation
+
+Documentation for Briefcase can be found on [Read The
+Docs](https://briefcase.readthedocs.io).
+
+## Community
+
+Briefcase is part of the [BeeWare suite](https://beeware.org). You can
+talk to the community through:
+
+- [@beeware@fosstodon.org on Mastodon](https://fosstodon.org/@beeware)
+- [Discord](https://beeware.org/bee/chat/)
+- The Briefcase [GitHub Discussions
+  forum](https://github.com/beeware/briefcase/discussions)
+
+We foster a welcoming and respectful community as described in our
+[BeeWare Community Code of
+Conduct](https://beeware.org/community/behavior/).
+
+## Contributing
+
+If you experience problems with Briefcase, [log them on
+GitHub](https://github.com/beeware/briefcase/issues).
+
+If you'd like to contribute to Briefcase development, our [contribution
+guide](https://briefcase.readthedocs.io/en/latest/how-to/contribute/index.html)
+details how to set up a development environment, and other requirements
+we have as part of our contribution process.

briefcase_debugger-0.3.26/src/briefcase_debugger.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+src/briefcase_debugger/__init__.py
+src/briefcase_debugger/config.py
+src/briefcase_debugger/debugpy.py
+src/briefcase_debugger/pdb.py
+src/briefcase_debugger.egg-info/PKG-INFO
+src/briefcase_debugger.egg-info/SOURCES.txt
+src/briefcase_debugger.egg-info/dependency_links.txt
+src/briefcase_debugger.egg-info/requires.txt
+src/briefcase_debugger.egg-info/top_level.txt
+tests/test_base.py
+tests/test_debugpy.py
+tests/test_debugpy_path_mappings.py
+tests/test_pdb.py

briefcase_debugger-0.3.26/src/briefcase_debugger.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

briefcase_debugger-0.3.26/src/briefcase_debugger.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[debugpy]
+debugpy<2.0.0,>=1.8.17
+
+[pdb]
+remote-pdb<3.0.0,>=2.1.0

briefcase_debugger-0.3.26/src/briefcase_debugger.egg-info/top_level.txt

@@ -0,0 +1 @@
+briefcase_debugger

briefcase_debugger-0.3.26/tests/test_base.py

@@ -0,0 +1,39 @@
+import importlib
+import json
+import os
+import sys
+from unittest.mock import MagicMock
+
+import briefcase_debugger
+
+
+def test_import_for_code_coverage(monkeypatch, capsys):
+    """Get 100% code coverage."""
+    # The module `briefcase_debugger` is already imported through the .pth
+    # file. Code executed during .pth files are not covered by coverage.py.
+    # So we need to reload the module to get a 100% code coverage.
+    importlib.reload(importlib.import_module("briefcase_debugger"))
+
+
+def test_unknown_debugger(monkeypatch, capsys):
+    """An unknown debugger raises an error and stops the application."""
+    os_environ = {}
+    os_environ["BRIEFCASE_DEBUGGER"] = json.dumps(
+        {
+            "debugger": "unknown",
+            "host": "somehost",
+            "port": 9999,
+            "host_os": "Windows",
+        }
+    )
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    fake_sys_exit = MagicMock()
+    monkeypatch.setattr(sys, "exit", fake_sys_exit)
+
+    briefcase_debugger.start_remote_debugger()
+
+    fake_sys_exit.assert_called_once_with(-1)
+
+    captured = capsys.readouterr()
+    assert "Unknown debugger" in captured.out

briefcase_debugger-0.3.26/tests/test_debugpy.py

@@ -0,0 +1,197 @@
+import json
+import os
+import sys
+from unittest.mock import MagicMock
+
+import briefcase_debugger
+import debugpy
+import pytest
+from briefcase_debugger.config import AppPathMappings
+
+
+def test_no_env_vars(monkeypatch, capsys):
+    """Nothing happens, when no env vars are set."""
+    os_environ = {}
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert captured.err == ""
+
+
+def test_no_debugger_verbose(monkeypatch, capsys):
+    """Nothing happens except a short message, when only verbose is requested."""
+    os_environ = {}
+    os_environ["BRIEFCASE_DEBUG"] = "1"
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    captured = capsys.readouterr()
+    assert (
+        captured.out
+        == "No 'BRIEFCASE_DEBUGGER' environment variable found. Debugger not starting.\n"
+    )
+    assert captured.err == ""
+
+
+@pytest.mark.parametrize(
+    ("os_name", "app_path_mappings", "sys_path", "expected_path_mappings"),
+    [
+        (
+            "nt",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["C:\\PROJECT_ROOT\\src\\helloworld"],
+            ),
+            ["C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app"],
+            [
+                (
+                    "C:\\PROJECT_ROOT\\src\\helloworld",
+                    "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app\\helloworld",
+                )
+            ],
+        ),
+        (
+            "posix",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["/PROJECT_ROOT/src/helloworld"],
+            ),
+            [
+                "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Resources/app"
+            ],
+            [
+                (
+                    "/PROJECT_ROOT/src/helloworld",
+                    "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Resources/app/helloworld",
+                )
+            ],
+        ),
+    ],
+)
+@pytest.mark.parametrize(
+    ("verbose", "some_verbose_output", "pydevd_trace_level"),
+    [
+        (True, "Extracted path mappings:\n[0] host =   ", 3),
+        (False, "", 0),
+    ],
+)
+def test_with_debugger(
+    os_name: str,
+    app_path_mappings: AppPathMappings,
+    sys_path: list[str],
+    expected_path_mappings: list[tuple[str, str]],
+    verbose: bool,
+    some_verbose_output: str,
+    pydevd_trace_level: int,
+    monkeypatch,
+    capsys,
+):
+    """Normal debug session."""
+    if os.name != os_name:
+        pytest.skip(f"Test only runs on {os_name} systems")
+
+    os_environ = {}
+    os_environ["BRIEFCASE_DEBUG"] = "1" if verbose else "0"
+    os_environ["BRIEFCASE_DEBUGGER"] = json.dumps(
+        {
+            "debugger": "debugpy",
+            "host": "somehost",
+            "port": 9999,
+            "host_os": "SomeOS",
+            "app_path_mappings": app_path_mappings,
+            "app_packages_path_mappings": None,
+        }
+    )
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    monkeypatch.setattr(sys, "path", sys_path)
+
+    fake_debugpy_listen = MagicMock()
+    monkeypatch.setattr(debugpy, "listen", fake_debugpy_listen)
+
+    fake_debugpy_wait_for_client = MagicMock()
+    monkeypatch.setattr(debugpy, "wait_for_client", fake_debugpy_wait_for_client)
+
+    # pydevd is dynamically loaded and only available when a real debugger is attached. So
+    # we fake the whole module, as otherwise the import in start_remote_debugger would fail
+    fake_pydevd = MagicMock()
+    monkeypatch.setitem(sys.modules, "pydevd", fake_pydevd)
+    fake_pydevd.DebugInfoHolder.DEBUG_TRACE_LEVEL = 0
+    fake_pydevd_file_utils = MagicMock()
+    fake_pydevd_file_utils.setup_client_server_paths.return_value = None
+    monkeypatch.setitem(sys.modules, "pydevd_file_utils", fake_pydevd_file_utils)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    fake_debugpy_listen.assert_called_once_with(
+        ("somehost", 9999),
+        in_process_debug_adapter=True,
+    )
+
+    fake_debugpy_wait_for_client.assert_called_once()
+    fake_pydevd_file_utils.setup_client_server_paths.assert_called_once_with(
+        expected_path_mappings
+    )
+
+    captured = capsys.readouterr()
+    assert "Waiting for debugger to attach..." in captured.out
+    assert captured.err == ""
+
+    assert some_verbose_output in captured.out
+    assert pydevd_trace_level == fake_pydevd.DebugInfoHolder.DEBUG_TRACE_LEVEL
+
+
+def test_with_debugger_without_path_mappings(monkeypatch, capsys):
+    """Debug session without path mappings."""
+    os_environ = {}
+    os_environ["BRIEFCASE_DEBUG"] = "0"
+    os_environ["BRIEFCASE_DEBUGGER"] = json.dumps(
+        {
+            "debugger": "debugpy",
+            "host": "somehost",
+            "port": 9999,
+            "host_os": "SomeOS",
+            "app_path_mappings": None,
+            "app_packages_path_mappings": None,
+        }
+    )
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    fake_debugpy_listen = MagicMock()
+    monkeypatch.setattr(debugpy, "listen", fake_debugpy_listen)
+
+    fake_debugpy_wait_for_client = MagicMock()
+    monkeypatch.setattr(debugpy, "wait_for_client", fake_debugpy_wait_for_client)
+
+    # pydevd is dynamically loaded and only available when a real debugger is attached. So
+    # we fake the whole module, as otherwise the import in start_remote_debugger would fail
+    fake_pydevd = MagicMock()
+    monkeypatch.setitem(sys.modules, "pydevd", fake_pydevd)
+    fake_pydevd.DebugInfoHolder.DEBUG_TRACE_LEVEL = 0
+    fake_pydevd_file_utils = MagicMock()
+    fake_pydevd_file_utils.setup_client_server_paths.return_value = None
+    monkeypatch.setitem(sys.modules, "pydevd_file_utils", fake_pydevd_file_utils)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    fake_debugpy_listen.assert_called_once_with(
+        ("somehost", 9999),
+        in_process_debug_adapter=True,
+    )
+
+    fake_debugpy_wait_for_client.assert_called_once()
+    fake_pydevd_file_utils.setup_client_server_paths.assert_not_called()
+
+    captured = capsys.readouterr()
+    assert "Waiting for debugger to attach..." in captured.out
+    assert captured.err == ""

briefcase_debugger-0.3.26/tests/test_debugpy_path_mappings.py

@@ -0,0 +1,287 @@
+import os
+import sys
+
+import briefcase_debugger.debugpy
+import pytest
+from briefcase_debugger.config import (
+    AppPackagesPathMappings,
+    AppPathMappings,
+    DebuggerConfig,
+)
+
+
+def test_mappings_not_existing():
+    """Complete empty config."""
+    path_mappings = briefcase_debugger.debugpy.load_path_mappings({}, False)
+    assert path_mappings == []
+
+
+def test_mappings_none(monkeypatch):
+    """Config with no mappings set."""
+    config = DebuggerConfig(
+        debugger="debugpy",
+        host="",
+        port=0,
+        app_path_mappings=None,
+        app_packages_path_mappings=None,
+    )
+    path_mappings = briefcase_debugger.debugpy.load_path_mappings(config, False)
+    assert path_mappings == []
+
+
+@pytest.mark.parametrize(
+    (
+        "os_name",
+        "app_path_mappings",
+        "app_packages_path_mappings",
+        "sys_path",
+        "expected_path_mappings",
+    ),
+    [
+        # Windows
+        pytest.param(
+            "nt",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["C:\\PROJECT_ROOT\\src\\helloworld"],
+            ),
+            None,
+            [
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\python313.zip",
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src",
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app",
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app_packages",
+            ],
+            [
+                (
+                    "C:\\PROJECT_ROOT\\src\\helloworld",
+                    "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app\\helloworld",
+                ),
+            ],
+            id="windows",
+        ),
+        # Windows with `app_packages_path_mappings` (currently not used by briefcase, but principally possible)
+        pytest.param(
+            "nt",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["C:\\PROJECT_ROOT\\src\\helloworld"],
+            ),
+            AppPackagesPathMappings(
+                sys_path_regex="app_packages$",
+                host_folder="C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app_packages",
+            ),
+            [
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\python313.zip",
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src",
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app",
+                "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app_packages",
+            ],
+            [
+                (
+                    "C:\\PROJECT_ROOT\\src\\helloworld",
+                    "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app\\helloworld",
+                ),
+                (
+                    "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app_packages",
+                    "C:\\PROJECT_ROOT\\build\\helloworld\\windows\\app\\src\\app_packages",
+                ),
+            ],
+            id="windows-with-app-packages",
+        ),
+        # macOS
+        pytest.param(
+            "posix",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["/PROJECT_ROOT/src/helloworld"],
+            ),
+            None,
+            [
+                "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Frameworks/Python.framework/Versions/3.13/lib/python3.13",
+                "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Frameworks/Python.framework/Versions/3.13/lib/python3.13/lib-dynload",
+                "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Resources/app",
+                "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages",
+                "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Resources/app_packages",
+            ],
+            [
+                (
+                    "/PROJECT_ROOT/src/helloworld",
+                    "/PROJECT_ROOT/build/helloworld/macos/app/Hello World.app/Contents/Resources/app/helloworld",
+                )
+            ],
+            id="macos",
+        ),
+        # iOS
+        pytest.param(
+            "posix",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["/PROJECT_ROOT/src/helloworld"],
+            ),
+            AppPackagesPathMappings(
+                sys_path_regex="app_packages$",
+                host_folder="/APP_PACKAGES_PATH/app_packages.iphonesimulator",
+            ),
+            [
+                "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/python/lib/python3.13",
+                "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/python/lib/python3.13/lib-dynload",
+                "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/app",
+                "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/python/lib/python3.13/site-packages",
+                "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/app_packages",
+            ],
+            [
+                (
+                    "/PROJECT_ROOT/src/helloworld",
+                    "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/app/helloworld",
+                ),
+                (
+                    "/APP_PACKAGES_PATH/app_packages.iphonesimulator",
+                    "CoreSimulator/Devices/RANDOM_NUMBER/data/Containers/Bundle/Application/RANDOM_NUMBER/Hello World.app/app_packages",
+                ),
+            ],
+            id="ios",
+        ),
+        # Android (with VS Code running on Windows)
+        pytest.param(
+            "posix",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["C:\\PROJECT_ROOT\\src\\helloworld"],
+            ),
+            AppPackagesPathMappings(
+                sys_path_regex="requirements$",
+                host_folder="C:\\BUNDLE_PATH\\app\\build\\python\\pip\\debug\\common",
+            ),
+            [
+                "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/app",
+                "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/requirements",
+                "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/stdlib-x86_64",
+                "/data/user/0/com.example.helloworld/files/chaquopy/stdlib-common.imy",
+                "/data/user/0/com.example.helloworld/files/chaquopy/bootstrap.imy",
+                "/data/user/0/com.example.helloworld/files/chaquopy/bootstrap-native/x86_64",
+            ],
+            [
+                (
+                    "C:\\PROJECT_ROOT\\src\\helloworld",
+                    "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/app/helloworld",
+                ),
+                (
+                    "C:\\BUNDLE_PATH\\app\\build\\python\\pip\\debug\\common",
+                    "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/requirements",
+                ),
+            ],
+            id="android-on-windows-host",
+        ),
+        # Android (with VS Code running on POSIX system)
+        pytest.param(
+            "posix",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["/PROJECT_ROOT/src/helloworld"],
+            ),
+            AppPackagesPathMappings(
+                sys_path_regex="requirements$",
+                host_folder="/BUNDLE_PATH/app/build/python/pip/debug/common",
+            ),
+            [
+                "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/app",
+                "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/requirements",
+                "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/stdlib-x86_64",
+                "/data/user/0/com.example.helloworld/files/chaquopy/stdlib-common.imy",
+                "/data/user/0/com.example.helloworld/files/chaquopy/bootstrap.imy",
+                "/data/user/0/com.example.helloworld/files/chaquopy/bootstrap-native/x86_64",
+            ],
+            [
+                (
+                    "/PROJECT_ROOT/src/helloworld",
+                    "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/app/helloworld",
+                ),
+                (
+                    "/BUNDLE_PATH/app/build/python/pip/debug/common",
+                    "/data/data/com.example.helloworld/files/chaquopy/AssetFinder/requirements",
+                ),
+            ],
+            id="android-on-posix-host",
+        ),
+    ],
+)
+def test_mappings(
+    os_name: str,
+    app_path_mappings: AppPathMappings,
+    app_packages_path_mappings: AppPackagesPathMappings | None,
+    sys_path: list[str],
+    expected_path_mappings: list[tuple[str, str]],
+    monkeypatch,
+):
+    if os.name != os_name:
+        pytest.skip(f"Test only runs on {os_name} systems")
+
+    config = DebuggerConfig(
+        debugger="debugpy",
+        host="",
+        port=0,
+        app_path_mappings=app_path_mappings,
+        app_packages_path_mappings=app_packages_path_mappings,
+    )
+
+    monkeypatch.setattr(sys, "path", sys_path)
+
+    path_mappings = briefcase_debugger.debugpy.load_path_mappings(config, False)
+
+    assert path_mappings == expected_path_mappings
+
+
+@pytest.mark.parametrize(
+    ("os_name", "app_path_mappings"),
+    [
+        # Windows
+        pytest.param(
+            "nt",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["C:\\PROJECT_ROOT\\src\\helloworld"],
+            ),
+            id="windows",
+        ),
+        # POSIX (macOS/iOS/Android)
+        pytest.param(
+            "posix",
+            AppPathMappings(
+                device_sys_path_regex="app$",
+                device_subfolders=["helloworld"],
+                host_folders=["/PROJECT_ROOT/src/helloworld"],
+            ),
+            id="posix",
+        ),
+    ],
+)
+def test_mappings_wrong_sys_path(
+    os_name: str,
+    app_path_mappings: AppPathMappings,
+    monkeypatch,
+):
+    """Path mappings with a wrong sys path set."""
+    if os.name != os_name:
+        pytest.skip(f"Test only runs on {os_name} systems")
+
+    config = DebuggerConfig(
+        debugger="debugpy",
+        host="",
+        port=0,
+        app_path_mappings=app_path_mappings,
+        app_packages_path_mappings=None,
+    )
+
+    sys_path = []
+    monkeypatch.setattr(sys, "path", sys_path)
+
+    with pytest.raises(ValueError, match=r"No sys.path entry matches regex"):
+        briefcase_debugger.debugpy.load_path_mappings(config, False)

briefcase_debugger-0.3.26/tests/test_pdb.py

@@ -0,0 +1,80 @@
+import json
+import os
+from unittest.mock import MagicMock
+
+import briefcase_debugger
+import briefcase_debugger.pdb
+import pytest
+
+
+def test_no_env_vars(monkeypatch, capsys):
+    """Nothing happens, when no env vars are set."""
+    os_environ = {}
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert captured.err == ""
+
+
+def test_no_debugger_verbose(monkeypatch, capsys):
+    """Nothing happens except a short message, when only verbose is requested."""
+    os_environ = {}
+    os_environ["BRIEFCASE_DEBUG"] = "1"
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    captured = capsys.readouterr()
+    assert (
+        captured.out
+        == "No 'BRIEFCASE_DEBUGGER' environment variable found. Debugger not starting.\n"
+    )
+    assert captured.err == ""
+
+
+@pytest.mark.parametrize("verbose", [True, False])
+@pytest.mark.parametrize(
+    ("host_os", "expected_host_cmds"),
+    [
+        ("Windows", ["telnet somehost 9999"]),
+        ("Darwin", ["nc somehost 9999"]),
+        ("Linux", ["nc somehost 9999"]),
+        ("UnknownOS", ["nc somehost 9999", "telnet somehost 9999"]),
+    ],
+)
+def test_with_debugger(monkeypatch, host_os, expected_host_cmds, capsys, verbose):
+    """Normal debug session."""
+    os_environ = {}
+    os_environ["BRIEFCASE_DEBUG"] = "1" if verbose else "0"
+    os_environ["BRIEFCASE_DEBUGGER"] = json.dumps(
+        {
+            "debugger": "pdb",
+            "host": "somehost",
+            "port": 9999,
+            "host_os": host_os,
+        }
+    )
+    monkeypatch.setattr(os, "environ", os_environ)
+
+    fake_remote_pdb = MagicMock()
+    monkeypatch.setattr(briefcase_debugger.pdb, "RemotePdb", fake_remote_pdb)
+
+    # start test function
+    briefcase_debugger.start_remote_debugger()
+
+    fake_remote_pdb.assert_called_once_with(
+        "somehost",
+        9999,
+        quiet=True,
+    )
+
+    captured = capsys.readouterr()
+    assert "Waiting for debugger to attach..." in captured.out
+    for cmd in expected_host_cmds:
+        assert cmd in captured.out
+    assert captured.err == ""