pyxdia 0.0.0__tar.gz

pyxdia-0.0.0/LICENSE.txt

@@ -0,0 +1,26 @@
+Copyright 2024 Matt Borgerson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+Dependencies
+--------------------------------------------------------------------------------
+
+pyxdia releases include binaries which are governed under separate licenses.
+See respective *.LICENSE.txt files in release package for more details.

pyxdia-0.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+graft pyxdia
+include LICENSE.txt
+graft tests
+global-exclude *.so
+global-exclude *.gitignore
+global-exclude *.pyc

pyxdia-0.0.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: pyxdia
+Version: 0.0.0
+Summary: pyxdia
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: docs
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+
+pyxdia
+======
+pyxdia is a Python library for extracting useful program information from a [PDB file](https://en.wikipedia.org/wiki/Program_database). pyxdia runs on Windows, macOS, Linux, and other platforms.
+
+## Dependencies
+
+pyxdia depends on [xdia](https://github.com/mborgerson/xdia), a native Windows executable. For cross-platform support, a thin loader and compatibility layer (xdialdr) and emulator ([Blink](https://github.com/jart/blink)) are used to run xdia. These dependencies are included in wheels for convenient installation, and in source distributions will be downloaded at installation time.
+
+## License
+
+pyxdia source is released under MIT license. pyxdia wheels include binaries that are released under individual licenses, with license text available within the wheel.

pyxdia-0.0.0/README.md

@@ -0,0 +1,11 @@
+pyxdia
+======
+pyxdia is a Python library for extracting useful program information from a [PDB file](https://en.wikipedia.org/wiki/Program_database). pyxdia runs on Windows, macOS, Linux, and other platforms.
+
+## Dependencies
+
+pyxdia depends on [xdia](https://github.com/mborgerson/xdia), a native Windows executable. For cross-platform support, a thin loader and compatibility layer (xdialdr) and emulator ([Blink](https://github.com/jart/blink)) are used to run xdia. These dependencies are included in wheels for convenient installation, and in source distributions will be downloaded at installation time.
+
+## License
+
+pyxdia source is released under MIT license. pyxdia wheels include binaries that are released under individual licenses, with license text available within the wheel.

pyxdia-0.0.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 120
+target-version = ['py310']
+
+[tool.ruff]
+line-length = 120
+extend-ignore = [
+	"E402", # Bottom imports
+]

pyxdia-0.0.0/pyxdia/__init__.py

@@ -0,0 +1,3 @@
+from .pdb import PDB
+
+__all__ = ["PDB"]

pyxdia-0.0.0/pyxdia/__main__.py

@@ -0,0 +1,16 @@
+import argparse
+
+from .pdb import PDB
+
+
+def main():
+    ap = argparse.ArgumentParser("pyxdia")
+    ap.add_argument("pdb", help="Path to PDB file")
+    args = ap.parse_args()
+
+    pdb = PDB(args.pdb)
+    pdb.pp()
+
+
+if __name__ == "__main__":
+    main()

pyxdia-0.0.0/pyxdia/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.0.0"

pyxdia-0.0.0/pyxdia/pdb.py

@@ -0,0 +1,62 @@
+import json
+import os
+import pathlib
+import platform
+import subprocess
+from pprint import pprint
+
+
+ROOT_PATH = pathlib.Path(__file__).parent.absolute()
+XDIA_EXE_PATH = ROOT_PATH / "bin" / "xdia.exe"
+MSDIA_DLL_PATH = ROOT_PATH / "bin" / "msdia140.dll"
+XDIALDR_PATH = ROOT_PATH / "bin" / "xdialdr"
+BLINK_PATH = ROOT_PATH / "bin" / "blink"
+
+
+class PDB:
+    """
+    This class interfaces with the xdia utility to extract useful program information from a Program Database (PDB) file.
+    """
+
+    _pdb_data: dict
+
+    def __init__(self, pdb_path: str | pathlib.Path):
+        self._load_pdb(pdb_path)
+
+    def _load_pdb(self, pdb_path: str | pathlib.Path) -> None:
+        # Ensure pdb_path is a pathlib.Path
+        if not isinstance(pdb_path, pathlib.Path):
+            pdb_path = pathlib.Path(pdb_path).absolute()
+
+        env = {"MSDIA_PATH": str(MSDIA_DLL_PATH), "XDIA_PATH": str(XDIA_EXE_PATH)}
+
+        if platform.system() == "Windows":
+            cmd = [XDIA_EXE_PATH]
+        else:
+            blink_required = (platform.system() != "Linux") or (platform.machine() != "x86_64")
+            if blink_required:
+                # XXX: Work around blink VFS mount issue
+                env["BLINK_PREFIX"] = "/tmp"
+                env["MSDIA_PATH"] = "/SystemRoot" + env["MSDIA_PATH"]
+                env["XDIA_PATH"] = "/SystemRoot" + env["XDIA_PATH"]
+                pdb_path = pathlib.Path("/SystemRoot") / pdb_path.relative_to("/")
+                xdialdr_path = pathlib.Path("/SystemRoot") / XDIALDR_PATH.relative_to("/")
+                cmd = [BLINK_PATH, xdialdr_path]
+            else:
+                cmd = [XDIALDR_PATH]
+
+        diadump_s = subprocess.check_output(cmd + [str(pdb_path)], encoding="utf-8", env=env)
+        self._pdb_data = json.loads(diadump_s)
+
+    def pp(self) -> None:
+        """
+        Pretty-print all available info.
+        """
+        pprint(self._pdb_data, indent=2)
+
+    @property
+    def globals(self) -> list[dict[str, int | str]]:
+        """
+        List all globals.
+        """
+        return self._pdb_data["globals"]

pyxdia-0.0.0/pyxdia.egg-info/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.1
+Name: pyxdia
+Version: 0.0.0
+Summary: pyxdia
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: docs
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+
+pyxdia
+======
+pyxdia is a Python library for extracting useful program information from a [PDB file](https://en.wikipedia.org/wiki/Program_database). pyxdia runs on Windows, macOS, Linux, and other platforms.
+
+## Dependencies
+
+pyxdia depends on [xdia](https://github.com/mborgerson/xdia), a native Windows executable. For cross-platform support, a thin loader and compatibility layer (xdialdr) and emulator ([Blink](https://github.com/jart/blink)) are used to run xdia. These dependencies are included in wheels for convenient installation, and in source distributions will be downloaded at installation time.
+
+## License
+
+pyxdia source is released under MIT license. pyxdia wheels include binaries that are released under individual licenses, with license text available within the wheel.

pyxdia-0.0.0/pyxdia.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE.txt
+MANIFEST.in
+README.md
+pyproject.toml
+setup.cfg
+setup.py
+pyxdia/__init__.py
+pyxdia/__main__.py
+pyxdia/__version__.py
+pyxdia/pdb.py
+pyxdia.egg-info/PKG-INFO
+pyxdia.egg-info/SOURCES.txt
+pyxdia.egg-info/dependency_links.txt
+pyxdia.egg-info/requires.txt
+pyxdia.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_pdb.py

pyxdia-0.0.0/pyxdia.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyxdia-0.0.0/pyxdia.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[docs]
+furo
+ipython
+myst-parser
+sphinx
+sphinx-autodoc-typehints

pyxdia-0.0.0/pyxdia.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyxdia

pyxdia-0.0.0/setup.cfg

@@ -0,0 +1,32 @@
+[metadata]
+name = pyxdia
+version = attr: pyxdia.__version__.__version__
+description = pyxdia
+long_description = file: README.md
+long_description_content_type = text/markdown
+license_files = LICENSE.txt
+classifiers = 
+	Programming Language :: Python
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3 :: Only
+	Programming Language :: Python :: 3.10
+	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
+
+[options]
+packages = 
+	pyxdia
+python_requires = >=3.10
+
+[options.extras_require]
+docs = 
+	furo
+	ipython
+	myst-parser
+	sphinx
+	sphinx-autodoc-typehints
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyxdia-0.0.0/setup.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+
+import gzip
+import shutil
+import platform
+import os
+import stat
+import tarfile
+from zipfile import ZipFile
+from urllib.request import urlretrieve, urlcleanup
+from pathlib import Path
+from setuptools import setup, Command
+from setuptools.command.build import build as _build
+from setuptools.command.build import SubCommand
+from setuptools.command.install import install as _install
+from setuptools.command.develop import develop as _develop
+from wheel.bdist_wheel import bdist_wheel
+
+
+root_dir = Path(__file__).parent.absolute()
+pyxdia_dir = root_dir / "pyxdia"
+
+
+with open(pyxdia_dir / "__version__.py") as f:
+    ns = {}
+    exec(f.read(), ns)
+    version = ns["__version__"]
+
+
+class CustomBdistWheel(bdist_wheel):
+    """
+    Overrides bdist_wheel to generate platform tag marking the wheel as
+    platform specific.
+    """
+
+    @staticmethod
+    def _get_darwin_tag():
+        # FIXME: This is based only on blink requirement. Check the binary to find the
+        #        actual requirement. This works for 1.1.0 release.
+        return "macosx_" + ("14" if platform.machine() == "arm64" else "11") + "_0"
+
+    def get_tag(self):
+        plat_to_tag = {"Windows": "win", "Linux": "linux", "Darwin": self._get_darwin_tag()}
+        plat = plat_to_tag.get(platform.system(), None)
+        assert plat is not None, "FIXME: Unhandled platform tag"
+        return ("py3", "none", f"{plat}_{platform.machine().lower()}")
+
+
+class CheckXdiaInstallation(Command):
+    """
+    Check for xdia, xdialdr, blink installation. For installations from
+    source, download and install necessary components if they are not already
+    installed.
+    """
+
+    description = 'Check xdia installation'
+    user_options = []
+    editable_mode: bool = False
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        if self.editable_mode:
+            prefix = pyxdia_dir
+        else:
+            build_py = self.get_finalized_command('build_py')
+            prefix = Path(build_py.build_lib) / "pyxdia"
+
+        self._bin_dir = prefix / "bin"
+        self._xdia_exe_path = self._bin_dir / "xdia.exe"
+        self._xdialdr_path = self._bin_dir / "xdialdr"
+        self._msdia140_dll_path = self._bin_dir / "msdia140.dll"
+        self._blink_path = self._bin_dir / "blink"
+
+    @staticmethod
+    def _download_file(url, filename = "") -> str:
+        print(f'Downloading {url}...')
+        if not filename:
+            filename = url.split("/")[-1]
+        urlretrieve(url, filename)
+        urlcleanup()
+        return filename
+
+    @staticmethod
+    def _mark_file_executable(path):
+        os.chmod(path, 0o755)
+
+    def _get_xdia_install_list(self) -> list[str]:
+        files = [self._xdia_exe_path, self._msdia140_dll_path]
+        if platform.system() != "Windows":
+            files.append(self._xdialdr_path)
+        return files
+
+    def _is_xdia_installed(self) -> bool:
+        return all(file.exists() for file in self._get_xdia_install_list())
+
+    def _install_xdia(self):
+        if ".dev" in version:
+            # FIXME: On Windows, run cmake to build xdia
+            raise RuntimeError("xdia not available for dev version. Please build and install xdia manually.")
+
+        xdia_release_url = "https://github.com/mborgerson/xdia/releases/download"
+
+        # Install xdia
+        path = self._download_file(f"{xdia_release_url}/v{version}/xdia.zip")
+        with ZipFile(path) as z:
+            z.extractall(self._bin_dir)
+
+        # Install xdialdr, if required
+        if platform.system() != "Windows":
+            path = self._download_file(f"{xdia_release_url}/v{version}/xdialdr.tar.xz")
+            with tarfile.open(path, "r:xz") as tar:
+                tar.extractall(path=self._bin_dir)
+
+    @staticmethod
+    def _is_blink_required() -> bool:
+        return platform.system() != "Windows" and (platform.system() != "Linux" or platform.machine() != "x86_64")
+
+    def _get_blink_install_list(self) -> list[str]:
+        return [self._blink_path]
+
+    def _is_blink_installed(self) -> bool:
+        return all(file.exists() for file in self._get_blink_install_list())
+
+    @staticmethod
+    def gunzip(src, dst):
+        with gzip.open(src, "rb") as s_file, open(dst, "wb") as d_file:
+            shutil.copyfileobj(s_file, d_file, 65536)
+
+    def _install_blink(self):
+        blink_version = "1.1.0"
+        blink_release_platform_filename_parts = {
+            "darwin-arm64": "darwin-arm64.gz",  # ???
+            "darwin-x86_64": "darwin-x86_64.elf",  # ???
+            "freebsd-x86_64": "freebsd-x86_64.elf.gz",
+            "linux-aarch64": "linux-aarch64.elf.gz",
+            "linux-arm": "linux-arm.elf.gz",
+            "linux-i486": "linux-i486.elf.gz",
+            "linux-mips": "linux-mips.elf.gz",
+            "linux-mips64": "linux-mips64.elf.gz",
+            "linux-mips64el": "linux-mips64el.elf.gz",
+            "linux-mipsel": "linux-mipsel.elf.gz",
+            "linux-powerpc": "linux-powerpc.elf.gz",
+            "linux-powerpc64le": "linux-powerpc64le.elf.gz",
+            "linux-s390x": "linux-s390x.elf.gz",
+            "linux-x86_64": "linux-x86_64.elf.gz",
+            "openbsd-x86_64": "openbsd-x86_64.elf.gz",
+        }
+        tag = f"{platform.system().lower()}-{platform.machine().lower()}"
+        blink_platform = blink_release_platform_filename_parts.get(tag, None)
+        assert blink_platform is not None, "FIXME: Unhandled platform tag"
+
+        blink_filename = f"blink-{blink_version}-{blink_platform}"
+        blink_release_url = f"https://github.com/jart/blink/releases/download/{blink_version}/{blink_filename}"
+
+        self._download_file(blink_release_url)
+        if blink_filename.endswith(".gz"):
+            self.gunzip(blink_filename, self._blink_path)
+        else:
+            shutil.copyfile(blink_filename, self._blink_path)
+        self._mark_file_executable(self._blink_path)
+
+        blink_license_url = "https://raw.githubusercontent.com/jart/blink/master/LICENSE"
+        self._download_file(blink_license_url, self._blink_path.parent / "blink.LICENSE.txt")
+
+    def run(self):
+        if not self._is_xdia_installed():
+            self._install_xdia()
+
+        if self._is_blink_required():
+            if not self._is_blink_installed():
+                self._install_blink()
+
+    def get_outputs(self):
+        outputs = self._get_xdia_install_list()
+        if self._is_blink_required():
+            outputs += self._get_blink_install_list()
+        return outputs
+
+
+class build(_build):
+    sub_commands = _build.sub_commands + [('check_xdia_install', None)]
+
+
+setup(
+    cmdclass={
+        'build': build,
+        'check_xdia_install': CheckXdiaInstallation,
+        'bdist_wheel': CustomBdistWheel
+    },
+    packages=["pyxdia"],
+    package_data={"pyxdia": ["bin/*"]},
+)

pyxdia-0.0.0/tests/test_cli.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# pylint:disable=no-self-use
+
+import os
+import subprocess
+import sys
+import unittest
+
+from pyxdia import PDB
+
+
+PDB_TEST_FILES = os.getenv("PDB_TEST_FILES")
+assert PDB_TEST_FILES is not None, "Set environment variable PDB_TEST_FILES"
+
+
+class TestCli(unittest.TestCase):
+    """
+    Test pyxdia module command line interface
+    """
+
+    def test_cli(self):
+        subprocess.run([sys.executable, "-m", "pyxdia", os.path.join(PDB_TEST_FILES, "hello-wdm.pdb")], check=True)
+
+
+if __name__ == "__main__":
+    unittest.main()

pyxdia-0.0.0/tests/test_pdb.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# pylint:disable=no-self-use
+
+import os
+import unittest
+
+from pyxdia import PDB
+
+
+PDB_TEST_FILES = os.getenv("PDB_TEST_FILES")
+assert PDB_TEST_FILES is not None, "Set environment variable PDB_TEST_FILES"
+
+
+class TestPDB(unittest.TestCase):
+    """
+    Test PDB class.
+    """
+
+    def test_instantiate(self):
+        pdb = PDB(os.path.join(PDB_TEST_FILES, "hello-wdm.pdb"))
+
+    def test_list_globals(self):
+        pdb = PDB(os.path.join(PDB_TEST_FILES, "hello-wdm.pdb"))
+        assert len(pdb.globals) == 78
+
+        globals_by_name = {g["name"]: g for g in pdb.globals}
+        assert globals_by_name["DriverEntry"] == {
+            "addressOffset": 0,
+            "addressSection": 5,
+            "name": "DriverEntry",
+            "relativeVirtualAddress": 20480,
+            "symTag": "Function",
+            "undecoratedName": "DriverEntry",
+        }
+
+
+if __name__ == "__main__":
+    unittest.main()