briefcase-debugger 0.3.26__py3-none-any.whl

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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+briefcase_debugger.pth,sha256=UBmHy5Bj1sYg5ql0_tQ4bPwZIE9WGdbdi0cMhfFaBr4,70
+briefcase_debugger/__init__.py,sha256=JGZqwgKxfLrordBpfUmGhXLdB_i3N4cboCGzsfGEk1I,1355
+briefcase_debugger/config.py,sha256=F0c9bySVvNx7Hat-E_mu_L0v2t7UtVkq-7JrE2Bg0DA,453
+briefcase_debugger/debugpy.py,sha256=APcpmcOSU6QWqME3JT2f4JBdReAoCtUrCPX9rQpmDeQ,3313
+briefcase_debugger/pdb.py,sha256=9TnSB5Zx5OfQrrlLYe7KyPx6nMIODqB7D1X0vM9fJdY,1120
+briefcase_debugger-0.3.26.dist-info/licenses/LICENSE,sha256=qRJk_D5ySIyUj3MPfDAN239NEM-LqvjBTIF1dqgAXEo,1534
+briefcase_debugger-0.3.26.dist-info/METADATA,sha256=9C9eIoGob702SAtDnRiVInG_4kQ8j6U4CKzWENAbwqQ,3164
+briefcase_debugger-0.3.26.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+briefcase_debugger-0.3.26.dist-info/top_level.txt,sha256=2teeJqa8nZbwTcxX91A3vAYIctgVfva3nGfAqvITQLY,19
+briefcase_debugger-0.3.26.dist-info/RECORD,,

briefcase_debugger-0.3.26.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

briefcase_debugger-0.3.26.dist-info/licenses/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.dist-info/top_level.txt

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

briefcase_debugger.pth

@@ -0,0 +1 @@
+import briefcase_debugger; briefcase_debugger.start_remote_debugger()