objutils 0.10.11__tar.gz → 0.10.13__tar.gz

{objutils-0.10.11 → objutils-0.10.13}/.pre-commit-config.yaml

@@ -42,7 +42,7 @@ repos:
         args: ["--line-length=132"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.20
+    rev: v0.15.21
     hooks:
       - id: ruff
         args: ["--fix", "--exit-non-zero-on-fix"]

{objutils-0.10.11 → objutils-0.10.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: objutils
-Version: 0.10.11
+Version: 0.10.13
 Summary: Objectfile library for Python
 Keywords: hex files,intel hex,s19,srec,srecords,object files,map files,embedded,microcontroller,ECU,shf,rfc4194
 Author-Email: Christoph Schueler <cpu12.gems@googlemail.com>
@@ -10,11 +10,12 @@ Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development
 Classifier: Topic :: Scientific/Engineering
 Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Project-URL: Repository, https://www.github.com/Christoph2/objutils
 Requires-Python: <4.0,>=3.10
 Requires-Dist: construct>=2.10.70
@@ -22,6 +23,7 @@ Requires-Dist: mako>=1.3.3
 Requires-Dist: sqlalchemy>=2.0.29
 Requires-Dist: rich>=14.2
 Requires-Dist: numpy>=2.2.5
+Requires-Dist: ufilename<0.2.0,>=0.1.1
 Provides-Extra: dev
 Requires-Dist: bumpver>=2023.1129; extra == "dev"
 Requires-Dist: pre-commit>=3.7.0; extra == "dev"
@@ -78,11 +80,14 @@ Features
 
 - Read ELF files (including symbols) and extract loadable sections.
 - Inspect PE/COFF files and symbols (optional PDB support).
+- Merge multiple HEX files into one (``oj-hex-merge``).
+- Split HEX files into separate sections (``oj-hex-split``).
 - Typed access (scalars, arrays, strings) to binary data.
 
 Recent improvements
 -------------------
 
+- New ``oj-hex-merge`` and ``oj-hex-split`` CLI tools for combining and partitioning HEX files.
 - New ``oj-dwarf-import`` CLI replaces ``dwarfer.py``/``cu_info.py`` for DWARF imports, CU listing, summaries, and attribute traversal.
 - Faster DWARF imports: batched ORM writes, quiet flag propagation, and safe DWARF expression evaluation keep large ELF files stable.
 - Exception handling and typing tightened across DWARF/ELF/PECOFF modules and public APIs to surface real errors without masking them.
@@ -215,6 +220,14 @@ And loaded again...
    Section(address = 0X00001000, length = 16, data = b'Hello HEX world!')
    Section(address = 0X00002000, length = 16, data = b'\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10')
 
+Or split it into its sections...
+
+.. code-block:: python
+
+   images = img1.split()
+   for i, img in enumerate(images):
+       dump("srec", f"part_{i}.srec", img)
+
 This leads to the conversion idiom.
 
 .. code-block:: python

{objutils-0.10.11 → objutils-0.10.13}/docs/README.rst

@@ -44,11 +44,14 @@ Features
 
 - Read ELF files (including symbols) and extract loadable sections.
 - Inspect PE/COFF files and symbols (optional PDB support).
+- Merge multiple HEX files into one (``oj-hex-merge``).
+- Split HEX files into separate sections (``oj-hex-split``).
 - Typed access (scalars, arrays, strings) to binary data.
 
 Recent improvements
 -------------------
 
+- New ``oj-hex-merge`` and ``oj-hex-split`` CLI tools for combining and partitioning HEX files.
 - New ``oj-dwarf-import`` CLI replaces ``dwarfer.py``/``cu_info.py`` for DWARF imports, CU listing, summaries, and attribute traversal.
 - Faster DWARF imports: batched ORM writes, quiet flag propagation, and safe DWARF expression evaluation keep large ELF files stable.
 - Exception handling and typing tightened across DWARF/ELF/PECOFF modules and public APIs to surface real errors without masking them.
@@ -181,6 +184,14 @@ And loaded again...
    Section(address = 0X00001000, length = 16, data = b'Hello HEX world!')
    Section(address = 0X00002000, length = 16, data = b'\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f\x10')
 
+Or split it into its sections...
+
+.. code-block:: python
+
+   images = img1.split()
+   for i, img in enumerate(images):
+       dump("srec", f"part_{i}.srec", img)
+
 This leads to the conversion idiom.
 
 .. code-block:: python

{objutils-0.10.11 → objutils-0.10.13}/docs/scripts.rst

@@ -278,22 +278,19 @@ oj_hex_info
 
 .. code-block:: shell
 
-    usage: oj-hex-info [-h] [-d]
-                      {ash,cosmac,emon52,etek,fpc,ihex,mostec,rca,shf,sig,srec,tek,titxt}
-                      hex_file
+    usage: oj-hex-info [-h] [-d] [-p]
+                      [file_type] hex_file
 
     Displays informations about HEX files.
 
     positional arguments:
-      {ash,cosmac,emon52,etek,fpc,ihex,mostec,rca,shf,sig,srec,tek,titxt}
-                            file type
+      file_type             file type (optional, if omitted it is probed)
       hex_file              HEX file
 
     optional arguments:
       -h, --help            show this help message and exit
       -d, --dump            hexdump contents
-
-Filetype is a required argument (no auto-probing yet).
+      -p, --print-filename  Print filename including path
 
 Run it as follows:
 
@@ -301,8 +298,9 @@ Without any optional arguments just the addresses and lengths of the contained s
 
 .. code-block:: shell
 
-    $ oj_hex_info srec sample.srec
+    $ oj-hex-info sample.srec
 
+    Sections
     --------
 
     Num   Address    Length
@@ -316,7 +314,7 @@ If you also want to see the contents, add *-d* option:
 
 .. code-block:: shell
 
-    $ oj_hex_info srec sample.srec -d
+    $ oj-hex-info sample.srec -d
 
     Sections
     --------
@@ -342,6 +340,78 @@ If you also want to see the contents, add *-d* option:
            16 bytes
     ---------------
 
+oj_hex_merge
+------------
+
+.. code-block:: shell
+
+    usage: oj-hex-merge [-h] -o OUTPUT [-t OUTPUT_TYPE] [-p] [-v]
+                        input_files [input_files ...]
+
+    Merges multiple HEX files into one.
+
+    positional arguments:
+      input_files           Input HEX files to be merged.
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -o OUTPUT, --output OUTPUT
+                            Output HEX file.
+      -t OUTPUT_TYPE, --type OUTPUT_TYPE
+                            Output file type (e.g., ihex, srec). If omitted, it's
+                            inferred from the output file extension.
+      -p, --print-filename  Print filenames while processing
+      -v, --verbose         Verbose output
+
+Example:
+
+.. code-block:: shell
+
+    $ oj-hex-merge file1.hex file2.hex -o merged.hex
+
+Note: Merging files with overlapping sections is not allowed and will result in an error.
+
+oj_hex_split
+------------
+
+.. code-block:: shell
+
+    usage: oj-hex-split [-h] [-o OUTPUT_NAMES [OUTPUT_NAMES ...]]
+                        [-t OUTPUT_TYPE] [-p PREFIX] [-v]
+                        input_file
+
+    Splits a HEX file into multiple files based on its sections.
+
+    positional arguments:
+      input_file            Input HEX file to be split.
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -o OUTPUT_NAMES [OUTPUT_NAMES ...], --output-names OUTPUT_NAMES [OUTPUT_NAMES ...]
+                            Optional list of output base names. If not provided,
+                            section numbers are used.
+      -t OUTPUT_TYPE, --type OUTPUT_TYPE
+                            Output file type (e.g., ihex, srec). If omitted, it's
+                            inferred from the input file extension.
+      -p PREFIX, --prefix PREFIX
+                            Prefix for output filenames. Defaults to input
+                            filename (without extension).
+      -v, --verbose         Verbose output
+
+Example:
+
+.. code-block:: shell
+
+    $ oj-hex-split merged.hex
+
+This will generate files like ``merged_000.hex``, ``merged_001.hex``, etc.
+
+You can also specify custom names:
+
+.. code-block:: shell
+
+    $ oj-hex-split merged.hex -o code data
+
 oj_coff_info
 ------------
 

{objutils-0.10.11 → objutils-0.10.13}/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.11"
+__version__ = "0.10.13"
 
 __all__ = [
     "Image",

{objutils-0.10.11 → objutils-0.10.13}/objutils/image.py

@@ -165,6 +165,10 @@ Usage Examples
     if 0x1050 in img:
         data = img.read(0x1050, 16)
 
+    # Check if address range is fully contained
+    if img.contains_range(0x1000, 0x100):
+        data = img.read(0x1000, 0x100)
+
     # Iterate over sections
     for section in img:
         print(f"Section at 0x{section.start_address:08X}, "
@@ -468,8 +472,61 @@ class Image:
         return not (self == other)
 
     def __contains__(self, addr: int) -> bool:
-        """Check if address is contained in any section."""
-        return any(addr in sec for sec in self.sections)
+        """Check if address is contained in any section of the image.
+
+        Args:
+            addr: Address to check.
+
+        Returns:
+            True if the address is within any section, False otherwise.
+        """
+        return any(addr in section for section in self.sections)
+
+    def contains_range(self, addr: int, size: int) -> bool:
+        """Check if address range is fully contained in the image.
+
+        Args:
+            addr: Start address of the range.
+            size: Size of the range.
+
+        Returns:
+            True if the entire range [addr, addr + size) is covered by sections.
+        """
+        if size < 0:
+            return False
+        if size == 0:
+            return addr in self
+
+        # Check if the range is covered by sections.
+        # Since sections are sorted and non-overlapping, we can check continuity.
+        remaining_size = size
+        current_addr = addr
+
+        # Find the first section that could contain current_addr
+        import bisect
+        from operator import attrgetter
+        idx = bisect.bisect_right(self.sections, current_addr, key=attrgetter("start_address")) - 1
+        if idx < 0:
+            idx = 0
+
+        while idx < len(self.sections) and remaining_size > 0:
+            section = self.sections[idx]
+            if current_addr < section.start_address:
+                # Gap before this section
+                return False
+
+            if current_addr < section.start_address + len(section):
+                # current_addr is in this section
+                covered = min(remaining_size, (section.start_address + len(section)) - current_addr)
+                remaining_size -= covered
+                current_addr += covered
+            else:
+                # current_addr is beyond this section
+                pass
+
+            idx += 1
+
+        return remaining_size == 0
 
     def hexdump(self, fp=sys.stdout) -> None:
         """Print hexadecimal dump of all sections.
@@ -818,16 +875,21 @@ class Image:
         self._call_address_function("write_string", addr, value, encoding, **kws)
 
     def _address_contained(self, address: int, length: int) -> bool:
-        """Check if address range is contained in the image.
+        """Check if address range has ANY overlap with the image.
 
         Args:
             address: Start address to check.
             length: Length of the address range.
 
         Returns:
-            True if the address range is contained in any section, False otherwise.
+            True if the address range overlaps with any section, False otherwise.
         """
-        return address in self or (address + length - 1) in self
+        if length <= 0:
+            return False
+        end = address + length
+        # A range [address, end) overlaps with [s.start, s.end) if:
+        # address < s.end AND s.start < end
+        return any(address < (s.start_address + len(s)) and s.start_address < end for s in self.sections)
 
     def insert_section(
         self, data: Union[bytes, bytearray, memoryview, str], start_address: Optional[int] = None, join: bool = True
@@ -901,6 +963,8 @@ class Image:
             This method currently only validates the address range but does not
             perform the actual update operation. Full implementation is pending.
         """
+        if address is None:
+            address = self.address
         if not self._address_contained(address, len(data)):
             raise InvalidAddressError("Address-space not in range")
 
@@ -940,23 +1004,13 @@ class Image:
             if not (new_address + len(section) <= s.start_address or new_address >= s.start_address + len(s)):
                 raise InvalidAddressError(f"New address 0x{new_address:08x} causes overlap with section at 0x{s.start_address:08x}")
 
-    def split(self, at: Optional[int] = None, equal_parts: Optional[int] = None, remap: Optional[bool] = None) -> None:
-        """Split image into multiple parts.
-
-        Args:
-            at: Address at which to split the image.
-            equal_parts: Number of equal-sized parts to split into.
-            remap: If True, remap addresses after splitting.
-
-        Raises:
-            NotImplementedError: This method is not yet implemented.
+    def split(self) -> list["Image"]:
+        """Split image into multiple parts based on sections.
 
-        Note:
-            This method is currently a placeholder and needs to be fully
-            implemented for production use. The parameters define different
-            splitting strategies that need to be developed.
+        Returns:
+            List of Image objects, each containing exactly one section.
         """
-        raise NotImplementedError(f"split() is not yet implemented. Called with: at={at}, equal_parts={equal_parts}, remap={remap}")
+        return [Image([section], join=False) for section in self.sections]
 
 
 def _validate_sections(sections: Iterable[Section]) -> None:

{objutils-0.10.11 → objutils-0.10.13}/objutils/scripts/oj_hex_info.py

@@ -4,7 +4,7 @@
 __copyright__ = """
    objutils - Object file library for Python.
 
-  (C) 2010-2020 by Christoph Schueler <cpu12.gems@googlemail.com>
+  (C) 2010-2026 by Christoph Schueler <cpu12.gems@googlemail.com>
 
   All Rights Reserved
 

objutils-0.10.13/objutils/scripts/oj_hex_merge.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+"""Merges multiple HEX files into one."""
+
+__copyright__ = """
+   objutils - Object file library for Python.
+
+  (C) 2010-2026 by Christoph Schueler <cpu12.gems@googlemail.com>
+
+  All Rights Reserved
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License along
+  with this program; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+"""
+
+import argparse
+import sys
+from os import path
+
+from objutils import load, probe, dump, Image
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Merges multiple HEX files into one.")
+    parser.add_argument(
+        "input_files",
+        nargs="+",
+        help="Input HEX files to be merged.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        required=True,
+        help="Output HEX file.",
+    )
+    parser.add_argument(
+        "-t",
+        "--type",
+        dest="output_type",
+        help="Output file type (e.g., ihex, srec). If omitted, it's inferred from the output file extension.",
+    )
+    parser.add_argument(
+        "-p",
+        "--print-filename",
+        dest="print_filename",
+        action="store_true",
+        default=False,
+        help="Print filenames while processing",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        dest="verbose",
+        action="store_true",
+        default=False,
+        help="Verbose output",
+    )
+
+    args = parser.parse_args()
+
+    output_type = args.output_type
+    if not output_type:
+        ext = path.splitext(args.output)[1].lower()
+        if ext in (".hex", ".ihex"):
+            output_type = "ihex"
+        elif ext in (".s19", ".srec", ".mot"):
+            output_type = "srec"
+        elif ext in (".bin",):
+            output_type = "bin"
+        else:
+            print(f"Could not infer output type from extension '{ext}'. Please specify with -t.")
+            sys.exit(1)
+
+    all_sections = []
+
+    for filename in args.input_files:
+        if not path.exists(filename):
+            print(f"File '{filename}' does not exist.")
+            sys.exit(1)
+
+        if args.print_filename:
+            print(f"Processing '{filename}'...")
+
+        with open(filename, "rb") as f:
+            file_type = probe(f)
+
+        if file_type is None:
+            print(f"Could not determine file type for '{filename}'.")
+            sys.exit(1)
+
+        img = load(file_type, filename)
+        for section in img:
+            # Check for overlaps manually to satisfy "No overlaps allowed during merge"
+            for existing in all_sections:
+                if not (
+                    section.start_address + section.length <= existing.start_address
+                    or section.start_address >= existing.start_address + existing.length
+                ):
+                    overlap_start = max(section.start_address, existing.start_address)
+                    print(f"Error: Overlap detected at 0x{overlap_start:08x} between input files.")
+                    sys.exit(1)
+            all_sections.append(section)
+
+    merged_image = Image(all_sections, join=True)
+
+    if args.verbose:
+        print("\nMerged Image Sections:")
+        print("Num   Address    Length")
+        print("-" * 79)
+        for idx, sec in enumerate(merged_image):
+            print(f"{idx:03d}   0x{sec.start_address:08x} {sec.length}")
+        print("-" * 79)
+        print(f"                 {len(merged_image)} total bytes")
+
+    dump(output_type, args.output, merged_image)
+    print(f"Successfully merged into '{args.output}' (type: {output_type}).")
+
+
+if __name__ == "__main__":
+    main()

objutils-0.10.13/objutils/scripts/oj_hex_split.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python
+"""Splits a HEX file into multiple files based on its sections."""
+
+__copyright__ = """
+   objutils - Object file library for Python.
+
+  (C) 2010-2026 by Christoph Schueler <cpu12.gems@googlemail.com>
+
+  All Rights Reserved
+
+  This program is free software; you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation; either version 2 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License along
+  with this program; if not, write to the Free Software Foundation, Inc.,
+  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+"""
+
+import argparse
+import sys
+from os import path
+from pathlib import Path
+
+from objutils import load, probe, dump
+from ufilename import build_filename, SuffixPolicy, IdentityPolicy
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Splits a HEX file into multiple files based on its sections.")
+    parser.add_argument(
+        "input_file",
+        help="Input HEX file to be split.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output-names",
+        nargs="+",
+        help="Optional list of output base names. If not provided, section numbers are used.",
+    )
+    parser.add_argument(
+        "-t",
+        "--type",
+        dest="output_type",
+        help="Output file type (e.g., ihex, srec). If omitted, it's inferred from the input file extension.",
+    )
+    parser.add_argument(
+        "-p",
+        "--prefix",
+        help="Prefix for output filenames. Defaults to input filename (without extension).",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        dest="verbose",
+        action="store_true",
+        default=False,
+        help="Verbose output",
+    )
+
+    args = parser.parse_args()
+
+    if not path.exists(args.input_file):
+        print(f"File '{args.input_file}' does not exist.")
+        sys.exit(1)
+
+    with open(args.input_file, "rb") as f:
+        file_type = probe(f)
+
+    if file_type is None:
+        print(f"Could not determine file type for '{args.input_file}'.")
+        sys.exit(1)
+
+    img = load(file_type, args.input_file)
+
+    if not img.sections:
+        print(f"No sections found in '{args.input_file}'.")
+        sys.exit(0)
+
+    output_type = args.output_type
+    input_path = Path(args.input_file)
+    if not output_type:
+        ext = input_path.suffix.lower()
+        if ext in (".hex", ".ihex"):
+            output_type = "ihex"
+        elif ext in (".s19", ".srec", ".mot"):
+            output_type = "srec"
+        elif ext in (".bin",):
+            output_type = "bin"
+        else:
+            output_type = "ihex"  # Fallback
+
+    base_prefix = args.prefix if args.prefix else input_path.stem
+    output_ext = input_path.suffix if not args.output_type else f".{args.output_type}"
+    # Normalize extension mapping for ufilename
+    if args.output_type:
+        if args.output_type == "ihex":
+            output_ext = ".hex"
+        elif args.output_type == "srec":
+            output_ext = ".s19"
+        elif args.output_type == "bin":
+            output_ext = ".bin"
+
+    if args.verbose:
+        print(f"Splitting '{args.input_file}' into {len(img.sections)} sections...")
+
+    split_images = img.split()
+
+    for idx, new_img in enumerate(split_images):
+        section = new_img.sections[0]
+        if args.output_names and idx < len(args.output_names):
+            # User provided a list of names
+            name_policy = IdentityPolicy()
+            out_base = args.output_names[idx]
+        else:
+            # Default: append section number
+            name_policy = SuffixPolicy(suffix=f"_{idx:03d}")
+            out_base = base_prefix
+
+        out_filename = build_filename(name_policy, out_base, output_ext)
+
+        print(f"Writing '{out_filename}'...")
+        if args.verbose:
+            print(f"  Section {idx:03d} (0x{section.start_address:08x}, {len(section)} bytes)")
+
+        dump(output_type, out_filename, new_img)
+
+    print(f"Successfully split into {len(split_images)} files.")
+
+
+if __name__ == "__main__":
+    main()