cann-cann 0.1.0__tar.gz

cann_cann-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 liggest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cann_cann-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: cann-cann
+Version: 0.1.0
+Summary: 看看环境上的 NPU 参数
+Author: liggest
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/liggest/cann-cann
+Project-URL: Repository, https://github.com/liggest/cann-cann
+Project-URL: Issues, https://github.com/liggest/cann-cann/issues
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# cann-cann
+
+一行代码快速检查环境上的 NPU 与 CANN 参数
+
+> 看看你的 UB 有多大😎
+</div>
+
+## 安装
+
+```bash
+pip install cann-cann
+```
+
+> 支持 Python >= 3.10；需要安装 CANN 并加载环境变量
+
+## Python 接口
+
+```python
+import cann_cann
+
+cann_cann.ub_size()  # 253952
+cann_cann.ub_size(unit="kb")  # 248
+cann_cann.memory_size(unit="gb")  # 128
+
+cann_cann.npu_name()  # "Ascend950PR_XXXX"
+cann_cann.all_npu_names()  # ["Ascend910A",...]
+
+cann_cann.memory_size(npu_name="Ascend910_9392", unit="gb")  # 64
+```
+
+也可先获取单独的配置对象，方便连续读取同一份配置中的多个参数：
+
+```python
+config = cann_cann.platform_config(npu_name="Ascend910B2")
+
+config.ub_size(unit="kb")  # 192
+config.l1_size(unit="kb")  # 512
+config.memory_size(unit="gb")  # 64
+
+# 读取配置文件中的原始值
+config.ai_core_spec.ub_size  # 196608
+config.soc_info.ai_core_count  # 24
+config.soc_info.memory_size  # 68719476736
+```
+
+## 命令行
+
+提供 `cann-cann` 与作为简称的 `ccann` 命令，使用任一命令均可
+
+```bash
+cann-cann UB  # 253952
+cann-cann UB --kb  # 248
+ccann L0A --unit kb  # 64
+ccann L1 --kb --npu-name Ascend910_9392  # 512
+ccann ai-cores  # 24
+ccann memory --gb  # 128
+
+cann-cann npu-name  # Ascend950PR_XXXX
+ccann all-npu-names  # Ascend910A...
+```
+
+> 查询名称不区分大小写
+>
+> 当前支持 `UB`、`L0A`、`L0B`、`L0C`、`L1`、`L2`、`memory` 和 `ai-cores`
+
+<!-- ## 单位
+
+平台配置中的存储空间大小以字节记录，Section 的类型化属性会原样返回这些值
+便利函数和方法默认使用 `unit="bytes"`
+
+为符合常见加速器工具的使用习惯，本项目中的 `kb` 和 `kib` 都表示 1024 字节，
+`mb` 和 `mib` 都表示 1024² 字节。CLI 可使用 `--kb`、`--kib`、`--mb` 和
+`--mib` 快速选择单位
+
+## 异常处理
+
+找不到 CANN、无法探测 NPU 名称或无法读取平台配置时，Python API 会抛出
+`CannCannError` 的子类。一般情况下只需捕获这个基类；需要采取不同恢复措施时，
+可以进一步捕获 `NPUDetectionError` 或 `PlatformConfigNotFoundError`。不支持的单位
+等参数错误使用标准 `ValueError`
+
+CLI 会简洁地显示可预期的错误，并以非零状态码退出。如果无法自动探测 NPU，
+可显式指定名称：
+
+```bash
+cann-cann UB --npu-name Ascend910_9392
+``` -->
+
+## 参与开发
+
+参与开发时，先安装开发依赖并启用提交前检查：
+
+```bash
+uv sync --dev
+uv run pre-commit install
+```
+
+启用后，每次提交前都会使用 Ruff 自动检查并格式化 Python 代码。也可手动检查所有文件：
+
+```bash
+uv run pre-commit run --all-files
+```
+
+完整检查、测试与构建：
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run pytest
+uv build
+```

cann_cann-0.1.0/README.md

@@ -0,0 +1,113 @@
+<div align="center">
+
+# cann-cann
+
+一行代码快速检查环境上的 NPU 与 CANN 参数
+
+> 看看你的 UB 有多大😎
+</div>
+
+## 安装
+
+```bash
+pip install cann-cann
+```
+
+> 支持 Python >= 3.10；需要安装 CANN 并加载环境变量
+
+## Python 接口
+
+```python
+import cann_cann
+
+cann_cann.ub_size()  # 253952
+cann_cann.ub_size(unit="kb")  # 248
+cann_cann.memory_size(unit="gb")  # 128
+
+cann_cann.npu_name()  # "Ascend950PR_XXXX"
+cann_cann.all_npu_names()  # ["Ascend910A",...]
+
+cann_cann.memory_size(npu_name="Ascend910_9392", unit="gb")  # 64
+```
+
+也可先获取单独的配置对象，方便连续读取同一份配置中的多个参数：
+
+```python
+config = cann_cann.platform_config(npu_name="Ascend910B2")
+
+config.ub_size(unit="kb")  # 192
+config.l1_size(unit="kb")  # 512
+config.memory_size(unit="gb")  # 64
+
+# 读取配置文件中的原始值
+config.ai_core_spec.ub_size  # 196608
+config.soc_info.ai_core_count  # 24
+config.soc_info.memory_size  # 68719476736
+```
+
+## 命令行
+
+提供 `cann-cann` 与作为简称的 `ccann` 命令，使用任一命令均可
+
+```bash
+cann-cann UB  # 253952
+cann-cann UB --kb  # 248
+ccann L0A --unit kb  # 64
+ccann L1 --kb --npu-name Ascend910_9392  # 512
+ccann ai-cores  # 24
+ccann memory --gb  # 128
+
+cann-cann npu-name  # Ascend950PR_XXXX
+ccann all-npu-names  # Ascend910A...
+```
+
+> 查询名称不区分大小写
+>
+> 当前支持 `UB`、`L0A`、`L0B`、`L0C`、`L1`、`L2`、`memory` 和 `ai-cores`
+
+<!-- ## 单位
+
+平台配置中的存储空间大小以字节记录，Section 的类型化属性会原样返回这些值
+便利函数和方法默认使用 `unit="bytes"`
+
+为符合常见加速器工具的使用习惯，本项目中的 `kb` 和 `kib` 都表示 1024 字节，
+`mb` 和 `mib` 都表示 1024² 字节。CLI 可使用 `--kb`、`--kib`、`--mb` 和
+`--mib` 快速选择单位
+
+## 异常处理
+
+找不到 CANN、无法探测 NPU 名称或无法读取平台配置时，Python API 会抛出
+`CannCannError` 的子类。一般情况下只需捕获这个基类；需要采取不同恢复措施时，
+可以进一步捕获 `NPUDetectionError` 或 `PlatformConfigNotFoundError`。不支持的单位
+等参数错误使用标准 `ValueError`
+
+CLI 会简洁地显示可预期的错误，并以非零状态码退出。如果无法自动探测 NPU，
+可显式指定名称：
+
+```bash
+cann-cann UB --npu-name Ascend910_9392
+``` -->
+
+## 参与开发
+
+参与开发时，先安装开发依赖并启用提交前检查：
+
+```bash
+uv sync --dev
+uv run pre-commit install
+```
+
+启用后，每次提交前都会使用 Ruff 自动检查并格式化 Python 代码。也可手动检查所有文件：
+
+```bash
+uv run pre-commit run --all-files
+```
+
+完整检查、测试与构建：
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run pytest
+uv build
+```

cann_cann-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "cann-cann"
+version = "0.1.0"
+description = "看看环境上的 NPU 参数"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[[project.authors]]
+name = "liggest"
+
+[project.urls]
+Homepage = "https://github.com/liggest/cann-cann"
+Repository = "https://github.com/liggest/cann-cann"
+Issues = "https://github.com/liggest/cann-cann/issues"
+
+[project.scripts]
+cann-cann = "cann_cann.cli:main"
+ccann = "cann_cann.cli:main"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.2",
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 140
+exclude = [".agents"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.2,<0.13.0"]
+build-backend = "uv_build"

cann_cann-0.1.0/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "cann-cann"
+version = "0.1.0"
+description = "看看环境上的 NPU 参数"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[[project.authors]]
+name = "liggest"
+
+[project.urls]
+Homepage = "https://github.com/liggest/cann-cann"
+Repository = "https://github.com/liggest/cann-cann"
+Issues = "https://github.com/liggest/cann-cann/issues"
+
+[project.scripts]
+cann-cann = "cann_cann.cli:main"
+ccann = "cann_cann.cli:main"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.2",
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 140
+exclude = [".agents"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[build-system]
+requires = ["uv_build>=0.12.2,<0.13.0"]
+build-backend = "uv_build"

cann_cann-0.1.0/src/cann_cann/__init__.py

@@ -0,0 +1,149 @@
+"""看看环境上的 NPU 参数"""
+
+from __future__ import annotations
+
+from functools import cache, lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from . import environment as _environment
+from .config import (
+    AICoreSpecSection,
+    CANNPlatformConfig,
+    PlatformConfigSection,
+    SoCInfoSection,
+    VersionSection,
+)
+from .errors import (
+    CannCannError,
+    CANNNotFoundError,
+    NPUDetectionError,
+    PlatformConfigError,
+    PlatformConfigNotFoundError,
+)
+from .units import SizeUnit
+
+if TYPE_CHECKING:
+    __version__: str
+
+
+def __getattr__(name: str) -> str:
+    """按需读取安装包版本，首次读取后缓存结果"""
+
+    if name != "__version__":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib.metadata import version
+
+    package_version = version("cann-cann")
+    globals()[name] = package_version
+    return package_version
+
+
+@lru_cache(maxsize=1)
+def _default_platform_config_directory() -> Path:
+    cann_home = _environment.find_cann_home()
+    return _environment.platform_config_directory(cann_home)
+
+
+@cache
+def _platform_config_by_name(npu_name: str) -> CANNPlatformConfig:
+    if not npu_name or Path(npu_name).name != npu_name:
+        raise ValueError(f"NPU 名称无效：{npu_name!r}")
+    path = _default_platform_config_directory() / f"{npu_name}.ini"
+    return CANNPlatformConfig.from_file(path)
+
+
+def npu_name() -> str:
+    """返回 ACL 探测到的 NPU 名称，并缓存首次成功的结果"""
+
+    return _environment.detect_npu_name()
+
+
+def all_npu_names() -> list[str]:
+    """列出当前 CANN 安装中包含平台配置的 NPU 名称"""
+
+    directory = _default_platform_config_directory()
+    return sorted(path.stem for path in directory.glob("*.ini") if path.is_file())
+
+
+def platform_config(npu_name: str | None = None) -> CANNPlatformConfig:
+    """返回 *npu_name* 对应的平台配置；不指定时自动探测 NPU 名称"""
+
+    resolved_name = _environment.detect_npu_name() if npu_name is None else npu_name.strip()
+    return _platform_config_by_name(resolved_name)
+
+
+def ub_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的 AI Core UB 大小"""
+
+    return platform_config(npu_name).ub_size(unit)
+
+
+def l0_a_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的 L0A 大小"""
+
+    return platform_config(npu_name).l0_a_size(unit)
+
+
+def l0_b_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的 L0B 大小"""
+
+    return platform_config(npu_name).l0_b_size(unit)
+
+
+def l0_c_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的 L0C 大小"""
+
+    return platform_config(npu_name).l0_c_size(unit)
+
+
+def l1_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的 L1 大小"""
+
+    return platform_config(npu_name).l1_size(unit)
+
+
+def l2_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的 L2 大小"""
+
+    return platform_config(npu_name).l2_size(unit)
+
+
+def memory_size(*, npu_name: str | None = None, unit: SizeUnit | str = "bytes") -> int | float:
+    """返回指定 NPU 的显存大小"""
+
+    return platform_config(npu_name).memory_size(unit)
+
+
+def ai_core_count(*, npu_name: str | None = None) -> int:
+    """返回指定 NPU 的 AI Core 数量"""
+
+    return platform_config(npu_name).ai_core_count()
+
+
+__all__ = [
+    "__version__",
+    "AICoreSpecSection",
+    "CANNNotFoundError",
+    "CANNPlatformConfig",
+    "CannCannError",
+    "NPUDetectionError",
+    "PlatformConfigError",
+    "PlatformConfigNotFoundError",
+    "PlatformConfigSection",
+    "SizeUnit",
+    "SoCInfoSection",
+    "VersionSection",
+    "ai_core_count",
+    "all_npu_names",
+    "l0_a_size",
+    "l0_b_size",
+    "l0_c_size",
+    "l1_size",
+    "l2_size",
+    "memory_size",
+    "npu_name",
+    "platform_config",
+    "ub_size",
+]

cann_cann-0.1.0/src/cann_cann/cli.py

@@ -0,0 +1,135 @@
+"""cann-cann 命令行入口"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TypeAlias
+
+from .errors import CannCannError
+
+_SIZE_QUERIES = {
+    "l0_a": "l0_a_size",
+    "l0a": "l0_a_size",
+    "l0_b": "l0_b_size",
+    "l0b": "l0_b_size",
+    "l0_c": "l0_c_size",
+    "l0c": "l0_c_size",
+    "l1": "l1_size",
+    "l2": "l2_size",
+    "hbm": "memory_size",
+    "memory": "memory_size",
+    "ub": "ub_size",
+}
+_COUNT_QUERIES = {
+    "ai_core_count": "ai_core_count",
+    "ai_cores": "ai_core_count",
+    "cores": "ai_core_count",
+}
+_CLIResult: TypeAlias = str | list[str] | int | float
+
+
+class _VersionAction(argparse.Action):
+    def __init__(self, option_strings: Sequence[str], dest: str, **kwargs) -> None:
+        super().__init__(option_strings, dest, nargs=0, **kwargs)
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: object,
+        option_string: str | None = None,
+    ) -> None:
+        import cann_cann
+
+        print(f"{parser.prog} {cann_cann.__version__}")
+        parser.exit()
+
+
+def _parser(prog: str = "cann-cann") -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        description="看看环境上的 NPU 参数",
+        epilog="AI Core 数量可用 AI_CORE_COUNT、cores 或 ai-cores 查询",
+        add_help=False,
+    )
+    parser._positionals.title = "位置参数"
+    parser._optionals.title = "选项"
+    parser.add_argument("-h", "--help", action="help", help="显示帮助信息并退出")
+    parser.add_argument("-v", "--version", action=_VersionAction, help="显示版本信息并退出")
+    parser.add_argument(
+        "query",
+        help="例如 UB、L1、memory、cores、npu-name 或 all-npu-names",
+    )
+    parser.add_argument(
+        "--npu-name",
+        metavar="NAME",
+        help="读取指定 NPU 名称的配置，不再自动探测",
+    )
+    units = parser.add_mutually_exclusive_group()
+    units.add_argument(
+        "--unit",
+        choices=("bytes", "kb", "kib", "mb", "mib", "gb", "gib"),
+        help="存储空间大小的输出单位（默认：bytes）",
+    )
+    units.add_argument("--kb", action="store_const", const="kb", dest="short_unit", help="以 kb 输出")
+    units.add_argument("--kib", action="store_const", const="kib", dest="short_unit", help="同 --kb")
+    units.add_argument("--mb", action="store_const", const="mb", dest="short_unit", help="以 mb 输出")
+    units.add_argument("--mib", action="store_const", const="mib", dest="short_unit", help="同 --mb")
+    units.add_argument("--gb", action="store_const", const="gb", dest="short_unit", help="以 gb 输出")
+    units.add_argument("--gib", action="store_const", const="gib", dest="short_unit", help="同 --gb")
+    return parser
+
+
+def _run(args: argparse.Namespace) -> _CLIResult:
+    # 运行时导入，确保 CLI 始终通过公开 Python API 完成查询
+    import cann_cann
+
+    query = args.query.lower().replace("-", "_")
+    unit = args.unit or args.short_unit or "bytes"
+
+    if query == "npu_name":
+        if args.npu_name is not None:
+            raise ValueError("查询 npu-name 时不能使用 --npu-name")
+        return cann_cann.npu_name()
+    if query == "all_npu_names":
+        if args.npu_name is not None:
+            raise ValueError("查询 all-npu-names 时不能使用 --npu-name")
+        return cann_cann.all_npu_names()
+    if query in _SIZE_QUERIES:
+        function = getattr(cann_cann, _SIZE_QUERIES[query])
+        return function(npu_name=args.npu_name, unit=unit)
+    if query in _COUNT_QUERIES:
+        if args.unit is not None or args.short_unit is not None:
+            raise ValueError("单位选项只能用于查询存储空间大小")
+        function = getattr(cann_cann, _COUNT_QUERIES[query])
+        return function(npu_name=args.npu_name)
+
+    raise ValueError(f"未知的查询项：{args.query}")
+
+
+def _print_result(result: _CLIResult) -> None:
+    if isinstance(result, list):
+        for item in result:
+            print(item)
+        return
+    print(result)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """运行命令行程序并返回退出码"""
+    prog = Path(sys.argv[0]).name if argv is None else "cann-cann"
+    parser = _parser(prog)
+    args = parser.parse_args(argv)
+    try:
+        _print_result(_run(args))
+    except (CannCannError, ValueError) as error:
+        print(f"错误：{error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

cann_cann-0.1.0/src/cann_cann/config.py

@@ -0,0 +1,285 @@
+"""CANN 平台配置文件的只读对象模型"""
+
+from __future__ import annotations
+
+import errno
+import os
+from collections.abc import Iterator, Mapping
+from configparser import ConfigParser
+from configparser import Error as ConfigParserError
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import MappingProxyType
+
+from .errors import (
+    PlatformConfigError,
+    PlatformConfigNotFoundError,
+)
+from .units import SizeUnit, convert_size
+
+
+def _optional_text(values: Mapping[str, str], key: str) -> str | None:
+    value = values.get(key)
+    return value if value not in (None, "") else None
+
+
+def _optional_int(values: Mapping[str, str], key: str) -> int | None:
+    value = _optional_text(values, key)
+    return None if value is None else int(value, 0)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PlatformConfigSection:
+    """一个 INI Section 的只读快照
+
+    已知的 Section 通过子类提供带类型提示的属性；同时保留完整原始数据，使新版
+    CANN 新增的字段在公共数据模型尚未适配时仍然可以读取
+    """
+
+    name: str
+    _raw: Mapping[str, str] = field(repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_raw", MappingProxyType(dict(self._raw)))
+
+    def raw(self, name: str) -> str | None:
+        """返回未经转换的 INI 字符串；字段不存在时返回 ``None``"""
+
+        return self._raw.get(name)
+
+    def raw_items(self) -> Mapping[str, str]:
+        """返回该 Section 未经转换的只读键值映射"""
+
+        return self._raw
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._raw)
+
+    def __len__(self) -> int:
+        return len(self._raw)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class VersionSection(PlatformConfigSection):
+    """``[version]`` 中的常用类型化字段"""
+
+    soc_version: str
+    short_soc_version: str | None
+    npu_arch: int | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SoCInfoSection(PlatformConfigSection):
+    """``[SoCInfo]`` 中的常用类型化字段"""
+
+    ai_core_count: int | None
+    cube_core_count: int | None
+    vector_core_count: int | None
+    memory_size: int | None
+    l2_size: int | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AICoreSpecSection(PlatformConfigSection):
+    """``[AICoreSpec]`` 中的常用类型化字段"""
+
+    l0_a_size: int | None
+    l0_b_size: int | None
+    l0_c_size: int | None
+    l1_size: int | None
+    ub_size: int | None
+    ub_block_size: int | None
+
+
+def _version_section(name: str, raw: Mapping[str, str]) -> VersionSection:
+    soc_version = _optional_text(raw, "SoC_version")
+    if soc_version is None:
+        raise PlatformConfigError("[version] 缺少必要字段 SoC_version")
+    return VersionSection(
+        name=name,
+        _raw=raw,
+        soc_version=soc_version,
+        short_soc_version=_optional_text(raw, "Short_SoC_version"),
+        npu_arch=_optional_int(raw, "NpuArch"),
+    )
+
+
+def _soc_info_section(name: str, raw: Mapping[str, str]) -> SoCInfoSection:
+    return SoCInfoSection(
+        name=name,
+        _raw=raw,
+        ai_core_count=_optional_int(raw, "ai_core_cnt"),
+        cube_core_count=_optional_int(raw, "cube_core_cnt"),
+        vector_core_count=_optional_int(raw, "vector_core_cnt"),
+        memory_size=_optional_int(raw, "memory_size"),
+        l2_size=_optional_int(raw, "l2_size"),
+    )
+
+
+def _ai_core_spec_section(name: str, raw: Mapping[str, str]) -> AICoreSpecSection:
+    return AICoreSpecSection(
+        name=name,
+        _raw=raw,
+        l0_a_size=_optional_int(raw, "l0_a_size"),
+        l0_b_size=_optional_int(raw, "l0_b_size"),
+        l0_c_size=_optional_int(raw, "l0_c_size"),
+        l1_size=_optional_int(raw, "l1_size"),
+        ub_size=_optional_int(raw, "ub_size"),
+        ub_block_size=_optional_int(raw, "ubblock_size"),
+    )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CANNPlatformConfig:
+    """一份 CANN 平台配置的只读类型化视图"""
+
+    version: VersionSection
+    soc_info: SoCInfoSection
+    ai_core_spec: AICoreSpecSection
+    _sections: Mapping[str, PlatformConfigSection] = field(repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        sections = MappingProxyType(dict(self._sections))
+        object.__setattr__(self, "_sections", sections)
+        if sections.get("version") is not self.version:
+            raise ValueError("version 必须引用已注册的 [version] Section")
+        if sections.get("SoCInfo") is not self.soc_info:
+            raise ValueError("soc_info 必须引用已注册的 [SoCInfo] Section")
+        if sections.get("AICoreSpec") is not self.ai_core_spec:
+            raise ValueError("ai_core_spec 必须引用已注册的 [AICoreSpec] Section")
+
+    @property
+    def npu_name(self) -> str:
+        """CANN 在 ``SoC_version`` 中记录的 NPU 名称"""
+
+        return self.version.soc_version
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> CANNPlatformConfig:
+        """解析 *path* 指向的 INI 文件，返回只读平台配置"""
+
+        config_path = Path(path)
+        if not config_path.is_file():
+            raise PlatformConfigNotFoundError(
+                errno.ENOENT,
+                "找不到平台配置文件",
+                os.fspath(config_path),
+            )
+
+        parser = ConfigParser(
+            interpolation=None,
+            strict=True,
+            empty_lines_in_values=False,
+        )
+        parser.optionxform = str
+        try:
+            with config_path.open(encoding="utf-8") as stream:
+                parser.read_file(stream)
+        except FileNotFoundError as error:
+            raise PlatformConfigNotFoundError(
+                errno.ENOENT,
+                "找不到平台配置文件",
+                os.fspath(config_path),
+            ) from error
+        except ConfigParserError as error:
+            raise PlatformConfigError(f"无法解析平台配置 {config_path}：{error}") from error
+
+        raw_sections = {name: dict(parser.items(name, raw=True)) for name in parser.sections()}
+        missing = [name for name in ("version", "SoCInfo", "AICoreSpec") if name not in raw_sections]
+        if missing:
+            names = ", ".join(f"[{name}]" for name in missing)
+            raise PlatformConfigError(f"平台配置缺少必要的 Section：{names}")
+
+        sections: dict[str, PlatformConfigSection] = {}
+        try:
+            for name, raw in raw_sections.items():
+                if name == "version":
+                    section = _version_section(name, raw)
+                elif name == "SoCInfo":
+                    section = _soc_info_section(name, raw)
+                elif name == "AICoreSpec":
+                    section = _ai_core_spec_section(name, raw)
+                else:
+                    section = PlatformConfigSection(name=name, _raw=raw)
+                sections[name] = section
+        except PlatformConfigError:
+            raise
+        except ValueError as error:
+            raise PlatformConfigError(f"平台配置 {config_path} 中存在无效值：{error}") from error
+
+        version = sections["version"]
+        soc_info = sections["SoCInfo"]
+        ai_core_spec = sections["AICoreSpec"]
+        assert isinstance(version, VersionSection)
+        assert isinstance(soc_info, SoCInfoSection)
+        assert isinstance(ai_core_spec, AICoreSpecSection)
+        return cls(
+            version=version,
+            soc_info=soc_info,
+            ai_core_spec=ai_core_spec,
+            _sections=sections,
+        )
+
+    def raw_section(self, name: str) -> Mapping[str, str] | None:
+        """返回 *name* 对应的原始只读映射；Section 不存在时返回 ``None``"""
+
+        section = self._sections.get(name)
+        return None if section is None else section.raw_items()
+
+    def section(self, name: str) -> PlatformConfigSection | None:
+        """按 INI 中的原始名称返回 Section；不存在时返回 ``None``"""
+
+        return self._sections.get(name)
+
+    @staticmethod
+    def _required_size(value: int | None, field_name: str) -> int:
+        if value is None:
+            raise PlatformConfigError(f"当前平台配置中没有字段 {field_name}")
+        return value
+
+    def ub_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 AI Core UB 大小"""
+
+        value = self._required_size(self.ai_core_spec.ub_size, "AICoreSpec.ub_size")
+        return convert_size(value, unit)
+
+    def l0_a_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 L0A 大小"""
+
+        value = self._required_size(self.ai_core_spec.l0_a_size, "AICoreSpec.l0_a_size")
+        return convert_size(value, unit)
+
+    def l0_b_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 L0B 大小"""
+
+        value = self._required_size(self.ai_core_spec.l0_b_size, "AICoreSpec.l0_b_size")
+        return convert_size(value, unit)
+
+    def l0_c_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 L0C 大小"""
+
+        value = self._required_size(self.ai_core_spec.l0_c_size, "AICoreSpec.l0_c_size")
+        return convert_size(value, unit)
+
+    def l1_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 L1 大小"""
+
+        value = self._required_size(self.ai_core_spec.l1_size, "AICoreSpec.l1_size")
+        return convert_size(value, unit)
+
+    def l2_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 L2 大小"""
+
+        value = self._required_size(self.soc_info.l2_size, "SoCInfo.l2_size")
+        return convert_size(value, unit)
+
+    def memory_size(self, unit: SizeUnit | str = "bytes") -> int | float:
+        """按指定单位返回 NPU 显存大小"""
+
+        value = self._required_size(self.soc_info.memory_size, "SoCInfo.memory_size")
+        return convert_size(value, unit)
+
+    def ai_core_count(self) -> int:
+        """返回 AI Core 数量"""
+
+        return self._required_size(self.soc_info.ai_core_count, "SoCInfo.ai_core_cnt")

cann_cann-0.1.0/src/cann_cann/environment.py

@@ -0,0 +1,95 @@
+"""发现当前 CANN 安装及其中的平台配置"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import platform
+from collections.abc import Mapping
+from functools import lru_cache
+from pathlib import Path
+
+from .errors import CANNNotFoundError, NPUDetectionError
+
+_CANN_HOME_VARIABLES = (
+    "ASCEND_HOME_PATH",
+    "ASCEND_TOOLKIT_HOME",
+    "ASCEND_TOOLKIT_LATEST_HOME",
+)
+_DEFAULT_CANN_HOMES = (Path("/usr/local/Ascend/cann"),)
+_ARCHITECTURES = {
+    "aarch64": "aarch64",
+    "arm64": "aarch64",
+    "x86_64": "x86_64",
+    "amd64": "x86_64",
+}
+
+
+def normalize_architecture(machine: str | None = None) -> str:
+    """返回 CANN 安装路径中使用的架构名称"""
+
+    detected = platform.machine() if machine is None else machine
+    try:
+        return _ARCHITECTURES[detected.strip().lower()]
+    except KeyError as exc:
+        raise CANNNotFoundError(f"CANN 不支持当前主机架构：{detected!r}") from exc
+
+
+def platform_config_directory(cann_home: str | os.PathLike[str], *, machine: str | None = None) -> Path:
+    """返回 CANN 安装中的平台配置目录"""
+
+    arch = normalize_architecture(machine)
+    return Path(cann_home).expanduser() / f"{arch}-linux" / "data" / "platform_config"
+
+
+def find_cann_home(
+    *,
+    environ: Mapping[str, str] | None = None,
+    machine: str | None = None,
+    default_homes: tuple[Path, ...] = _DEFAULT_CANN_HOMES,
+) -> Path:
+    """按约定的环境变量优先级查找可用的 CANN 根目录"""
+
+    environment = os.environ if environ is None else environ
+    candidates = [Path(value).expanduser() for name in _CANN_HOME_VARIABLES if (value := environment.get(name))]
+    candidates.extend(default_homes)
+
+    for candidate in candidates:
+        if platform_config_directory(candidate, machine=machine).is_dir():
+            return candidate.resolve()
+
+    searched = ", ".join(str(path) for path in candidates) or "没有可供查找的路径"
+    raise CANNNotFoundError(f"找不到包含平台配置的 CANN 安装；已查找：{searched}")
+
+
+@lru_cache(maxsize=1)
+def detect_npu_name() -> str:
+    """通过 ACL 探测 NPU 名称，并缓存首次成功的结果"""
+
+    try:
+        acl = importlib.import_module("acl")
+    except (ImportError, OSError) as exc:
+        raise NPUDetectionError("无法导入 ACL，因而无法探测 NPU 名称；请显式指定 npu_name") from exc
+
+    try:
+        name = acl.get_soc_name()
+    except Exception as exc:
+        raise NPUDetectionError("ACL 探测 NPU 名称失败；请显式指定 npu_name") from exc
+
+    if not isinstance(name, str) or not name.strip():
+        raise NPUDetectionError("ACL 未返回有效的 NPU 名称；请显式指定 npu_name")
+    return name.strip()
+
+
+def list_npu_names(
+    *,
+    cann_home: str | os.PathLike[str] | None = None,
+    machine: str | None = None,
+) -> list[str]:
+    """列出当前 CANN 安装中包含平台配置的 NPU 名称"""
+
+    home = find_cann_home(machine=machine) if cann_home is None else Path(cann_home)
+    directory = platform_config_directory(home, machine=machine)
+    if not directory.is_dir():
+        raise CANNNotFoundError(f"CANN 平台配置目录不存在：{directory}")
+    return sorted(path.stem for path in directory.glob("*.ini") if path.is_file())

cann_cann-0.1.0/src/cann_cann/errors.py

@@ -0,0 +1,21 @@
+"""cann-cann 的公开异常"""
+
+
+class CannCannError(Exception):
+    """cann-cann 公开异常的基类"""
+
+
+class CANNNotFoundError(CannCannError):
+    """找不到可用的 CANN 安装时抛出"""
+
+
+class NPUDetectionError(CannCannError):
+    """无法探测当前 NPU 名称时抛出"""
+
+
+class PlatformConfigError(CannCannError):
+    """无法使用 CANN 平台配置时抛出"""
+
+
+class PlatformConfigNotFoundError(PlatformConfigError, FileNotFoundError):
+    """找不到所需的平台配置文件时抛出"""

cann_cann-0.1.0/src/cann_cann/units.py

@@ -0,0 +1,37 @@
+"""存储空间大小的单位转换"""
+
+from __future__ import annotations
+
+from typing import Literal, TypeAlias
+
+SizeUnit: TypeAlias = Literal["bytes", "kb", "kib", "mb", "mib", "gb", "gib"]
+
+_UNIT_DIVISORS: dict[str, int] = {
+    "bytes": 1,
+    "kb": 1024,
+    "kib": 1024,
+    "mb": 1024**2,
+    "mib": 1024**2,
+    "gb": 1024**3,
+    "gib": 1024**3,
+}
+
+
+def convert_size(value: int, unit: SizeUnit | str = "bytes") -> int | float:
+    """将字节数转换为支持的二进制单位
+
+    为方便使用，``kb`` 与 ``kib``、``mb`` 与 ``mib``、``gb`` 与 ``gib``
+    含义相同，均按 1024 进制换算。结果能整除时返回整数，否则返回浮点数
+    """
+
+    normalized_unit = unit.lower()
+    try:
+        divisor = _UNIT_DIVISORS[normalized_unit]
+    except KeyError as error:
+        choices = ", ".join(_UNIT_DIVISORS)
+        raise ValueError(f"不支持的单位 {unit!r}；可选值：{choices}") from error
+
+    quotient, remainder = divmod(value, divisor)
+    if remainder == 0:
+        return quotient
+    return value / divisor