symbolic 12.6.2__tar.gz

symbolic-12.6.2/MANIFEST.in

@@ -0,0 +1 @@
+include rustsrc.zip version.txt

symbolic-12.6.2/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.1
+Name: symbolic
+Version: 12.6.2
+Summary: A python library for dealing with symbol files and more.
+Home-page: UNKNOWN
+Author: Sentry
+Author-email: hello@sentry.io
+License: MIT
+Description: Symbolic
+        --------
+        
+        Symbolic is a Python library that can work with debug symbol files.
+        
+Platform: any
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown

symbolic-12.6.2/README

@@ -0,0 +1,4 @@
+Symbolic
+--------
+
+Symbolic is a Python library that can work with debug symbol files.

symbolic-12.6.2/setup.cfg

@@ -0,0 +1,11 @@
+[mypy]
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

symbolic-12.6.2/setup.py

@@ -0,0 +1,123 @@
+import os
+import re
+import sys
+import atexit
+import shutil
+import zipfile
+import tempfile
+import subprocess
+from setuptools import setup, find_packages
+from setuptools.command.sdist import sdist
+
+
+_version_re = re.compile(r'(?m)^version\s*=\s*"(.*?)"\s*$')
+
+
+DEBUG_BUILD = os.environ.get("SYMBOLIC_DEBUG") == "1"
+
+with open("README") as f:
+    readme = f.read()
+
+
+if os.path.isfile("../symbolic-cabi/Cargo.toml"):
+    with open("../symbolic-cabi/Cargo.toml") as f:
+        match = _version_re.search(f.read())
+        assert match is not None
+        version = match[1]
+else:
+    with open("version.txt") as f:
+        version = f.readline().strip()
+
+
+def vendor_rust_deps():
+    subprocess.Popen(["scripts/git-archive-all", "py/rustsrc.zip"], cwd="..").wait()
+
+
+def write_version():
+    with open("version.txt", "w") as f:
+        f.write("%s\n" % version)
+
+
+class CustomSDist(sdist):
+    def run(self):
+        vendor_rust_deps()
+        write_version()
+        sdist.run(self)
+
+
+def build_native(spec):
+    cmd = ["cargo", "build", "-p", "symbolic-cabi"]
+    if not DEBUG_BUILD:
+        cmd.append("--release")
+        target = "release"
+    else:
+        target = "debug"
+
+    # Step 0: find rust sources
+    if not os.path.isfile("../symbolic-cabi/Cargo.toml"):
+        scratchpad = tempfile.mkdtemp()
+
+        @atexit.register
+        def delete_scratchpad():
+            try:
+                shutil.rmtree(scratchpad)
+            except OSError:
+                pass
+
+        zf = zipfile.ZipFile("rustsrc.zip")
+        zf.extractall(scratchpad)
+        rust_path = scratchpad + "/rustsrc"
+    else:
+        rust_path = ".."
+        scratchpad = None
+
+    # Step 1: build the rust library
+    print("running `{}` ({} target)".format(" ".join(cmd), target))
+    build = spec.add_external_build(cmd=cmd, path=rust_path)
+
+    def find_dylib():
+        cargo_target = os.environ.get("CARGO_BUILD_TARGET")
+        if cargo_target:
+            in_path = f"target/{cargo_target}/{target}"
+        else:
+            in_path = "target/%s" % target
+        return build.find_dylib("symbolic_cabi", in_path=in_path)
+
+    rtld_flags = ["NOW"]
+    if sys.platform == "darwin":
+        rtld_flags.append("NODELETE")
+    spec.add_cffi_module(
+        module_path="symbolic._lowlevel",
+        dylib=find_dylib,
+        header_filename=lambda: build.find_header(
+            "symbolic.h", in_path="symbolic-cabi/include"
+        ),
+        rtld_flags=rtld_flags,
+    )
+
+
+setup(
+    name="symbolic",
+    version=version,
+    packages=find_packages(),
+    author="Sentry",
+    license="MIT",
+    author_email="hello@sentry.io",
+    description="A python library for dealing with symbol files and more.",
+    long_description=readme,
+    include_package_data=True,
+    package_data={"symbolic": ["py.typed", "_lowlevel.pyi"]},
+    long_description_content_type="text/markdown",
+    zip_safe=False,
+    platforms="any",
+    install_requires=["milksnake>=0.1.2"],
+    # Specify transitive dependencies manually that are required for the build because
+    # they are not resolved properly since upgrading to python 3.11 in manylinux.
+    # milksnake -> cffi -> pycparser
+    # milksnake specifies cffi>=1.6.0 as dependency while cffi does not specify a
+    # minimum version for pycparser
+    setup_requires=["milksnake>=0.1.2", "cffi>=1.6.0", "pycparser"],
+    python_requires=">=3.8",
+    milksnake_tasks=[build_native],
+    cmdclass={"sdist": CustomSDist},
+)

symbolic-12.6.2/symbolic/__init__.py

@@ -0,0 +1,23 @@
+__all__ = []
+
+
+def _import_all():
+    import pkgutil
+
+    glob = globals()
+    for _, modname, _ in pkgutil.iter_modules(__path__):
+        if modname[:1] == "_":
+            continue
+        mod = __import__("symbolic.%s" % modname, glob, glob, ["__name__"])
+        if not hasattr(mod, "__all__"):
+            continue
+        __all__.extend(mod.__all__)
+        for name in mod.__all__:
+            obj = getattr(mod, name)
+            if hasattr(obj, "__module__"):
+                obj.__module__ = "symbolic"
+            glob[name] = obj
+
+
+_import_all()
+del _import_all

symbolic-12.6.2/symbolic/cfi.py

@@ -0,0 +1,60 @@
+"""Minidump processing"""
+from __future__ import annotations
+
+import shutil
+from typing import IO
+
+from symbolic._lowlevel import lib, ffi
+from symbolic.utils import (
+    RustObject,
+    rustcall,
+    encode_path,
+    make_buffered_slice_reader,
+)
+
+__all__ = [
+    "CfiCache",
+    "CFICACHE_LATEST_VERSION",
+]
+
+# The most recent version for the CFI cache file format
+CFICACHE_LATEST_VERSION = rustcall(lib.symbolic_cficache_latest_version)
+
+
+class CfiCache(RustObject):
+    """A cache for call frame information (CFI) to improve native stackwalking"""
+
+    __dealloc_func__ = lib.symbolic_cficache_free
+
+    @classmethod
+    def open(cls, path: str) -> CfiCache:
+        """Loads a cficache from a file via mmap."""
+        return cls._from_objptr(rustcall(lib.symbolic_cficache_open, encode_path(path)))
+
+    @classmethod
+    def from_object(cls, obj: RustObject) -> CfiCache:
+        """Creates a cficache from the given object."""
+        return cls._from_objptr(
+            rustcall(lib.symbolic_cficache_from_object, obj._get_objptr())
+        )
+
+    @property
+    def version(self) -> str:
+        """Version of the file format."""
+        return self._methodcall(lib.symbolic_cficache_get_version)
+
+    @property
+    def is_latest_version(self) -> bool:
+        """Returns true if this is the latest file format."""
+        return self.version >= CFICACHE_LATEST_VERSION
+
+    def open_stream(self) -> IO[bytes]:
+        """Returns a stream to read files from the internal buffer."""
+        buf = self._methodcall(lib.symbolic_cficache_get_bytes)
+        size = self._methodcall(lib.symbolic_cficache_get_size)
+        return make_buffered_slice_reader(ffi.buffer(buf, size), self)
+
+    def write_to(self, f: IO[bytes]) -> None:
+        """Writes the CFI cache into a file object."""
+        # https://github.com/python/mypy/issues/15031
+        shutil.copyfileobj(self.open_stream(), f)  # type: ignore[misc]

symbolic-12.6.2/symbolic/common.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+from typing import overload
+
+from symbolic._lowlevel import lib, ffi
+from symbolic.utils import rustcall, encode_str, decode_str
+from symbolic import exceptions
+
+
+__all__ = ["arch_is_known", "arch_get_ip_reg_name", "normalize_arch", "parse_addr"]
+
+
+ignore_arch_exc = (exceptions.UnknownArchError,)
+
+
+# Make sure we init the lib and turn on rust backtraces
+os.environ["RUST_BACKTRACE"] = "1"
+ffi.init_once(lib.symbolic_init, "init")
+
+
+def arch_is_known(arch: str) -> bool:
+    """Checks if an architecture is known."""
+    if not isinstance(arch, str):
+        return False
+    return rustcall(lib.symbolic_arch_is_known, encode_str(arch))
+
+
+@overload
+def normalize_arch(arch: None) -> None:
+    ...
+
+
+@overload
+def normalize_arch(arch: str) -> str:
+    ...
+
+
+def normalize_arch(arch: str | None) -> str | None:
+    """Normalizes an architecture name."""
+    if arch is None:
+        return None
+    if not isinstance(arch, str):
+        raise ValueError("Invalid architecture: expected string")
+
+    normalized = rustcall(lib.symbolic_normalize_arch, encode_str(arch))
+    return decode_str(normalized, free=True)
+
+
+def arch_get_ip_reg_name(arch: str) -> str | None:
+    """Returns the ip register if known for this arch."""
+    try:
+        rv = rustcall(lib.symbolic_arch_ip_reg_name, encode_str(arch))
+        return str(decode_str(rv, free=True))
+    except ignore_arch_exc:
+        return None
+
+
+def parse_addr(x: int | str | None) -> int:
+    """Parses an address."""
+    if x is None:
+        return 0
+    if isinstance(x, int):
+        return x
+    if isinstance(x, str):
+        if x[:2] == "0x":
+            return int(x[2:], 16)
+        return int(x)
+    raise ValueError(f"Unsupported address format {x!r}")

symbolic-12.6.2/symbolic/debuginfo.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import bisect
+from weakref import WeakValueDictionary
+from typing import overload, Generator
+
+from symbolic._lowlevel import lib, ffi
+from symbolic.utils import RustObject, rustcall, decode_str, encode_str
+from symbolic.common import parse_addr, arch_is_known
+from symbolic.symcache import SymCache
+from symbolic.cfi import CfiCache
+
+
+__all__ = [
+    "Archive",
+    "Object",
+    "ObjectLookup",
+    "BcSymbolMap",
+    "UuidMapping",
+    "id_from_breakpad",
+    "normalize_code_id",
+    "normalize_debug_id",
+]
+
+
+class Archive(RustObject):
+    __dealloc_func__ = lib.symbolic_archive_free
+
+    _objcache: WeakValueDictionary[int, Object]
+
+    @classmethod
+    def open(self, path: str | bytes) -> Archive:
+        """Opens an archive from a given path."""
+        if isinstance(path, str):
+            path = path.encode("utf-8")
+        return Archive._from_objptr(rustcall(lib.symbolic_archive_open, path))
+
+    @classmethod
+    def from_bytes(self, data: bytes) -> Archive:
+        """Loads an archive from a binary buffer."""
+        return Archive._from_objptr(
+            rustcall(lib.symbolic_archive_from_bytes, data, len(data))
+        )
+
+    @property
+    def object_count(self) -> int:
+        """The number of objects in this archive."""
+        return self._methodcall(lib.symbolic_archive_object_count)
+
+    def iter_objects(self) -> Generator[Object, None, None]:
+        """Iterates over all objects."""
+        for idx in range(self.object_count):
+            try:
+                yield self._get_object(idx)
+            except LookupError:
+                pass
+
+    def get_object(
+        self, debug_id: str | None = None, arch: str | None = None
+    ) -> Object:
+        """Get an object by either arch or id."""
+        if debug_id is not None:
+            debug_id = debug_id.lower()
+        for obj in self.iter_objects():
+            if obj.debug_id == debug_id or obj.arch == arch:
+                return obj
+        raise LookupError("Object not found")
+
+    def _get_object(self, idx: int) -> Object:
+        """Returns the object at a certain index."""
+        cache = getattr(self, "_objcache", None)
+        if cache is None:
+            cache = self._objcache = WeakValueDictionary()
+        rv = cache.get(idx)
+        if rv is not None:
+            return rv
+        ptr = self._methodcall(lib.symbolic_archive_get_object, idx)
+        if ptr == ffi.NULL:
+            raise LookupError("No object #%d" % idx)
+        rv = cache[idx] = Object._from_objptr(ptr)
+        return rv
+
+
+class Object(RustObject):
+    __dealloc_func__ = lib.symbolic_object_free
+
+    @property
+    def arch(self) -> str:
+        """The architecture of the object."""
+        # make it an ascii bytestring on 2.x
+        arch = self._methodcall(lib.symbolic_object_get_arch)
+        return str(decode_str(arch, free=True))
+
+    @property
+    def code_id(self) -> str | None:
+        """The code identifier of the object. Returns None if there is no code id."""
+        code_id = self._methodcall(lib.symbolic_object_get_code_id)
+        code_id = decode_str(code_id, free=True)
+        if code_id:
+            return code_id
+        return None
+
+    @property
+    def debug_id(self) -> str:
+        """The debug identifier of the object."""
+        debug_id = self._methodcall(lib.symbolic_object_get_debug_id)
+        return decode_str(debug_id, free=True)
+
+    @property
+    def kind(self) -> str:
+        """The kind of the object (e.g. executable, debug file, library, ...)."""
+        kind = self._methodcall(lib.symbolic_object_get_kind)
+        return str(decode_str(kind, free=True))
+
+    @property
+    def file_format(self) -> str:
+        """The file format of the object file (e.g. MachO, ELF, ...)."""
+        format = self._methodcall(lib.symbolic_object_get_file_format)
+        return str(decode_str(format, free=True))
+
+    @property
+    def features(self) -> frozenset[str]:
+        """The list of features offered by this debug file."""
+        struct = self._methodcall(lib.symbolic_object_get_features)
+        features = set()
+        if struct.symtab:
+            features.add("symtab")
+        if struct.debug:
+            features.add("debug")
+        if struct.unwind:
+            features.add("unwind")
+        if struct.sources:
+            features.add("sources")
+        return frozenset(features)
+
+    def make_symcache(self) -> SymCache:
+        """Creates a symcache from the object."""
+        return SymCache._from_objptr(
+            self._methodcall(lib.symbolic_symcache_from_object)
+        )
+
+    def make_cficache(self) -> CfiCache:
+        """Creates a cficache from the object."""
+        return CfiCache._from_objptr(
+            self._methodcall(lib.symbolic_cficache_from_object)
+        )
+
+    def __repr__(self) -> str:
+        return "<Object {} {!r}>".format(
+            self.debug_id,
+            self.arch,
+        )
+
+
+class ObjectRef:
+    """Holds a reference to an object in a format."""
+
+    def __init__(self, data):
+        self.addr = parse_addr(data.get("image_addr"))
+        # not a real address but why handle it differently
+        self.size = parse_addr(data.get("image_size"))
+        self.vmaddr = data.get("image_vmaddr")
+        self.code_id = data.get("code_id")
+        self.code_file = data.get("code_file") or data.get("name")
+        self.debug_id = normalize_debug_id(
+            data.get("debug_id") or data.get("id") or data.get("uuid") or None
+        )
+        self.debug_file = data.get("debug_file")
+
+        if data.get("arch") is not None and arch_is_known(data["arch"]):
+            self.arch = data["arch"]
+        else:
+            self.arch = None
+
+        # Legacy alias for backwards compatibility
+        self.name = self.code_file
+
+    def __repr__(self) -> str:
+        return "<ObjectRef {} {!r}>".format(
+            self.debug_id,
+            self.arch,
+        )
+
+
+class ObjectLookup:
+    """Helper to look up objects based on the info a client provides."""
+
+    def __init__(self, objects):
+        self._addresses = []
+        self._by_addr = {}
+        self.objects = {}
+        for ref_data in objects:
+            obj = ObjectRef(ref_data)
+            self._addresses.append(obj.addr)
+            self._by_addr[obj.addr] = obj
+            self.objects[obj.debug_id] = obj
+        self._addresses.sort()
+
+    def iter_objects(self):
+        """Iterates over all objects."""
+        return self.objects.values()
+
+    def get_debug_ids(self):
+        """Returns a list of ids."""
+        return sorted(self.objects)
+
+    def iter_debug_ids(self):
+        """Iterates over all ids."""
+        return iter(self.objects)
+
+    def find_object(self, addr):
+        """Given an instruction address this locates the image this address
+        is contained in.
+        """
+        idx = bisect.bisect_right(self._addresses, parse_addr(addr))
+        if idx > 0:
+            rv = self._by_addr[self._addresses[idx - 1]]
+            if not rv.size or parse_addr(addr) < rv.addr + rv.size:
+                return rv
+
+    def get_object(self, debug_id):
+        """Finds an object by the given debug id."""
+        return self.objects.get(debug_id)
+
+
+class BcSymbolMap(RustObject):
+    """Object representing an Apple ``.bcsymbolmap`` file."""
+
+    __dealloc_func__ = lib.symbolic_bcsymbolmap_free
+
+    @classmethod
+    def open(cls, path: str | bytes) -> BcSymbolMap:
+        """Parses a BCSymbolMap file."""
+        if isinstance(path, str):
+            path = path.encode("utf-8")
+        return cls._from_objptr(rustcall(lib.symbolic_bcsymbolmap_open, path))
+
+
+class UuidMapping(RustObject):
+    """Object representing a mapping from one DebugID to another."""
+
+    __dealloc_func__ = lib.symbolic_uuidmapping_free
+
+    @classmethod
+    def from_plist(cls, debug_id: str, path: str | bytes) -> UuidMapping:
+        """Parses a PList."""
+        if isinstance(path, str):
+            path = path.encode("utf-8")
+        return cls._from_objptr(
+            rustcall(lib.symbolic_uuidmapping_from_plist, encode_str(debug_id), path)
+        )
+
+
+def id_from_breakpad(breakpad_id):
+    """Converts a Breakpad CodeModuleId to DebugId"""
+    if breakpad_id is None:
+        return None
+
+    s = encode_str(breakpad_id)
+    id = rustcall(lib.symbolic_id_from_breakpad, s)
+    return decode_str(id, free=True)
+
+
+def normalize_code_id(code_id):
+    """Normalizes a code identifier to default representation"""
+    if code_id is None:
+        return None
+
+    s = encode_str(code_id)
+    id = rustcall(lib.symbolic_normalize_code_id, s)
+    return decode_str(id, free=True)
+
+
+@overload
+def normalize_debug_id(debug_id: None) -> None:
+    ...
+
+
+@overload
+def normalize_debug_id(debug_id: str) -> str:
+    ...
+
+
+def normalize_debug_id(debug_id: str | None) -> str | None:
+    """Normalizes a debug identifier to default representation"""
+    if debug_id is None:
+        return None
+
+    s = encode_str(debug_id)
+    id = rustcall(lib.symbolic_normalize_debug_id, s)
+    return decode_str(id, free=True)

symbolic-12.6.2/symbolic/exceptions.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from symbolic._lowlevel import lib
+
+
+__all__ = ["SymbolicError"]
+exceptions_by_code: dict[int, type[SymbolicError]] = {}
+
+
+class SymbolicError(Exception):
+    if TYPE_CHECKING:
+        code: int
+    else:
+        code = None
+
+    def __init__(self, msg):
+        Exception.__init__(self)
+        self.message = msg
+        self.rust_info = None
+
+    def __str__(self) -> str:
+        rv = self.message
+        if self.rust_info is not None:
+            return f"{rv}\n\n{self.rust_info}"
+        return rv
+
+
+def _make_error(
+    error_name: str, base: type[SymbolicError] = SymbolicError, code: int | None = None
+) -> type[SymbolicError]:
+    class Exc(base):  # type: ignore[misc,valid-type]
+        pass
+
+    Exc.__name__ = Exc.__qualname__ = error_name
+    if code is not None:
+        Exc.code = code
+    globals()[Exc.__name__] = Exc
+    __all__.append(Exc.__name__)
+    return Exc
+
+
+def _get_error_base(error_name: str) -> type[SymbolicError]:
+    pieces = error_name.split("Error", 1)
+    if len(pieces) == 2 and pieces[0] and pieces[1]:
+        base_error_name = pieces[0] + "Error"
+        base_class = globals().get(base_error_name)
+        if base_class is None:
+            base_class = _make_error(base_error_name)
+        return base_class
+    return SymbolicError
+
+
+def _make_exceptions() -> None:
+    for attr in dir(lib):
+        if not attr.startswith("SYMBOLIC_ERROR_CODE_"):
+            continue
+
+        error_name = attr[20:].title().replace("_", "")
+        base = _get_error_base(error_name)
+        exc = _make_error(error_name, base=base, code=getattr(lib, attr))
+        exceptions_by_code[exc.code] = exc
+
+
+_make_exceptions()
+
+if TYPE_CHECKING:
+    # treat unknown attribute names as exception types
+    def __getattr__(name: str) -> type[SymbolicError]:
+        ...