hatch-native 0.1.0__py3-none-any.whl

hatch_native/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.1.0"
+
+from .config import ExternalLibraryConfig, LibraryValidationConfig, ValidationCommandConfig
+from .external import LIBRARY_SOURCES, ExternalLibrary, LibrarySource, pkg_config_variable, resolve_external_library, resolve_library_source
+from .headers import check_headers, header_symbols, prefixed_header_symbols
+from .manifest import MANIFEST_VERSION, write_artifact_manifest
+from .naming import shared_library_name
+from .symbols import exported_symbols
+from .validation import check_exports, run_validation_command

hatch_native/config.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator, model_validator
+
+__all__ = ("ExternalLibraryConfig", "LibraryValidationConfig", "ValidationCommandConfig")
+
+
+class ValidationCommandConfig(BaseModel):
+    """A project-specific command used to validate a built artifact."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    command: list[str] = Field(description="Validation command argv list.")
+    working_directory: Path | None = Field(default=None, alias="working-directory", description="Validation command working directory.")
+    env: dict[str, str] = Field(default_factory=dict, description="Additional environment variables for this validation command.")
+
+    @field_validator("command", mode="before")
+    @classmethod
+    def validate_command(cls, values: Any) -> list[str]:
+        if isinstance(values, str):
+            raise TypeError("Validation command must be an argv list, not a shell string.")
+        return [str(value) for value in values]
+
+    @field_validator("working_directory", mode="before")
+    @classmethod
+    def validate_working_directory(cls, path: Path | None) -> Path | None:
+        if path is None:
+            return None
+        if not isinstance(path, Path):
+            path = Path(path)
+        return path
+
+
+class LibraryValidationConfig(BaseModel):
+    """Header and export validation fields, named the same in every hatch native plugin.
+
+    Each field accepts its kebab-case name in pyproject.toml and its
+    snake_case name in Python.
+    """
+
+    expected_symbols: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("expected-symbols", "expected_symbols"),
+        description="Exported symbols expected in a copied library.",
+    )
+    header_symbol_prefix: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("header-symbol-prefix", "header_symbol_prefix"),
+        description="Expect every function in expected-headers whose name starts with this prefix to be exported.",
+    )
+    expected_headers: list[Path] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("expected-headers", "expected_headers"),
+        description="Header files expected to exist after build.",
+    )
+    expected_abi_strings: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("expected-abi-strings", "expected_abi_strings"),
+        description="ABI version strings or macros expected in the configured headers.",
+    )
+    validate_artifact: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("validate", "validate_artifact"),
+        description="Load the copied library with ctypes.CDLL after copy. Requires a library built for the host.",
+    )
+    validation_commands: list[ValidationCommandConfig] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("validation-commands", "validation_commands"),
+        description="Project-specific validation commands to run after artifact copy.",
+    )
+
+    @field_validator("expected_symbols", "expected_abi_strings", mode="before")
+    @classmethod
+    def validate_validation_strings(cls, values: Any) -> list[str]:
+        if values is None:
+            return []
+        if isinstance(values, str):
+            return [values]
+        return [str(value) for value in values]
+
+    @field_validator("expected_headers", mode="before")
+    @classmethod
+    def validate_expected_headers(cls, values: Any) -> list[Path]:
+        if values is None:
+            return []
+        if isinstance(values, (str, Path)):
+            values = [values]
+        return [value if isinstance(value, Path) else Path(value) for value in values]
+
+    @field_validator("validation_commands", mode="before")
+    @classmethod
+    def validate_validation_commands(cls, values: Any) -> list[Any]:
+        if values is None:
+            return []
+        if isinstance(values, dict):
+            return [values]
+        if isinstance(values, list) and values and all(not isinstance(value, dict) for value in values):
+            return [{"command": values}]
+        return list(values)
+
+    @model_validator(mode="after")
+    def validate_header_symbol_prefix(self):
+        if self.header_symbol_prefix is not None and not self.expected_headers:
+            raise ValueError(f"Artifact '{getattr(self, 'name', None)}' must set expected-headers when using header-symbol-prefix.")
+        return self
+
+
+class ExternalLibraryConfig(BaseModel):
+    """Where to find a prebuilt library when it is not built by this project."""
+
+    pkg_config: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("pkg-config", "pkg_config"),
+        description="pkg-config module locating this library in external mode.",
+    )
+    library_root: Path | None = Field(
+        default=None,
+        validation_alias=AliasChoices("library-root", "library_root"),
+        description="Prefix with lib/ and include/ for this library in external mode.",
+    )
+    python_package: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("python-package", "python_package"),
+        description="Installed Python package shipping this library under lib/ and include/; linked from there instead of built.",
+    )
+
+    @field_validator("library_root", mode="before")
+    @classmethod
+    def validate_library_root(cls, path: Path | None) -> Path | None:
+        if path is None:
+            return None
+        if not isinstance(path, Path):
+            path = Path(path)
+        return path

hatch_native/external.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.util import find_spec
+from os import environ
+from pathlib import Path
+from shlex import join as shell_join
+from subprocess import run
+from typing import Literal
+
+from .naming import shared_library_name
+
+__all__ = (
+    "LIBRARY_SOURCES",
+    "ExternalLibrary",
+    "LibrarySource",
+    "pkg_config_variable",
+    "resolve_external_library",
+    "resolve_library_source",
+)
+
+LibrarySource = Literal["bundled", "external", "static", "direct"]
+LIBRARY_SOURCES: tuple[str, ...] = ("bundled", "external", "static", "direct")
+
+
+@dataclass(frozen=True)
+class ExternalLibrary:
+    """A prebuilt C ABI library resolved outside the build."""
+
+    name: str
+    library: Path
+    library_dir: Path
+    include_dir: Path | None
+    link_name: str
+    package: str | None = None
+
+
+def resolve_library_source(configured: str, *, env_var: str) -> str:
+    """Return `env_var` if set, else `configured`, rejecting anything but the four library-source modes."""
+    value = environ.get(env_var) or configured
+    if value not in LIBRARY_SOURCES:
+        raise ValueError(f"Unsupported {env_var}: {value}")
+    return value
+
+
+def pkg_config_variable(module: str, variable: str, *, label: str) -> Path:
+    """Read one pkg-config variable, such as libdir or includedir, for `module`."""
+    command = ["pkg-config", f"--variable={variable}", module]
+    try:
+        completed = run(command, capture_output=True, text=True, check=False)
+    except FileNotFoundError as error:
+        raise RuntimeError(f"Artifact '{label}' needs pkg-config on PATH to resolve '{module}'.") from error
+    if completed.returncode != 0 or not completed.stdout.strip():
+        raise RuntimeError(f"Artifact '{label}' pkg-config lookup failed: {shell_join(command)}: {completed.stderr.strip()}")
+    return Path(completed.stdout.strip())
+
+
+def resolve_external_library(
+    name: str,
+    *,
+    label: str,
+    platform: str,
+    root_env_var: str,
+    root: Path | None = None,
+    package: str | None = None,
+    pkg_config: str | None = None,
+) -> ExternalLibrary:
+    """Locate a prebuilt library and its headers.
+
+    Lookup order: an explicit `root` prefix, an installed Python `package`
+    shipping `lib/` and `include/`, a `pkg_config` module, then `$PREFIX` or
+    `$CONDA_PREFIX` (with `Library/` on Windows). `root_env_var` only names the
+    caller's override in the error message.
+    """
+    if root is not None:
+        library_dir, include_dir = root / "lib", root / "include"
+    elif package:
+        spec = find_spec(package)
+        if spec is None or not spec.submodule_search_locations:
+            raise ValueError(f"Artifact '{label}' package '{package}' is not installed in the build environment.")
+        prefix = Path(next(iter(spec.submodule_search_locations)))
+        library_dir, include_dir = prefix / "lib", prefix / "include"
+    elif pkg_config:
+        library_dir = pkg_config_variable(pkg_config, "libdir", label=label)
+        include_dir = pkg_config_variable(pkg_config, "includedir", label=label)
+    else:
+        conda_prefix = environ.get("PREFIX") or environ.get("CONDA_PREFIX")
+        if not conda_prefix:
+            raise ValueError(f"Artifact '{label}' is external but has no library-root, pkg-config, {root_env_var}, PREFIX, or CONDA_PREFIX.")
+        prefix = Path(conda_prefix) / "Library" if platform == "win32" else Path(conda_prefix)
+        library_dir, include_dir = prefix / "lib", prefix / "include"
+
+    shared_library = shared_library_name(name, platform=platform)
+    if platform == "win32":
+        candidates = [library_dir.parent / "bin" / shared_library, library_dir / shared_library]
+        link_name = name if (library_dir / f"{name}.lib").is_file() else f"{name}.dll"
+    elif platform == "darwin":
+        candidates = [library_dir / shared_library, *sorted(library_dir.glob(f"lib{name}.*.dylib"))]
+        link_name = name
+    else:
+        candidates = [library_dir / shared_library, *sorted(library_dir.glob(f"{shared_library}.*"))]
+        link_name = name
+    library = next((candidate for candidate in candidates if candidate.is_file()), None)
+    if library is None:
+        searched = ", ".join(str(candidate.parent) for candidate in candidates[:2])
+        raise FileNotFoundError(f"Artifact '{label}' external library '{shared_library}' was not found under {searched}.")
+    return ExternalLibrary(
+        name=name,
+        library=library,
+        library_dir=library_dir,
+        include_dir=include_dir if include_dir.is_dir() else None,
+        link_name=link_name,
+        package=package,
+    )

hatch_native/headers.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+from re import DOTALL, MULTILINE, escape, findall, sub
+
+__all__ = ("check_headers", "header_symbols", "prefixed_header_symbols")
+
+
+def header_symbols(text: str, prefix: str) -> list[str]:
+    """Functions declared in a C header whose names start with `prefix`.
+
+    Comments, preprocessor lines, `static inline` definitions, and function
+    pointer declarators such as `prefix_status (*open)(...)` are skipped, since
+    none of them is exported by the library. Declarations are found with
+    regular expressions rather than a C parser, which works for a hand-written
+    or generated ABI header.
+    """
+    text = sub(r"/\*.*?\*/", " ", text, flags=DOTALL)
+    text = sub(r"//[^\n]*", " ", text)
+    text = sub(r"^\s*#.*?(?<!\\)$", " ", text, flags=MULTILINE | DOTALL)
+    text = sub(r"\bstatic\s+inline\b[^;{]*\{", "static inline {", text)
+    declared = findall(rf"\b({escape(prefix)}\w*)\s*\((?!\s*\*)", text)
+    inline = set(findall(rf"\bstatic\s+(?:inline\s+)?[^;{{(]*?\b({escape(prefix)}\w*)\s*\((?!\s*\*)", text))
+    return sorted(set(declared) - inline)
+
+
+def check_headers(headers: list[Path], abi_strings: list[str], *, base: Path, label: str) -> list[Path]:
+    """Resolve expected headers against `base`, require each to be a file, and require every ABI string in one of them."""
+    resolved = []
+    for header in headers:
+        path = Path(header)
+        path = path.resolve() if path.is_absolute() else (base / path).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"Artifact '{label}' expected header does not exist: {header}")
+        if not path.is_file():
+            raise FileNotFoundError(f"Artifact '{label}' expected header is not a file: {header}")
+        resolved.append(path)
+
+    if abi_strings and not resolved:
+        raise ValueError(f"Artifact '{label}' must set expected-headers when using expected-abi-strings.")
+
+    for expected in abi_strings:
+        if not any(expected in header.read_text(errors="replace") for header in resolved):
+            raise RuntimeError(f"Artifact '{label}' expected ABI string was not found in headers: {expected}")
+    return resolved
+
+
+def prefixed_header_symbols(headers: list[Path], prefix: str | None, *, label: str) -> list[str]:
+    """Functions starting with `prefix` across `headers`; an error if a prefix is set and none match."""
+    if prefix is None:
+        return []
+    symbols = sorted({symbol for header in headers for symbol in header_symbols(header.read_text(errors="replace"), prefix)})
+    if not symbols:
+        raise RuntimeError(f"Artifact '{label}' expected headers declare no functions starting with '{prefix}'.")
+    return symbols

hatch_native/manifest.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from json import dumps
+from pathlib import Path
+
+__all__ = ("MANIFEST_VERSION", "write_artifact_manifest")
+
+MANIFEST_VERSION = 1
+
+
+def write_artifact_manifest(destination: Path, *, module: str, records: list[dict[str, str]]) -> None:
+    """Write the artifact manifest JSON shared by the hatch native plugins."""
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"version": MANIFEST_VERSION, "module": module, "artifacts": records}
+    destination.write_text(dumps(payload, indent=2, sort_keys=True) + "\n")

hatch_native/naming.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+__all__ = ("shared_library_name",)
+
+
+def shared_library_name(library: str, *, platform: str) -> str:
+    """Render a platform-specific standalone shared-library filename."""
+    if platform == "win32":
+        return f"{library}.dll"
+    if platform == "darwin":
+        return f"lib{library}.dylib"
+    if platform == "linux":
+        return f"lib{library}.so"
+    if platform == "emscripten":
+        return f"{library}.wasm"
+    raise ValueError(f"Unsupported platform: {platform}")

hatch_native/symbols.py

@@ -0,0 +1,172 @@
+"""Read exported symbol names from shared libraries without loading them.
+
+Supports ELF, Mach-O (including fat binaries), PE, and WebAssembly so that
+cross-compiled and Pyodide artifacts can be checked on any host.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from struct import Struct, unpack_from
+
+__all__ = ("exported_symbols",)
+
+_ELF_MAGIC = b"\x7fELF"
+_PE_MAGIC = b"MZ"
+_WASM_MAGIC = b"\x00asm"
+_MACHO_MAGICS = {
+    b"\xcf\xfa\xed\xfe": ("<", 64),
+    b"\xfe\xed\xfa\xcf": (">", 64),
+    b"\xce\xfa\xed\xfe": ("<", 32),
+    b"\xfe\xed\xfa\xce": (">", 32),
+}
+_FAT_MAGICS = {b"\xca\xfe\xba\xbe": 32, b"\xca\xfe\xba\xbf": 64}
+
+
+def exported_symbols(path: Path | str) -> set[str]:
+    """Return the names a shared library exports, as a C caller would spell them."""
+    data = Path(path).read_bytes()
+    if data[:4] == _ELF_MAGIC:
+        return _elf_exports(data)
+    if data[:4] in _MACHO_MAGICS:
+        return _macho_exports(data)
+    if data[:4] in _FAT_MAGICS:
+        return _fat_exports(data)
+    if data[:2] == _PE_MAGIC:
+        return _pe_exports(data)
+    if data[:4] == _WASM_MAGIC:
+        return _wasm_exports(data)
+    raise ValueError(f"Unrecognized shared library format: {path}")
+
+
+def _cstring(data: bytes, offset: int) -> str:
+    end = data.index(b"\x00", offset)
+    return data[offset:end].decode("utf-8", errors="replace")
+
+
+def _elf_exports(data: bytes) -> set[str]:
+    is_64 = data[4] == 2
+    endian = "<" if data[5] == 1 else ">"
+    if is_64:
+        shoff, shentsize, shnum = unpack_from(f"{endian}Q", data, 0x28)[0], *unpack_from(f"{endian}HH", data, 0x3A)
+        section_header = Struct(f"{endian}IIQQQQIIQQ")
+        symbol = Struct(f"{endian}IBBHQQ")
+    else:
+        shoff, shentsize, shnum = unpack_from(f"{endian}I", data, 0x20)[0], *unpack_from(f"{endian}HH", data, 0x2E)
+        section_header = Struct(f"{endian}IIIIIIIIII")
+        symbol = Struct(f"{endian}IIIBBH")
+
+    sections = [section_header.unpack_from(data, shoff + index * shentsize) for index in range(shnum)]
+    dynsym = next((section for section in sections if section[1] == 11), None)
+    if dynsym is None:
+        raise ValueError("ELF file has no dynamic symbol table")
+    _, _, _, _, sym_offset, sym_size, link, _, _, entsize = dynsym
+    str_offset = sections[link][4]
+
+    exported = set()
+    for index in range(sym_size // (entsize or symbol.size)):
+        fields = symbol.unpack_from(data, sym_offset + index * (entsize or symbol.size))
+        if is_64:
+            name, info, _, shndx = fields[0], fields[1], fields[2], fields[3]
+        else:
+            name, info, shndx = fields[0], fields[3], fields[5]
+        if shndx == 0 or info >> 4 not in (1, 2) or name == 0:
+            continue
+        exported.add(_cstring(data, str_offset + name))
+    return exported
+
+
+def _macho_exports(data: bytes, base: int = 0) -> set[str]:
+    endian, bits = _MACHO_MAGICS[data[base : base + 4]]
+    header_size = 32 if bits == 64 else 28
+    ncmds = unpack_from(f"{endian}I", data, base + 16)[0]
+    nlist = Struct(f"{endian}IBBHQ") if bits == 64 else Struct(f"{endian}IBBhI")
+
+    offset = base + header_size
+    symtab = None
+    for _ in range(ncmds):
+        cmd, cmdsize = unpack_from(f"{endian}II", data, offset)
+        if cmd == 0x2:
+            symtab = unpack_from(f"{endian}IIII", data, offset + 8)
+        offset += cmdsize
+    if symtab is None:
+        raise ValueError("Mach-O file has no symbol table")
+    symoff, nsyms, stroff, _ = symtab
+
+    exported = set()
+    for index in range(nsyms):
+        strx, n_type, _, _, _ = nlist.unpack_from(data, base + symoff + index * nlist.size)
+        if n_type & 0xE0 or not n_type & 0x01 or n_type & 0x0E != 0x0E:
+            continue
+        name = _cstring(data, base + stroff + strx)
+        exported.add(name.removeprefix("_"))
+    return exported
+
+
+def _fat_exports(data: bytes) -> set[str]:
+    bits = _FAT_MAGICS[data[:4]]
+    narch = unpack_from(">I", data, 4)[0]
+    arch = Struct(">IIQQII") if bits == 64 else Struct(">IIIII")
+    exported = set()
+    for index in range(narch):
+        fields = arch.unpack_from(data, 8 + index * arch.size)
+        exported |= _macho_exports(data, base=fields[2])
+    return exported
+
+
+def _pe_exports(data: bytes) -> set[str]:
+    pe_offset = unpack_from("<I", data, 0x3C)[0]
+    if data[pe_offset : pe_offset + 4] != b"PE\x00\x00":
+        raise ValueError("PE file has no PE signature")
+    nsections, optional_size = unpack_from("<H", data, pe_offset + 6)[0], unpack_from("<H", data, pe_offset + 20)[0]
+    optional_offset = pe_offset + 24
+    magic = unpack_from("<H", data, optional_offset)[0]
+    directory_offset = optional_offset + (112 if magic == 0x20B else 96)
+    export_rva, export_size = unpack_from("<II", data, directory_offset)
+    if export_rva == 0 or export_size == 0:
+        return set()
+
+    section = Struct("<8sIIIIIIHHI")
+    sections_offset = optional_offset + optional_size
+    sections = [section.unpack_from(data, sections_offset + index * section.size) for index in range(nsections)]
+
+    def file_offset(rva: int) -> int:
+        for _, virtual_size, virtual_address, raw_size, raw_pointer, *_ in sections:
+            if virtual_address <= rva < virtual_address + max(virtual_size, raw_size):
+                return rva - virtual_address + raw_pointer
+        raise ValueError(f"PE RVA {rva:#x} is not inside any section")
+
+    export_offset = file_offset(export_rva)
+    nnames, _, names_rva = unpack_from("<III", data, export_offset + 24)
+    names_offset = file_offset(names_rva)
+    return {_cstring(data, file_offset(unpack_from("<I", data, names_offset + index * 4)[0])) for index in range(nnames)}
+
+
+def _leb128(data: bytes, offset: int) -> tuple[int, int]:
+    result = shift = 0
+    while True:
+        byte = data[offset]
+        offset += 1
+        result |= (byte & 0x7F) << shift
+        shift += 7
+        if not byte & 0x80:
+            return result, offset
+
+
+def _wasm_exports(data: bytes) -> set[str]:
+    offset = 8
+    while offset < len(data):
+        section_id = data[offset]
+        size, offset = _leb128(data, offset + 1)
+        if section_id != 7:
+            offset += size
+            continue
+        count, offset = _leb128(data, offset)
+        exported = set()
+        for _ in range(count):
+            length, offset = _leb128(data, offset)
+            exported.add(data[offset : offset + length].decode("utf-8", errors="replace"))
+            offset += length
+            _, offset = _leb128(data, offset + 1)
+        return exported
+    return set()

hatch_native/tests/test_all.py

@@ -0,0 +1,5 @@
+from hatch_native import *
+
+
+def test_all():
+    assert True

hatch_native/tests/test_shared.py

@@ -0,0 +1,129 @@
+from json import loads
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from hatch_native import (
+    LibraryValidationConfig,
+    check_exports,
+    check_headers,
+    header_symbols,
+    prefixed_header_symbols,
+    resolve_external_library,
+    resolve_library_source,
+    shared_library_name,
+    write_artifact_manifest,
+)
+
+HEADER = """
+#define DEMO_ABI_VERSION 1
+/* demo_commented(void); */
+typedef int (*demo_callback)(int);
+int demo_answer(void);
+void demo_free(void *ptr);
+static inline int demo_inline(void) { return 1; }
+"""
+
+
+def test_header_symbols_skip_comments_pointers_and_inline():
+    assert header_symbols(HEADER, "demo_") == ["demo_answer", "demo_free"]
+
+
+def test_check_headers_resolves_and_finds_abi_string(tmp_path):
+    (tmp_path / "demo.h").write_text(HEADER)
+    assert check_headers([Path("demo.h")], ["DEMO_ABI_VERSION 1"], base=tmp_path, label="demo") == [(tmp_path / "demo.h").resolve()]
+
+
+def test_check_headers_errors(tmp_path):
+    with pytest.raises(FileNotFoundError, match="expected header does not exist"):
+        check_headers([Path("missing.h")], [], base=tmp_path, label="demo")
+    with pytest.raises(ValueError, match="must set expected-headers"):
+        check_headers([], ["DEMO_ABI_VERSION"], base=tmp_path, label="demo")
+    (tmp_path / "demo.h").write_text(HEADER)
+    with pytest.raises(RuntimeError, match="ABI string was not found"):
+        check_headers([Path("demo.h")], ["DEMO_ABI_VERSION 2"], base=tmp_path, label="demo")
+
+
+def test_prefixed_header_symbols(tmp_path):
+    header = tmp_path / "demo.h"
+    header.write_text(HEADER)
+    assert prefixed_header_symbols([header], None, label="demo") == []
+    assert prefixed_header_symbols([header], "demo_", label="demo") == ["demo_answer", "demo_free"]
+    with pytest.raises(RuntimeError, match="declare no functions starting with 'other_'"):
+        prefixed_header_symbols([header], "other_", label="demo")
+
+
+def test_check_exports_reports_missing(monkeypatch, tmp_path):
+    monkeypatch.setattr("hatch_native.validation.exported_symbols", lambda path: {"demo_answer"})
+    check_exports(tmp_path / "libdemo.so", expected=["demo_answer"], load=False, label="demo", display_path="lib/libdemo.so")
+    with pytest.raises(RuntimeError, match="expected symbol was not exported: demo_free"):
+        check_exports(tmp_path / "libdemo.so", expected=["demo_answer", "demo_free"], load=False, label="demo", display_path="lib/libdemo.so")
+
+
+@pytest.mark.parametrize(
+    "platform,filename",
+    [("linux", "libdemo.so"), ("darwin", "libdemo.dylib"), ("win32", "demo.dll"), ("emscripten", "demo.wasm")],
+)
+def test_shared_library_name(platform, filename):
+    assert shared_library_name("demo", platform=platform) == filename
+
+
+def test_resolve_library_source(monkeypatch):
+    monkeypatch.delenv("DEMO_LIBRARY_SOURCE", raising=False)
+    assert resolve_library_source("bundled", env_var="DEMO_LIBRARY_SOURCE") == "bundled"
+    monkeypatch.setenv("DEMO_LIBRARY_SOURCE", "external")
+    assert resolve_library_source("bundled", env_var="DEMO_LIBRARY_SOURCE") == "external"
+    monkeypatch.setenv("DEMO_LIBRARY_SOURCE", "vendored")
+    with pytest.raises(ValueError, match="Unsupported DEMO_LIBRARY_SOURCE: vendored"):
+        resolve_library_source("bundled", env_var="DEMO_LIBRARY_SOURCE")
+
+
+def test_resolve_external_library_from_root(tmp_path):
+    (tmp_path / "lib").mkdir()
+    (tmp_path / "include").mkdir()
+    (tmp_path / "lib" / "libdemo.so.1").write_bytes(b"")
+    external = resolve_external_library("demo", label="demo", platform="linux", root_env_var="DEMO_ROOT", root=tmp_path)
+    assert external.library == tmp_path / "lib" / "libdemo.so.1"
+    assert external.include_dir == tmp_path / "include"
+    assert external.link_name == "demo"
+
+
+def test_resolve_external_library_windows_prefers_bin_and_import_library(tmp_path):
+    (tmp_path / "lib").mkdir()
+    (tmp_path / "bin").mkdir()
+    (tmp_path / "bin" / "demo.dll").write_bytes(b"")
+    (tmp_path / "lib" / "demo.lib").write_bytes(b"")
+    external = resolve_external_library("demo", label="demo", platform="win32", root_env_var="DEMO_ROOT", root=tmp_path)
+    assert external.library == tmp_path / "bin" / "demo.dll"
+    assert external.link_name == "demo"
+    assert external.include_dir is None
+
+
+def test_resolve_external_library_errors(monkeypatch, tmp_path):
+    monkeypatch.delenv("PREFIX", raising=False)
+    monkeypatch.delenv("CONDA_PREFIX", raising=False)
+    with pytest.raises(ValueError, match="DEMO_ROOT, PREFIX, or CONDA_PREFIX"):
+        resolve_external_library("demo", label="demo", platform="linux", root_env_var="DEMO_ROOT")
+    with pytest.raises(FileNotFoundError, match="external library 'libdemo.so' was not found"):
+        resolve_external_library("demo", label="demo", platform="linux", root_env_var="DEMO_ROOT", root=tmp_path)
+    with pytest.raises(ValueError, match="package 'not_a_real_package' is not installed"):
+        resolve_external_library("demo", label="demo", platform="linux", root_env_var="DEMO_ROOT", package="not_a_real_package")
+
+
+def test_write_artifact_manifest(tmp_path):
+    destination = tmp_path / "demo" / "lib" / "artifacts.json"
+    write_artifact_manifest(destination, module="demo", records=[{"name": "demo", "role": "library"}])
+    assert loads(destination.read_text()) == {"version": 1, "module": "demo", "artifacts": [{"name": "demo", "role": "library"}]}
+
+
+def test_validation_config_accepts_both_spellings():
+    kebab = LibraryValidationConfig.model_validate({"expected-symbols": "demo_answer", "expected-headers": "demo.h", "validate": True})
+    snake = LibraryValidationConfig(expected_symbols=["demo_answer"], expected_headers=[Path("demo.h")], validate_artifact=True)
+    assert kebab == snake
+    assert LibraryValidationConfig.model_validate({"validation-commands": ["true"]}).validation_commands[0].command == ["true"]
+
+
+def test_validation_config_requires_headers_for_prefix():
+    with pytest.raises(ValidationError, match="must set expected-headers when using header-symbol-prefix"):
+        LibraryValidationConfig.model_validate({"header-symbol-prefix": "demo_"})

hatch_native/tests/test_symbols.py

@@ -0,0 +1,31 @@
+import _ctypes
+
+import pytest
+
+from hatch_native.symbols import exported_symbols
+
+
+def test_host_extension_module_exports_init_symbol():
+    assert "PyInit__ctypes" in exported_symbols(_ctypes.__file__)
+
+
+def test_wasm_export_section(tmp_path):
+    # (module (func $f (export "demo_answer") (result i32) i32.const 42) (memory (export "memory") 1))
+    module = bytes.fromhex(
+        "0061736d01000000"  # magic, version
+        "010501600001 7f"  # type section: () -> i32
+        "03020100"  # function section: one function of type 0
+        "0503010001"  # memory section: min 1 page
+        "071802 0b64656d6f5f616e737765720000 066d656d6f72790200"  # export section: demo_answer (func 0), memory (mem 0)
+        "0a06010400412a0b"  # code section
+    )
+    wasm = tmp_path / "demo.wasm"
+    wasm.write_bytes(module)
+    assert exported_symbols(wasm) == {"demo_answer", "memory"}
+
+
+def test_unknown_format_fails_clearly(tmp_path):
+    other = tmp_path / "other.so"
+    other.write_bytes(b"not a library")
+    with pytest.raises(ValueError, match="Unrecognized shared library format"):
+        exported_symbols(other)

hatch_native/validation.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from ctypes import CDLL
+from pathlib import Path
+from shlex import join as shell_join
+from subprocess import run
+
+from .symbols import exported_symbols
+
+__all__ = ("check_exports", "run_validation_command")
+
+
+def check_exports(library: Path, *, expected: list[str], load: bool, label: str, display_path: str) -> None:
+    """Require `expected` symbols in the export table of `library`, then optionally load it with ctypes."""
+    if expected:
+        try:
+            exported = exported_symbols(library)
+        except (OSError, ValueError) as error:
+            raise RuntimeError(f"Artifact '{label}' could not read exported symbols from '{display_path}': {error}") from error
+        missing = [symbol for symbol in expected if symbol not in exported]
+        if missing:
+            raise RuntimeError(f"Artifact '{label}' expected symbol was not exported: {', '.join(missing)}")
+
+    if load:
+        try:
+            CDLL(str(library))
+        except OSError as error:
+            raise RuntimeError(f"Artifact '{label}' failed validation load check for '{display_path}': {error}") from error
+
+
+def run_validation_command(command: list[str], *, cwd: Path, env: dict[str, str], label: str) -> None:
+    """Run one validation command argv, raising with the artifact label on a missing executable or non-zero exit."""
+    try:
+        completed = run(command, cwd=cwd, env=env, check=False)
+    except FileNotFoundError as error:
+        raise RuntimeError(f"Artifact '{label}' validation command was not found: {command[0]}") from error
+    if completed.returncode != 0:
+        raise RuntimeError(f"Artifact '{label}' validation command failed with exit code {completed.returncode}: {shell_join(command)}")

hatch_native-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: hatch-native
+Version: 0.1.0
+Summary: Shared native-build helpers for hatch plugins
+Project-URL: Repository, https://github.com/python-project-templates/hatch-native
+Project-URL: Homepage, https://github.com/python-project-templates/hatch-native
+Author-email: the hatch-native authors <t.paine154@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: pydantic
+Provides-Extra: develop
+Requires-Dist: build; extra == 'develop'
+Requires-Dist: bump-my-version; extra == 'develop'
+Requires-Dist: check-dist; extra == 'develop'
+Requires-Dist: codespell; extra == 'develop'
+Requires-Dist: hatchling; extra == 'develop'
+Requires-Dist: mdformat; extra == 'develop'
+Requires-Dist: mdformat-myst; extra == 'develop'
+Requires-Dist: mdformat-tables>=1; extra == 'develop'
+Requires-Dist: pytest; extra == 'develop'
+Requires-Dist: pytest-cov; extra == 'develop'
+Requires-Dist: ruff; extra == 'develop'
+Requires-Dist: twine; extra == 'develop'
+Requires-Dist: ty; extra == 'develop'
+Requires-Dist: uv; extra == 'develop'
+Requires-Dist: wheel; extra == 'develop'
+Description-Content-Type: text/markdown
+
+# hatch native
+
+Shared native-build helpers for hatch plugins
+
+[![Build Status](https://github.com/python-project-templates/hatch-native/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/python-project-templates/hatch-native/actions/workflows/build.yaml)
+[![codecov](https://codecov.io/gh/python-project-templates/hatch-native/branch/main/graph/badge.svg)](https://codecov.io/gh/python-project-templates/hatch-native)
+[![License](https://img.shields.io/github/license/python-project-templates/hatch-native)](https://github.com/python-project-templates/hatch-native)
+[![PyPI](https://img.shields.io/pypi/v/hatch-native.svg)](https://pypi.python.org/pypi/hatch-native)
+
+## Overview
+
+Helpers shared by the hatch native build plugins ([hatch-rs](https://github.com/python-project-templates/hatch-rs), [hatch-cpp](https://github.com/python-project-templates/hatch-cpp)) for wheels that ship a C ABI library next to a Python extension. It is a library for plugin authors, not a hatch plugin, and has no configuration of its own.
+
+| Module       | Provides                                                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `symbols`    | `exported_symbols(path)`: the export table of an ELF, Mach-O (including fat), PE, or WebAssembly binary, read without loading it                                                     |
+| `headers`    | `header_symbols(text, prefix)`, `check_headers(...)` for expected headers and ABI strings, `prefixed_header_symbols(...)`                                                            |
+| `validation` | `check_exports(...)` for expected symbols plus an optional `ctypes` load, `run_validation_command(...)`                                                                              |
+| `config`     | pydantic models `LibraryValidationConfig`, `ExternalLibraryConfig`, `ValidationCommandConfig`, so every plugin uses the same field names                                             |
+| `external`   | `resolve_library_source(...)` for `bundled`, `external`, `static`, `direct`; `resolve_external_library(...)` from a root, a Python package, pkg-config, or `$PREFIX`/`$CONDA_PREFIX` |
+| `manifest`   | `write_artifact_manifest(...)`: `{"version": 1, "module": ..., "artifacts": [...]}`                                                                                                  |
+| `naming`     | `shared_library_name(name, platform=...)`: `libfoo.so`, `libfoo.dylib`, `foo.dll`, `foo.wasm`                                                                                        |
+
+Plugins mix the config models into their own artifact models, so a project writes the same keys whichever plugin builds the library:
+
+```toml
+expected-headers = ["include/foo/foo.h"]
+header-symbol-prefix = "foo_"
+expected-abi-strings = ["FOO_ABI_VERSION 1"]
+validate = false
+```
+
+Each key also accepts its snake_case spelling.
+
+> [!NOTE]
+> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).

hatch_native-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+hatch_native/__init__.py,sha256=vt5NxBl-bYTix-TYO8Mgf3nNqvBY1jJxUs2vGwV8lkU,536
+hatch_native/config.py,sha256=_yc3kNOfcsH8Ua62sxYG0SVP9erfd5ZEK3aoSUQPte0,5684
+hatch_native/external.py,sha256=zh6jqfZEMRVhO-1DP853qKVcD0dyq0YHaomJ1Yso68k,4636
+hatch_native/headers.py,sha256=IaiQoCreYTarkdgKaToaRf1MvOS9CI0asy5BXLZv3CE,2729
+hatch_native/manifest.py,sha256=l3aIOuPZsX_ufK2Ph-l6zu5SKgkpVAT10Ua5kAdEr0I,567
+hatch_native/naming.py,sha256=MVsvTPPTOXIIEdnQAK8OKTNFDpAXr9isYgu1nK1xvto,522
+hatch_native/symbols.py,sha256=M3b1tJj-yIZZ8qtBbyHBlDF3Zszus3t_L74rdIPFYm0,6566
+hatch_native/validation.py,sha256=Z4HHcYCxh7hPNmL9jHFPFCAjinNc4CH4C0I5Q-f5Sc8,1749
+hatch_native/tests/test_all.py,sha256=ptrNJHxn3_oqh6soGK0Ln62P330yuGLIhzFyAYbb2WQ,61
+hatch_native/tests/test_shared.py,sha256=RjVcxiGiGCTXvrLnz3wXTA6EhBgVYY4fxdU98AYxEA8,6141
+hatch_native/tests/test_symbols.py,sha256=_tS5RTphjX3KnKt6tnOL4gZSqDCkNkR4jVCcPSq2K1g,1121
+hatch_native-0.1.0.dist-info/METADATA,sha256=sfh_YFD8mJX5FO70QKdADJleQJJdzNdQg5jisqfzOqo,5066
+hatch_native-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hatch_native-0.1.0.dist-info/licenses/LICENSE,sha256=RJv62sIjY-yDby6aGrpsXxXxN5lMUCxclVo4HZjsAno,11354
+hatch_native-0.1.0.dist-info/RECORD,,

hatch_native-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hatch_native-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 the hatch-native authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.