export normalize_isa and deprecate KNOWN_ARCHITECTURES (#62)

- Add `normalize_isa()` to the public API, which normalizes ISA strings
to canonical
form (e.g. `amd64` → `x86_64`, `aarch64` → `arm64`) and passes
unrecognized values
through lowercased — making it safe for any platform without requiring
an allowlist
- Deprecate `KNOWN_ARCHITECTURES` — the constant remains exported for
backwards
    compatibility but consumers should migrate to `normalize_isa()`
- Relax `test_py_info_machine_property` to assert the machine value is
lowercase
instead of requiring membership in `KNOWN_ARCHITECTURES`, fixing test
failures on
    platforms like `alpha` or `armv8l`
Fixes: #59

---------

Co-authored-by: Rahul Devikar <radevika@microsoft.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/changelog/59.bugfix.rst

@@ -0,0 +1 @@
+export normalize_isa and deprecate KNOWN_ARCHITECTURES - by :user:`rahuldevikar`.

docs/conf.py

@@ -21,13 +21,19 @@
     "sphinxcontrib.mermaid",
 ]
 
+extlinks = {
+    "issue": ("https://github.com/tox-dev/python-discovery/issues/%s", "#%s"),
+    "pull": ("https://github.com/tox-dev/python-discovery/pull/%s", "PR #%s"),
+    "user": ("https://github.com/%s", "@%s"),
+}
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
 
 templates_path = []
 source_suffix = ".rst"
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "changelog/*.rst"]
 
 main_doc = "index"
 pygments_style = "default"

src/python_discovery/__init__.py

@@ -6,7 +6,7 @@
 
 from ._cache import ContentStore, DiskCache, PyInfoCache
 from ._discovery import get_interpreter
-from ._py_info import KNOWN_ARCHITECTURES, PythonInfo
+from ._py_info import KNOWN_ARCHITECTURES, PythonInfo, normalize_isa
 from ._py_spec import PythonSpec
 from ._specifier import SimpleSpecifier, SimpleSpecifierSet, SimpleVersion
 
@@ -24,4 +24,5 @@
     "SimpleVersion",
     "__version__",
     "get_interpreter",
+    "normalize_isa",
 ]

src/python_discovery/_py_info.py

@@ -770,21 +770,43 @@ def _possible_base(self) -> Generator[str, None, None]:
 
 KNOWN_ARCHITECTURES: frozenset[str] = frozenset({
     "arm64",
-    "i686",
     "loongarch64",
+    "ppc",
     "ppc64",
     "ppc64le",
     "riscv64",
     "s390x",
+    "sparc64",
     "x86",
     "x86_64",
 })
-"""Known CPU architecture (ISA) values after normalization."""
+"""Known CPU architecture (ISA) values after normalization.
+
+.. deprecated::
+    Use :func:`normalize_isa` instead, which handles both known and unknown architectures.
+"""
 
 
 def normalize_isa(isa: str) -> str:
+    """
+    Normalize an ISA (instruction set architecture) string to a canonical form.
+
+    Known aliases are mapped (e.g. ``amd64`` → ``x86_64``, ``aarch64`` → ``arm64``).
+    Unrecognized values are lowercased and returned as-is.
+    """
     low = isa.lower()
-    return {"amd64": "x86_64", "aarch64": "arm64", "i386": "x86", "i586": "x86"}.get(low, low)
+    return {
+        "amd64": "x86_64",
+        "aarch64": "arm64",
+        "i386": "x86",
+        "i486": "x86",
+        "i586": "x86",
+        "i686": "x86",
+        "powerpc": "ppc",
+        "powerpc64": "ppc64",
+        "powerpc64le": "ppc64le",
+        "sparcv9": "sparc64",
+    }.get(low, low)
 
 
 def _main() -> None:  # pragma: no cover

tests/py_info/test_py_info.py

@@ -14,7 +14,7 @@
 import pytest
 from setuptools.dist import Distribution
 
-from python_discovery import KNOWN_ARCHITECTURES, DiskCache, PythonInfo, PythonSpec
+from python_discovery import DiskCache, PythonInfo, PythonSpec
 from python_discovery import _cached_py_info as cached_py_info
 from python_discovery._py_info import VersionInfo
 
@@ -338,7 +338,7 @@ def test_py_info_machine_property() -> None:
     assert machine is not None
     assert isinstance(machine, str)
     assert len(machine) > 0
-    assert machine in KNOWN_ARCHITECTURES, f"unexpected machine value: {machine}"
+    assert machine == machine.lower(), f"machine value should be lowercase: {machine}"
 
 
 def test_py_info_machine_in_spec() -> None:

tests/test_py_spec.py

@@ -217,9 +217,19 @@ def test_spec_satisfies_machine(left: str, right: str, expected: bool) -> None:
         pytest.param("x86_64", "x86_64", id="x86_64"),
         pytest.param("arm64", "arm64", id="arm64"),
         pytest.param("x86", "x86", id="x86"),
+        pytest.param("i386", "x86", id="i386"),
+        pytest.param("i486", "x86", id="i486"),
+        pytest.param("i586", "x86", id="i586"),
+        pytest.param("i686", "x86", id="i686"),
         pytest.param("ppc64le", "ppc64le", id="ppc64le"),
+        pytest.param("powerpc", "ppc", id="powerpc"),
+        pytest.param("powerpc64", "ppc64", id="powerpc64"),
+        pytest.param("powerpc64le", "ppc64le", id="powerpc64le"),
         pytest.param("riscv64", "riscv64", id="riscv64"),
         pytest.param("s390x", "s390x", id="s390x"),
+        pytest.param("sparcv9", "sparc64", id="sparcv9"),
+        pytest.param("sparc64", "sparc64", id="sparc64"),
+        pytest.param("alpha", "alpha", id="alpha-passthrough"),
     ],
 )
 def test_normalize_isa(isa: str, normalized: str) -> None: