objutils 0.10.3__tar.gz → 0.10.5__tar.gz

{objutils-0.10.3 → objutils-0.10.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: objutils
-Version: 0.10.3
+Version: 0.10.5
 Summary: Objectfile library for Python
 License: GPLv2
 License-File: LICENSE
@@ -36,7 +36,7 @@ Readme
 .. image:: https://github.com/christoph2/objutils/raw/master/docs/objutils_banner.png
     :align: center
 
-|PyPI| |Python Versions| |License: GPLv2| |Code style: black|
+|PyPI| |Python Versions| |License: GPLv2| |Code style: black| |Ask DeepWiki| |PDF Manual|
 
 
 Binary data stored in hex-files is in widespread use especially in embedded systems applications.
@@ -467,4 +467,8 @@ If you contribute code to this project, you are implicitly allowing your code to
    :target: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
+.. |Ask DeepWiki| image:: https://deepwiki.com/badge.svg
+   :target: https://deepwiki.com/christoph2/objutils
+.. |PDF Manual| image:: https://img.shields.io/badge/docs-PDF%20manual-blue.svg
+   :target: https://objutils.readthedocs.io/_/downloads/en/latest/pdf/
 

{objutils-0.10.3 → objutils-0.10.5}/docs/README.rst

@@ -5,7 +5,7 @@ Readme
 .. image:: https://github.com/christoph2/objutils/raw/master/docs/objutils_banner.png
     :align: center
 
-|PyPI| |Python Versions| |License: GPLv2| |Code style: black|
+|PyPI| |Python Versions| |License: GPLv2| |Code style: black| |Ask DeepWiki| |PDF Manual|
 
 
 Binary data stored in hex-files is in widespread use especially in embedded systems applications.
@@ -436,3 +436,7 @@ If you contribute code to this project, you are implicitly allowing your code to
    :target: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black
+.. |Ask DeepWiki| image:: https://deepwiki.com/badge.svg
+   :target: https://deepwiki.com/christoph2/objutils
+.. |PDF Manual| image:: https://img.shields.io/badge/docs-PDF%20manual-blue.svg
+   :target: https://objutils.readthedocs.io/_/downloads/en/latest/pdf/

{objutils-0.10.3 → objutils-0.10.5}/objutils/__init__.py

@@ -13,7 +13,7 @@ Registers CODECS and implements an interface to them.
 The first parameter is always the codec name.
 """
 
-__version__ = "0.10.3"
+__version__ = "0.10.5"
 
 __all__ = [
     "Image",

{objutils-0.10.3 → objutils-0.10.5}/objutils/cosmac.py

@@ -5,14 +5,11 @@ This module handles the RCA Cosmac hex format, used with RCA 1802/1804/1805
 microprocessors and COSMAC development systems.
 
 Format specification:
-
 - Four data record formats with optional address:
-
-  1. ``!MAAAA DD`` – Full format with start symbol
-  2. ``?MAAAA DD`` – Alternate start symbol
-  3. ``AAAA DD`` – Address only (no symbol)
-  4. ``DD`` – Data only (address continues from previous)
-
+  1. !MAAAA DD - Full format with start symbol
+  2. ?MAAAA DD - Alternate start symbol
+  3. AAAA DD - Address only (no symbol)
+  4. DD - Data only (address continues from previous)
 - M: Memory identifier (single hex digit)
 - AAAA: 16-bit address (hex)
 - DD: Data bytes (hex, space-separated)

{objutils-0.10.3 → objutils-0.10.5}/objutils/elf/model.py

@@ -130,7 +130,7 @@ from sqlalchemy.engine import Engine
 from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.ext.hybrid import hybrid_method, hybrid_property
 from sqlalchemy.orm import Session, declarative_base, relationship
-from sqlalchemy.pool import NullPool
+from sqlalchemy.pool import NullPool, StaticPool
 from sqlalchemy.sql import func
 
 from objutils.elf import defs
@@ -1312,6 +1312,11 @@ class Model:
             # else:
             self.dbname = filename
 
+        # NullPool creates a fresh connection each time, which doesn't work for
+        # :memory: SQLite (each connection gets its own empty database).
+        # Use StaticPool for in-memory databases to reuse the same connection.
+        pool_class = StaticPool if self.dbname == ":memory:" else NullPool
+
         self._engine = create_engine(
             f"sqlite:///{self.dbname}",
             echo=debug,
@@ -1319,7 +1324,7 @@ class Model:
                 "detect_types": sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES,
                 "timeout": SQLITE_TIMEOUT_SECONDS,
             },
-            poolclass=NullPool,
+            poolclass=pool_class,
             native_datetime=True,
         )
 

{objutils-0.10.3 → objutils-0.10.5}/objutils/emon52.py

@@ -5,9 +5,7 @@ This module handles the EMON52 hex format used by the Elektor
 Electronics EMON52 8052 development system.
 
 Format specification:
-
-- Data records: ``LL AAAA:DD CCCC``
-
+- Data records: LL AAAA:DD CCCC
   - LL: Length/byte count (hex)
   - AAAA: 16-bit address (hex)
   - DD: Data bytes (hex, space-separated)

{objutils-0.10.3 → objutils-0.10.5}/objutils/etek.py

@@ -5,24 +5,18 @@ This module handles the Extended Tektronix hex format, an extension
 of the standard Tektronix format with 24-bit addressing and symbol support.
 
 Format specification:
-
-- Data records: ``%LL6CCAAAAADD``
-
-  - LL: Length field (``2 * (data_length + 5)`` in hex)
+- Data records: %LL6CCAAAAADD
+  - LL: Length field (2 * (data_length + 5) in hex)
   - 6: Record type identifier
   - CC: Checksum (nibble sum)
   - AAAAAA: 24-bit address (hex)
   - DD: Data bytes (hex)
-
-- Symbol records: ``%LL3CCU``
-
+- Symbol records: %LL3CCU
   - LL: Length field
   - 3: Symbol type identifier
   - CC: Checksum
   - U: Symbol string (name + address)
-
-- EOF records: ``%LL8CCAAAAADD``
-
+- EOF records: %LL8CCAAAAADD
   - 8: EOF type identifier
 """
 

{objutils-0.10.3 → objutils-0.10.5}/objutils/hexfile.py

@@ -791,7 +791,7 @@ class Reader(BaseType):
         self.stats = Statistics()
         self.valid = True
         self.formats: list[tuple[int, re.Pattern[str]]] = []
-        self.base_address = 0   # Base address for relative addressing (if applicable - mainly Intel HEX)
+        self.base_address = 0  # Base address for relative addressing (if applicable - mainly Intel HEX)
 
         # Parse FORMAT_SPEC into compiled patterns
         if isinstance(self.FORMAT_SPEC, str):

{objutils-0.10.3 → objutils-0.10.5}/objutils/ihex.py

@@ -25,10 +25,9 @@ __copyright__ = """
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 """
 
-import operator
 from collections.abc import Mapping, Sequence
 from functools import partial
-from typing import Any, Callable, Optional
+from typing import Any, Optional
 
 import objutils.checksums as checksums
 import objutils.hexfile as hexfile

{objutils-0.10.3 → objutils-0.10.5}/objutils/image.py

@@ -716,11 +716,20 @@ class Image:
         array: Any,
         dtype: str,
         byte_order: str = "MSB_LAST",
-        order: Optional[str] = None,
+        index_mode: str = "ROW_DIR",
         **kws: Any,
     ) -> None:
-        """Write a NumPy ndarray using ASAM datatype and ECU byte order semantics."""
-        self._call_address_function("write_asam_ndarray", addr, array, dtype, byte_order, order=order, **kws)
+        """Write a NumPy ndarray using ASAM datatype and ECU byte order semantics.
+
+        Args:
+            addr: Absolute memory address to write to.
+            array: NumPy ndarray (shape in numpy convention).
+            dtype: ASAM datatype name.
+            byte_order: ASAM byte order string.
+            index_mode: ``"ROW_DIR"`` (default) or ``"COLUMN_DIR"``.
+            **kws: Passed through to section method.
+        """
+        self._call_address_function("write_asam_ndarray", addr, array, dtype, byte_order, index_mode=index_mode, **kws)
 
     def read_ndarray(
         self,
@@ -755,12 +764,27 @@ class Image:
         length: int,
         dtype: str,
         shape: Optional[tuple[int, ...]] = None,
-        order: Optional[str] = None,
         byte_order: str = "MSB_LAST",
+        index_mode: str = "ROW_DIR",
         **kws: Any,
     ) -> Any:
-        """Read a NumPy ndarray using ASAM datatype and ECU byte order semantics."""
-        return self._call_address_function("read_asam_ndarray", addr, length, dtype, shape, order, byte_order, **kws)
+        """Read a NumPy ndarray using ASAM datatype and ECU byte order semantics.
+
+        Args:
+            addr: Start address to read from.
+            length: Number of **elements** (not bytes).
+            dtype: ASAM datatype name.
+            shape: Dimensions in **ASAM** order ``(X, Y, Z, ...)``.
+            byte_order: ASAM byte order string.
+            index_mode: ``"ROW_DIR"`` (default) or ``"COLUMN_DIR"``.
+            **kws: Passed through to section method.
+
+        Returns:
+            NumPy ndarray with shape in numpy convention.
+        """
+        return self._call_address_function(
+            "read_asam_ndarray", addr, length, dtype, shape=shape, byte_order=byte_order, index_mode=index_mode, **kws
+        )
 
     def read_string(self, addr: int, encoding: str = "latin1", length: int = -1, **kws: Any) -> str:
         """Read string from image.

{objutils-0.10.3 → objutils-0.10.5}/objutils/pecoff/__init__.py

@@ -739,12 +739,12 @@ class SectionAPI:
     def __init__(self, parent: PeParser):
         self.parent = parent
 
-        def fetch(self, name_pattern: str | None = None) -> list[model.Pe_Section]:
-            self.parent.create_db_on_demand()
-            if self.parent.db is None:
-                raise RuntimeError("PE database is not initialized")
-            with self.parent.db.session() as ses:
-                q = ses.query(model.Pe_Section)
+    def fetch(self, name_pattern: str | None = None) -> list[model.Pe_Section]:
+        self.parent.create_db_on_demand()
+        if self.parent.db is None:
+            raise RuntimeError("PE database is not initialized")
+        with self.parent.db.session() as ses:
+            q = ses.query(model.Pe_Section)
             if name_pattern:
                 q = q.filter(model.Pe_Section.name.like(f"%{name_pattern}%"))
             return q.order_by(model.Pe_Section.vaddr).all()
@@ -754,12 +754,12 @@ class SymbolAPI:
     def __init__(self, parent: PeParser):
         self.parent = parent
 
-        def fetch(self, name_pattern: str | None = None) -> list[model.Pe_Symbol]:
-            self.parent.create_db_on_demand()
-            if self.parent.db is None:
-                raise RuntimeError("PE database is not initialized")
-            with self.parent.db.session() as ses:
-                q = ses.query(model.Pe_Symbol)
+    def fetch(self, name_pattern: str | None = None) -> list[model.Pe_Symbol]:
+        self.parent.create_db_on_demand()
+        if self.parent.db is None:
+            raise RuntimeError("PE database is not initialized")
+        with self.parent.db.session() as ses:
+            q = ses.query(model.Pe_Symbol)
             if name_pattern:
                 q = q.filter(model.Pe_Symbol.name.like(f"%{name_pattern}%"))
             return q.order_by(model.Pe_Symbol.value).all()

{objutils-0.10.3 → objutils-0.10.5}/objutils/pecoff/model.py

@@ -114,7 +114,10 @@ def StdInteger(default=0, primary_key=False, unique=False, nullable=False, index
             count = StdInteger(default=0, index=True)
         ```
     """
-    return Column(Integer, primary_key=primary_key, unique=unique, nullable=nullable, index=index, default=default)
+    kw = dict(primary_key=primary_key, unique=unique, nullable=nullable, index=index)
+    if not primary_key:
+        kw["default"] = default
+    return Column(Integer, **kw)
 
 
 class MixInBase:

{objutils-0.10.3 → objutils-0.10.5}/objutils/scripts/oj_coff_extract.py

@@ -52,6 +52,14 @@ def main(argv: list[str] | None = None) -> int:
         dest="include",
         default=None,
     )
+    parser.add_argument(
+        "-r",
+        "--no-image-base",
+        help="Use relative virtual addresses (RVAs) instead of absolute addresses. Required for 64-bit PE files "
+        "whose image base pushes addresses beyond 32-bit hex format limits.",
+        dest="no_image_base",
+        action="store_true",
+    )
     parser.add_argument("-n", help="Number of data bytes per line", dest="row_length", default=16, type=int)
     args = parser.parse_args(argv)
 
@@ -60,17 +68,33 @@ def main(argv: list[str] | None = None) -> int:
     except (OSError, ValueError, RuntimeError) as e:
         print(f"\n'{args.pe_file}' is not valid PE/COFF file. Raised exception: '{repr(e)}'.")
         return 1
-    print("\nExtracting from...\n")
+
+    add_image_base = not args.no_image_base
+    image_base = pp.image_base()
+    if args.no_image_base:
+        print(f"\nUsing relative addresses (image base {image_base:#010x} subtracted).\n")
+    else:
+        print(f"\nUsing absolute addresses (image base: {image_base:#010x}).\n")
+
+    print("Extracting from...\n")
     print("Section                   Address    Length")
     print("-" * 45)
     img = pp.create_image(
         callback=callback,
         join=args.join,
+        add_image_base=add_image_base,
         exclude_pattern=args.exclude or "",
         include_pattern=args.include or "",
     )
     if img:
-        dump(args.file_type, args.output_file_name, img, row_length=args.row_length)
+        try:
+            dump(args.file_type, args.output_file_name, img, row_length=args.row_length)
+        except Exception as e:
+            if "address too large" in str(e).lower():
+                print(f"\nError: {e}")
+                print(f"Hint: Try using --no-image-base / -r to use relative addresses (subtract image base {image_base:#010x}).")
+                return 1
+            raise
         print(f"HEX image written to: '{args.output_file_name}' [{len(img)} total bytes]")
     return 0
 

{objutils-0.10.3 → objutils-0.10.5}/objutils/scripts/oj_coff_syms.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 import argparse
 
-from objutils.pecoff import PeParser
+from objutils.pecoff import PeParser, SymbolAPI
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -35,7 +35,7 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     # Fetch via SymbolAPI to ensure DB is created/reused
-    syms = pp.SymbolAPI(pp).fetch(name_pattern=args.pattern)  # type: ignore[attr-defined]
+    syms = SymbolAPI(pp).fetch(name_pattern=args.pattern)
     # Fallback: if SymbolAPI attr is not present (static type), use direct list
     if not syms and pp.symbols:
         syms = [type("_S", (), s) for s in pp.symbols]  # quick adapter for printing

objutils-0.10.5/objutils/scripts/oj_dwarf_info.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python
+"""DWARF database inspector (read-only).
+
+Lists compilation units or traverses DIE attributes from an existing ``.prgdb``
+database. This script intentionally does **not** perform DWARF import; use
+``oj-dwarf-import`` to build the database first.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from objutils.dwarf.constants import Tag
+from objutils.dwarf.traverser import AttributeParser
+from objutils.elf import model
+
+
+def _parse_offset(text: str) -> int:
+    try:
+        return int(text, 0)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"Invalid offset '{text}'") from exc
+
+
+def _attr_value(die: Any, name: str) -> Any:
+    attrs = getattr(die, "attributes_map", {}) or {}
+    attr = attrs.get(name)
+    return None if attr is None else getattr(attr, "raw_value", None)
+
+
+def _print_cus(cus: Iterable[Any], *, quiet: bool) -> None:
+    if quiet:
+        return
+    print("Compilation Units:")
+    print("-------------------")
+    for idx, cu in enumerate(cus, 1):
+        name = _attr_value(cu, "name") or ""
+        low_pc = _attr_value(cu, "low_pc")
+        high_pc = _attr_value(cu, "high_pc")
+        low_pc_str = f"0x{int(low_pc):08x}" if low_pc is not None else "-"
+        high_pc_str = f"0x{int(high_pc):08x}" if high_pc is not None else "-"
+        print(f"[{idx:03d}] off=0x{int(cu.offset):08x} name={name} range={low_pc_str}..{high_pc_str}")
+
+
+def _print_summary(session, *, quiet: bool) -> None:
+    if quiet:
+        return
+    die_count = session.query(model.DebugInformationEntry).count()
+    attr_count = session.query(model.DIEAttribute).count()
+    print(f"DIEs: {die_count:,}")
+    print(f"Attributes: {attr_count:,}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Inspect DWARF debug info stored in a .prgdb database (no import).")
+    parser.add_argument("db", help="Path to .prgdb database generated by oj-dwarf-import")
+    parser.add_argument("--quiet", "-q", action="store_true", help="Suppress non-error output")
+    parser.add_argument("--list-cus", action="store_true", help="List compile units")
+    parser.add_argument("--summary", action="store_true", help="Print DIE/attribute counts")
+    parser.add_argument(
+        "--walk-attrs",
+        action="store_true",
+        help="Traverse DIE attributes with AttributeParser (starts at first DIE unless --offset is set).",
+    )
+    parser.add_argument(
+        "--offset",
+        type=_parse_offset,
+        help="Absolute DIE offset (decimal or 0x-prefixed hex) used for --walk-attrs start point.",
+    )
+    args = parser.parse_args(argv)
+
+    db_path = Path(args.db)
+    if db_path.suffix.lower() != model.DB_EXTENSION:
+        parser.error(f"Expected a '{model.DB_EXTENSION}' database; got '{db_path}'")
+    if not db_path.exists():
+        parser.error(f"Database not found: {db_path}")
+
+    post_actions = args.list_cus or args.summary or args.walk_attrs
+    if not post_actions:
+        args.list_cus = True
+
+    try:
+        db = model.Model(str(db_path))
+    except (OSError, SQLAlchemyError, ValueError) as exc:
+        if not args.quiet:
+            print(f"Failed to open database '{db_path}': {exc}")
+        return 4
+
+    try:
+        session = db.session
+        if args.summary:
+            _print_summary(session, quiet=args.quiet)
+
+        if args.list_cus or args.walk_attrs:
+            DIE = model.DebugInformationEntry
+            raw_cus = session.query(DIE).filter(DIE.tag == Tag.compile_unit).order_by(DIE.offset, DIE.cu_start).all()
+            seen = set()
+            cus = []
+            for cu in raw_cus:
+                key = (cu.offset, cu.cu_start)
+                if key in seen:
+                    continue
+                seen.add(key)
+                cus.append(cu)
+            if args.list_cus:
+                _print_cus(cus, quiet=args.quiet)
+
+            if args.walk_attrs:
+                ap = AttributeParser(session)
+                if args.offset is not None:
+                    start_die = session.query(DIE).filter(DIE.offset == int(args.offset)).first()
+                    if start_die is None:
+                        if not args.quiet:
+                            print(f"No DIE found at offset 0x{int(args.offset):08x}.")
+                        return 5
+                    ap.traverse_tree(start_die)
+                else:
+                    if not cus:
+                        if not args.quiet:
+                            print("No DebugInformationEntry available in the database to traverse.")
+                        return 5
+                    for cu in cus:
+                        ap.traverse_tree(cu)
+    except (OSError, SQLAlchemyError, RuntimeError, ValueError) as exc:
+        if not args.quiet:
+            print(f"Traversal failed: {exc}")
+        return 5
+    finally:
+        try:
+            db.close()
+        except SQLAlchemyError:
+            pass
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())