#!/usr/bin/env python
"""Package entry-point.
Registers CODECS and implements an interface to them.
- :func:`load`
- :func:`loads`
- :func:`probe`
- :func:`probes`
- :func:`dump`
- :func:`dumps`
The first parameter is always the codec name.
"""
__version__ = "0.8.1"
__all__ = [
"Image",
"Section",
"registry",
"load",
"loads",
"dump",
"dumps",
"probe",
"probes",
]
__copyright__ = """
objutils - Object file library for Python.
(C) 2010-2024 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 os
import sys
from rich import pretty
from rich.console import Console
from rich.traceback import install as tb_install
import objutils.ash
import objutils.binfile
import objutils.cosmac
import objutils.emon52
import objutils.etek
import objutils.fpc
import objutils.ihex
import objutils.mostec
import objutils.rca
import objutils.shf
import objutils.sig
import objutils.srec
import objutils.tek
import objutils.titxt
from objutils.image import Image # noqa: F401
from objutils.registry import registry
from objutils.section import Section # noqa: F401
# Optional developer-friendly console and tracebacks; disabled by default for library consumers.
_ENABLE_RICH = os.getenv("OBJUTILS_RICH", "0").lower() in {"1", "true", "yes"}
if _ENABLE_RICH and sys.stderr.isatty():
pretty.install()
tb_install(show_locals=True, max_frames=3)
console = Console()
else:
console = None # type: ignore[assignment]
registry.register("bin", objutils.binfile.Reader, objutils.binfile.Writer, "Plain binary format.")
registry.register(
"binzip",
objutils.binfile.BinZipReader,
objutils.binfile.BinZipWriter,
"Zipped binary format.",
)
registry.register("sig", objutils.sig.Reader, objutils.sig.Writer, "Signetics format.")
registry.register(
"srec",
objutils.srec.Reader,
objutils.srec.Writer,
"Motorola S-Records (a.k.a. S19).",
)
registry.register(
"titxt",
objutils.titxt.Reader,
objutils.titxt.Writer,
"Texas Instruments MSP430 text format.",
)
registry.register(
"emon52",
objutils.emon52.Reader,
objutils.emon52.Writer,
"Elektor Monitor (EMON52) file format.",
)
registry.register("etek", objutils.etek.Reader, objutils.etek.Writer, "Extended Tektonix format.")
registry.register("fpc", objutils.fpc.Reader, objutils.fpc.Writer, "Four packed code file format.")
registry.register("ihex", objutils.ihex.Reader, objutils.ihex.Writer, "Intel IHex format.")
registry.register("mostec", objutils.mostec.Reader, objutils.mostec.Writer, "MOSTech format.")
registry.register("rca", objutils.rca.Reader, objutils.rca.Writer, "RCA format.")
registry.register("tek", objutils.tek.Reader, objutils.tek.Writer, "Tektonix format.")
registry.register("cosmac", objutils.cosmac.Reader, objutils.cosmac.Writer, "RCA COSMAC format.")
registry.register("ash", objutils.ash.Reader, objutils.ash.Writer, "ASCII hex space formats.")
registry.register("shf", objutils.shf.Reader, objutils.shf.Writer, "S Hexdump Format (rfc4149).")
from typing import Any, Optional
[docs]
def load(codec_name: str, *args: Any, **kws: Any) -> Image:
"""Load hex data from file.
Parameters
----------
codec_name: str
Name of a registered codec.
Returns
-------
class:`Image`
"""
return registry.get(codec_name).Reader().load(*args, **kws)
[docs]
def loads(codec_name: str, *args: Any, **kws: Any) -> Image:
"""Load hex data from bytes.
Parameters
----------
codec_name: str
Name of a registered codec.
Returns
-------
class:`Image`
"""
return registry.get(codec_name).Reader().loads(*args, **kws)
[docs]
def probe(*args: Any, **kws: Any) -> Optional[str]:
"""Try to guess codec from file.
Returns
-------
str | None
The detected codec name or None if undetected.
"""
for name, codec in registry:
reader = codec.Reader()
if reader.probe(*args, **kws):
return name
return None
[docs]
def probes(*args: Any, **kws: Any) -> Optional[str]:
"""Try to guess codec from bytes.
Returns
-------
str | None
The detected codec name or None if undetected.
"""
for name, codec in registry:
reader = codec.Reader()
if reader.probes(*args, **kws):
return name
return None
[docs]
def dump(codec_name: str, *args: Any, **kws: Any) -> None:
"""Save hex data to file.
Parameters
----------
codec_name: str
Name of a registered codec.
Returns
-------
bytes
"""
registry.get(codec_name).Writer().dump(*args, **kws)
[docs]
def dumps(codec_name: str, *args: Any, **kws: Any) -> bytes:
"""Save hex data to bytes.
Parameters
----------
codec_name: str
Name of a registered codec.
Returns
-------
bytes
"""
return registry.get(codec_name).Writer().dumps(*args, **kws)