export normalize_isa and deprecate KNOWN_ARCHITECTURES

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

@@ -779,10 +779,20 @@ def _possible_base(self) -> Generator[str, None, None]:
     "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)
 

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: