firestarter 3.2.1__tar.gz → 3.2.2__tar.gz

{firestarter-3.2.1/firestarter.egg-info → firestarter-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firestarter
-Version: 3.2.1
+Version: 3.2.2
 Summary: EPROM programmer software for the Relatively Universal ROM Programmer
 Author-email: Henrik Olsson <henols@gmail.com>
 Project-URL: Homepage, https://github.com/henols/firestarter_app

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '3.2.1'
-__version_tuple__ = version_tuple = (3, 2, 1)
+__version__ = version = '3.2.2'
+__version_tuple__ = version_tuple = (3, 2, 2)
 
-__commit_id__ = commit_id = 'g4526a89'
+__commit_id__ = commit_id = 'ga7d562c'

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter/chip_resolver.py

@@ -10,11 +10,50 @@ Single chokepoint between CLI dispatch and the EPROM database lookup/conversion.
 from typing import Any
 
 from firestarter.database import EpromDatabase
-from firestarter.exceptions import ChipNotFoundError, ChipNotImplementedError
+from firestarter.exceptions import (
+    AmbiguousChipNameError,
+    ChipNotFoundError,
+    ChipNotImplementedError,
+)
 
 _NON_ZERO_WIRE_FIELDS = ("memory-size", "pin-count", "vpp_mv")
 
 
+def _qualified_choices(name: str, db: EpromDatabase) -> list[str]:
+    """The row `name` selects first, then each other row it selects that
+    programs differently, all as qualified names. Empty when one row, or rows
+    that program the same, are selected."""
+    alternatives = db.ambiguous_alternatives(name)
+    if not alternatives:
+        return []
+    raw_config, manufacturer = db.get_eprom_config(name)
+    return [db.qualified_chip_name(name, raw_config, manufacturer), *alternatives]
+
+
+def refuse_if_ambiguous(name: str, db: EpromDatabase) -> None:
+    """Refuse a name that selects chips that program differently: guessing
+    one would drive the wrong VPP, algorithm or timing."""
+    choices = _qualified_choices(name, db)
+    if choices:
+        listed = ", ".join(f"'{c}'" for c in choices)
+        raise AmbiguousChipNameError(
+            f"'{name}' names chips that program differently. Name one: {listed}."
+        )
+
+
+def describe_ambiguity(name: str, db: EpromDatabase) -> str | None:
+    """For display commands, which use the first row: the other rows `name`
+    selects, or None."""
+    choices = _qualified_choices(name, db)
+    if not choices:
+        return None
+    others = ", ".join(f"'{c}'" for c in choices[1:])
+    return (
+        f"'{name}' also names chips that program differently: {others}. "
+        f"This shows '{choices[0]}'."
+    )
+
+
 def resolve_chip(name: str, db: EpromDatabase | None = None) -> dict[str, Any]:
     """Resolve a chip name to its programmer-config dict.
 
@@ -26,6 +65,9 @@ def resolve_chip(name: str, db: EpromDatabase | None = None) -> dict[str, Any]:
     conversion (``convert_to_programmer`` returns ``{}``) are treated as the
     not-found condition.
 
+    Raises ``AmbiguousChipNameError`` (a ``ChipNotFoundError``) when the name
+    selects rows that program differently; the message names each of them.
+
     Raises ``ChipNotImplementedError`` when the chip exists in the database but
     its ``support_status`` is not ``"supported"`` (covers protocol-not-implemented,
     adapter-required, and vpp-exceeds-max).  This guard fires BEFORE any wire dict
@@ -49,6 +91,7 @@ def resolve_chip(name: str, db: EpromDatabase | None = None) -> dict[str, Any]:
     # have a support_status, so raise ChipNotFoundError immediately.
     if raw_config is None:
         raise ChipNotFoundError(name)
+    refuse_if_ambiguous(name, db)
 
     # Support-status guard: refuse every program-capable operation
     # for non-supported chips BEFORE convert_to_programmer builds any wire dict.

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter/cli_handlers.py

@@ -38,7 +38,11 @@ from firestarter.channel import (
     dev_command_gate_message,
     is_dev_tools_enabled,
 )
-from firestarter.chip_resolver import resolve_chip
+from firestarter.chip_resolver import (
+    describe_ambiguity,
+    refuse_if_ambiguous,
+    resolve_chip,
+)
 from firestarter.chip_test import (
     OP_ID,
     SDP_HOLD_NOT_RUN,
@@ -160,10 +164,17 @@ def _complete_eprom(
     semantics at main.py:39-45.
     """  # noqa: E501
     db = EpromDatabase()
-    return [
-        click.shell_completion.CompletionItem(e["name"])
+    qualified = db.names_needing_qualifier()
+    # A row whose name also names chips that program differently is offered
+    # by the qualified name that selects it.
+    names = (
+        qualified.get((e["manufacturer"], e["name"]), e["name"])
         for e in db.get_eproms()
-        if e["name"].lower().startswith(incomplete.lower())
+    )
+    return [
+        click.shell_completion.CompletionItem(name)
+        for name in names
+        if name.lower().startswith(incomplete.lower())
     ]
 
 
@@ -486,7 +497,11 @@ def _list_cmd(app: AppContext) -> None:
     """List all EPROMs in the database."""
     eprom_data_list = app.db.get_eproms()
     if eprom_data_list:
-        print_eprom_list_table(eprom_data_list, app.eprom_presenter.spec_builder)
+        print_eprom_list_table(
+            eprom_data_list,
+            app.eprom_presenter.spec_builder,
+            app.db.names_needing_qualifier(),
+        )
         sys.exit(0)
     sys.exit(1)
 
@@ -504,6 +519,9 @@ def info(app: AppContext, eprom: str, config: bool, adapter: bool) -> None:
         logger.error(f"EPROM '{eprom}' not found in database.")
         sys.exit(1)
 
+    ambiguity = describe_ambiguity(eprom, app.db)
+    if ambiguity:
+        logger.warning(ambiguity)
     eprom_data_for_programmer = app.db.convert_to_programmer(eprom_details)
     raw_config_data, manufacturer = app.db.get_eprom_config(eprom)
 
@@ -534,7 +552,11 @@ def search(app: AppContext, text: str) -> None:
     """Search for EPROMs in the database."""
     search_results = app.db.search_eprom(text)
     if search_results:
-        print_eprom_list_table(search_results, app.eprom_presenter.spec_builder)
+        print_eprom_list_table(
+            search_results,
+            app.eprom_presenter.spec_builder,
+            app.db.names_needing_qualifier(),
+        )
         sys.exit(0)
     sys.exit(1)
 
@@ -1505,7 +1527,9 @@ def chip_id(app: AppContext, eprom: str, force: bool) -> None:
                 for ic in found_eproms_for_detected_id
             ]
             print_eprom_list_table(
-                mapped_found_eproms, app.eprom_presenter.spec_builder
+                mapped_found_eproms,
+                app.eprom_presenter.spec_builder,
+                app.db.names_needing_qualifier(),
             )
         else:
             logger.warning(
@@ -3058,6 +3082,8 @@ def _canonical_part_number(part_number: str | None, raw_token: str) -> str | Non
     def _strip_paren(s: str) -> str:
         return re.sub(r"\([^)]*\)", "", s).strip().lower()
 
+    # A manufacturer qualifier (PART@MANUFACTURER) is not part of the name.
+    raw_token = raw_token.partition("@")[0].strip()
     query = raw_token.lower()
     if query == part_number.lower():
         return part_number
@@ -3166,6 +3192,10 @@ def dev_test(app: "AppContext", chip: str, fast: bool, submit: bool) -> None:
     # still runs the full community-validation sweep below.
     if not app.db.get_eprom(chip):
         raise ChipNotFoundError(f"{chip}: not found in database")
+    # A name that selects chips that program differently is refused here,
+    # not step by step: every step would be SKIPPED and the report would
+    # name no chip.
+    refuse_if_ambiguous(chip, app.db)
 
     # The chip must be known to be in the DB (see above) before its
     # electrical type can be read, so the UV-scope resolution happens here,

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter/database.py

@@ -14,6 +14,7 @@ return the same instance.
 import json
 import logging
 import os
+import re
 from pathlib import Path
 from typing import Any
 
@@ -145,6 +146,11 @@ def _read_config_file(filename: str) -> dict:
         return {}
 
 
+def _strip_mode(name: str) -> str:
+    """'DS1245AB(RW)' -> 'ds1245ab': the name without its mode annotation."""
+    return re.sub(r"\([^)]*\)", "", name).strip().lower()
+
+
 class EpromDatabase:
     """
     Manages the EPROM and pin map database for the Firestarter application.
@@ -157,6 +163,7 @@ class EpromDatabase:
     def __init__(self, skip_local_override: bool = False):
         self.proms: dict[str, Any] = {}
         self.pin_maps: dict[str, Any] = {}
+        self._names_needing_qualifier: dict[tuple[str, str], str] | None = None
         self._initialize_database_core(skip_local_override=skip_local_override)
         logger.debug("EpromDatabase initialized.")
 
@@ -426,46 +433,146 @@ class EpromDatabase:
             for ic_config in ics
         ]
 
+    def find_chip_configs(self, chip_name: str) -> list[tuple[dict, str]]:
+        """Return every database row `chip_name` selects, as
+        (config_dict, manufacturer) pairs in database order.
+
+        A name matches a row's `part_number` directly, or one of its
+        comma-separated aliases. Upstream infoic.xml encodes chip aliases as
+        comma-separated lists (e.g. "AT28C256,AT28C256E,AT28HC256"), which
+        build_db.py preserves in the part_number field.
+
+        infoic.xml also annotates many names with a parenthetical mode, such
+        as "(RW)", "(TEST)" or "(RW3.3V)" (e.g. "DS1245AB(RW),DS1245Y(RW)"). A
+        name matches an annotated alias with the annotation stripped, but only
+        when no row matches the name as typed: "DS1220(TEST)" selects the
+        (TEST) row, never the (RW) row that "DS1220" also matches.
+
+        The same part number can name rows of different manufacturers, which
+        program differently. `PART@MANUFACTURER` selects one manufacturer's
+        rows; see `resolve_manufacturer` for how the manufacturer matches.
+        """
+        name, at, wanted = chip_name.partition("@")
+        manufacturer_wanted = self.resolve_manufacturer(wanted) if at else None
+        if at and manufacturer_wanted is None:
+            return []
+        query = name.strip().lower()
+        query_stripped = _strip_mode(name)
+        exact: list[tuple[dict, str]] = []
+        stripped: list[tuple[dict, str]] = []
+        for manufacturer, ics in self.proms.items():
+            if manufacturer_wanted is not None and manufacturer != manufacturer_wanted:
+                continue
+            for ic_config in ics:
+                part_number = ic_config.get("part_number", "")
+                aliases = part_number.split(",")
+                if query == part_number.lower() or query in (
+                    a.strip().lower() for a in aliases
+                ):
+                    exact.append((ic_config, manufacturer))
+                elif query_stripped and query_stripped in (
+                    _strip_mode(a) for a in aliases
+                ):
+                    stripped.append((ic_config, manufacturer))
+        return exact or stripped
+
     def get_eprom_config(self, chip_name: str):
         """
         Retrieves the raw configuration data for a specific EPROM by its name.
             Returns (config_dict, manufacturer_str) or (None, None).
 
-        Matches against `part_number` directly OR against any of the
-        comma-separated alias names within it. Upstream infoic.xml encodes
-        chip aliases as comma-separated lists (e.g.,
-        "AT28C256,AT28C256E,AT28HC256"), which build_db.py preserves in
-        the part_number field. Without alias-aware lookup, queries like
-        `firestarter info AT28C256` failed despite the chip being in the DB.
-
-        Also handles infoic.xml's parenthetical mode annotations: many
-        chip names carry "(RW)", "(TEST)", "(RW3.3V)" etc. (e.g.,
-        "DS1245AB(RW),DS1245Y(RW)"). A plain query like "DS1245AB"
-        is normalized to match against the paren-stripped alias.
+        The first row `find_chip_configs` selects; see there for how a name
+        matches.
         """
-        import re
-
-        def _strip_paren(s):
-            # "DS1245AB(RW)" -> "DS1245AB"; preserves the canonical chip name.
-            return re.sub(r"\([^)]*\)", "", s).strip().lower()
+        matches = self.find_chip_configs(chip_name)
+        return matches[0] if matches else (None, None)
+
+    def resolve_manufacturer(self, wanted: str) -> str | None:
+        """The manufacturer `wanted` names: an exact name, ignoring case, else
+        the one manufacturer it is a prefix of. None when it names none, or is
+        a prefix of more than one."""
+        wanted = wanted.strip().lower()
+        if not wanted:
+            return None
+        names = list(self.proms)
+        exact = [m for m in names if m.lower() == wanted]
+        if exact:
+            return exact[0]
+        prefixed = [m for m in names if m.lower().startswith(wanted)]
+        return prefixed[0] if len(prefixed) == 1 else None
+
+    def qualified_chip_name(
+        self, chip_name: str, ic_config: dict, manufacturer: str
+    ) -> str:
+        """The name that selects this one row: the row's alias that `chip_name`
+        matched, with its mode annotation, then `@` and the manufacturer.
+
+        The manufacturer is its first word when that word names it alone, so
+        the name needs no shell quoting ('27C128@MICROCHIP', not
+        '27C128@MICROCHIP memory').
+        """
+        name = chip_name.partition("@")[0].strip()
+        aliases = [a.strip() for a in ic_config.get("part_number", "").split(",")]
+        alias = next(
+            (a for a in aliases if a.lower() == name.lower()),
+            next(
+                (a for a in aliases if _strip_mode(a) == _strip_mode(name)),
+                aliases[0],
+            ),
+        )
+        first_word = manufacturer.split()[0] if manufacturer.split() else manufacturer
+        short = (
+            first_word
+            if self.resolve_manufacturer(first_word) == manufacturer
+            else manufacturer
+        )
+        return f"{alias}@{short}"
+
+    def names_needing_qualifier(self) -> dict[tuple[str, str], str]:
+        """Every row with an alias that, typed as shown, also selects rows that
+        program differently, keyed (manufacturer, part_number), with the
+        qualified name that selects it. Such a row can only be named with
+        `@MANUFACTURER`."""
+        if self._names_needing_qualifier is None:
+            by_name: dict[str, list[tuple[dict, str]]] = {}
+            for manufacturer, ics in self.proms.items():
+                for ic_config in ics:
+                    for alias in ic_config.get("part_number", "").split(","):
+                        by_name.setdefault(alias.strip().lower(), []).append(
+                            (ic_config, manufacturer)
+                        )
+            needing: dict[tuple[str, str], str] = {}
+            for name, rows in by_name.items():
+                if len(rows) < 2:
+                    continue
+                wires = [
+                    self.convert_to_programmer(self._map_data(ic, m)) for ic, m in rows
+                ]
+                if all(w == wires[0] for w in wires[1:]):
+                    continue
+                for ic, m in rows:
+                    needing.setdefault(
+                        (m, ic.get("part_number", "")),
+                        self.qualified_chip_name(name, ic, m),
+                    )
+            self._names_needing_qualifier = needing
+        return self._names_needing_qualifier
 
-        query = chip_name.lower()
-        query_stripped = _strip_paren(chip_name)
-        for manufacturer, ics in self.proms.items():
-            for ic_config in ics:
-                part_number = ic_config.get("part_number", "")
-                if query == part_number.lower():
-                    return ic_config, manufacturer
-                # Alias match: split on comma + match individual aliases.
-                # Try exact alias first, then paren-stripped alias.
-                if "," in part_number or "(" in part_number:
-                    aliases = [a.strip().lower() for a in part_number.split(",")]
-                    if query in aliases:
-                        return ic_config, manufacturer
-                    aliases_stripped = [_strip_paren(a) for a in part_number.split(",")]
-                    if query_stripped and query_stripped in aliases_stripped:
-                        return ic_config, manufacturer
-        return None, None
+    def ambiguous_alternatives(self, chip_name: str) -> list[str]:
+        """Name the other rows `chip_name` selects that program differently
+        from the one `get_eprom_config` uses, each as a qualified name that
+        selects that row alone. Empty when the choice cannot matter.
+        """
+        matches = self.find_chip_configs(chip_name)
+        if len(matches) < 2:
+            return []
+        chosen = self.convert_to_programmer(self._map_data(*matches[0]))
+        return [
+            self.qualified_chip_name(chip_name, ic_config, manufacturer)
+            for ic_config, manufacturer in matches[1:]
+            if self.convert_to_programmer(self._map_data(ic_config, manufacturer))
+            != chosen
+        ]
 
     def get_eprom(self, chip_name: str):
         """

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter/eprom_info.py

@@ -394,9 +394,17 @@ class EpromConsolePresenter:
 
 
 # --- Helper function for printing EPROM list (for testing/CLI) ---
-def print_eprom_list_table(eproms_data: list, spec_builder: EpromSpecBuilder):
+def print_eprom_list_table(
+    eproms_data: list,
+    spec_builder: EpromSpecBuilder,
+    qualified_names: dict[tuple[str, str], str] | None = None,
+):
     """Prints a list of EPROM data in a table format. For CLI/testing.
 
+    A row in `qualified_names` (keyed (manufacturer, name)) can only be named
+    with `@MANUFACTURER`; its Name cell ends in '*' and a line under the table
+    gives an example.
+
     Column layout:
     - Name: dynamic width clamped to [13, 20]; names longer than 20 chars are
       truncated with a trailing ellipsis ('…') that counts toward the 20-char cap.
@@ -413,19 +421,26 @@ def print_eprom_list_table(eproms_data: list, spec_builder: EpromSpecBuilder):
     # Compute the widest rendered name (including any [!] suffix) across all rows,
     # then clamp to the [13, 20] range.  Names that would exceed 20 chars are
     # truncated to 19 chars + '…' (ellipsis counts toward the 20-char cap).
-    def _render_name(raw_name: str, has_bus_config: bool) -> str:
+    qualified_names = qualified_names or {}
+
+    def _render_name(raw_name: str, has_bus_config: bool, marked: bool) -> str:
         """Return the name string as it will be rendered in the table cell."""
         name = raw_name
         if not has_bus_config:
             name = (name[:11] + "[!]") if len(name) > 11 else f"{name}[!]"
-        if len(name) > 20:
-            name = name[:19] + "…"  # ellipsis counts toward the 20-char cap
-        return name
+        cap = 19 if marked else 20
+        if len(name) > cap:
+            name = name[: cap - 1] + "…"  # ellipsis counts toward the cap
+        return name + "*" if marked else name
 
-    rendered_names = [
-        _render_name(ic.get("name", ""), bool(ic.get("bus-config")))
+    marked_rows = [
+        (ic.get("manufacturer", ""), ic.get("name", "")) in qualified_names
         for ic in eproms_data
     ]
+    rendered_names = [
+        _render_name(ic.get("name", ""), bool(ic.get("bus-config")), marked)
+        for ic, marked in zip(eproms_data, marked_rows)
+    ]
     name_w = max(13, min(20, max((len(n) for n in rendered_names), default=13)))
 
     divider = f"+{'':-<{name_w + 1}}+{'':-<18}+{'':-<6}+{'':-<12}+{'':-<13}+{'':-<6}+"
@@ -462,6 +477,19 @@ def print_eprom_list_table(eproms_data: list, spec_builder: EpromSpecBuilder):
             f"| {name: <{name_w}}| {ic.get('manufacturer', ''): <17}|{ic.get('pin-count', 0): >5} | {chip_id_str: <11}| {type_str_display: <12}| {vpp_str: <5}|"  # noqa: E501
         )
     logger.info(divider)
+    example = next(
+        (
+            qualified_names[(ic.get("manufacturer", ""), ic.get("name", ""))]
+            for ic, marked in zip(eproms_data, marked_rows)
+            if marked
+        ),
+        None,
+    )
+    if example:
+        logger.info(
+            "* This name also selects chips that program differently. "
+            f"Add @MANUFACTURER to choose one, e.g. {example}"
+        )
 
 
 # Standalone test function

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter/exceptions.py

@@ -195,3 +195,9 @@ class ChipNotFoundError(Exception):
     """
 
     pass
+
+
+class AmbiguousChipNameError(ChipNotFoundError):
+    """Raised when a chip name selects database rows that program differently
+    (VPP, algorithm, chip ID or pulse width), so no one chip is named. The
+    message lists a qualified name for each of them."""

{firestarter-3.2.1 → firestarter-3.2.2/firestarter.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firestarter
-Version: 3.2.1
+Version: 3.2.2
 Summary: EPROM programmer software for the Relatively Universal ROM Programmer
 Author-email: Henrik Olsson <henols@gmail.com>
 Project-URL: Homepage, https://github.com/henols/firestarter_app

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ tests/test_build_db_pinout_fork.py
 tests/test_canonical_part_number.py
 tests/test_characterization.py
 tests/test_chip_database_field_inventory.py
+tests/test_chip_name_resolution.py
 tests/test_chip_resolver.py
 tests/test_chip_test.py
 tests/test_chip_test_blank_check_order.py

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter.egg-info/scm_file_list.json

@@ -119,6 +119,7 @@
     "tests/test_canonical_part_number.py",
     "tests/test_characterization.py",
     "tests/test_chip_database_field_inventory.py",
+    "tests/test_chip_name_resolution.py",
     "tests/test_chip_resolver.py",
     "tests/test_chip_test.py",
     "tests/test_chip_test_blank_check_order.py",

{firestarter-3.2.1 → firestarter-3.2.2}/firestarter.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "3.2.1",
+  "tag": "3.2.2",
   "distance": 0,
-  "node": "g4526a89",
+  "node": "ga7d562c",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-10-25"