ft-readiness 0.1.0__py3-none-any.whl

ft_readiness/__init__.py

@@ -0,0 +1,5 @@
+"""Author-side readiness gate for free-threaded Python (3.14t)."""
+
+__version__ = "0.1.0"
+
+from .checks import Finding, run_static_checks  # noqa: E402,F401

ft_readiness/checks.py

@@ -0,0 +1,183 @@
+"""Static free-threading readiness checks over a built dist/ + project metadata.
+
+These run on any interpreter (no free-threaded build required). They catch the
+two genuinely-silent author-side failures: shipping no cp3XXt wheel for an
+extension package, and a Free Threading classifier that doesn't match the wheels
+actually shipped. The runtime GIL-slot check lives in runtime.py / the pytest
+plugin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from .metadata import ProjectMeta, resolve_meta
+from .wheels import Wheel, collect_wheels, find_sdists
+
+ERROR = "error"
+WARNING = "warning"
+INFO = "info"
+
+
+@dataclass
+class Finding:
+    code: str
+    level: str
+    message: str
+    hint: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "level": self.level,
+            "message": self.message,
+            "hint": self.hint,
+        }
+
+
+def _has_ext(wheels: List[Wheel]) -> bool:
+    return any(w.is_extension for w in wheels)
+
+
+def run_static_checks(
+    project_dir: Path,
+    dist_dir: Path,
+    meta: Optional[ProjectMeta] = None,
+) -> List[Finding]:
+    findings: List[Finding] = []
+    wheels = collect_wheels(dist_dir)
+    sdists = find_sdists(dist_dir)
+    if meta is None:
+        meta = resolve_meta(project_dir, dist_dir)
+
+    if not wheels and not sdists and meta is None:
+        findings.append(
+            Finding(
+                "FT000",
+                ERROR,
+                f"Nothing to inspect: no wheels/sdists in {dist_dir} and no "
+                "pyproject.toml with a [project] table.",
+                "Run this after `python -m build` (or point --dist / --project "
+                "at your artifacts).",
+            )
+        )
+        return findings
+
+    ft_wheels = [w for w in wheels if w.is_freethreaded]
+    ext_wheels = [w for w in wheels if w.is_extension]
+    abi3_wheels = [w for w in wheels if w.is_abi3]
+    has_ft_wheel = bool(ft_wheels)
+    has_ext = bool(ext_wheels)
+
+    ft_classifier = meta.ft_classifier if meta else None
+    ft_level = meta.ft_level if meta else None
+
+    # FT001 — classifier claims free-threading, but no cp3XXt wheel ships for an
+    # extension package. Users on a free-threaded build get zero parallelism.
+    if ft_classifier and has_ext and not has_ft_wheel:
+        findings.append(
+            Finding(
+                "FT001",
+                ERROR,
+                f"Declares '{ft_classifier}' but ships no free-threaded "
+                "(cp3XXt) wheel for its compiled extension.",
+                "Build a cp3XXt wheel (cibuildwheel with CIBW_ENABLE=cpython-"
+                "freethreading, or CPython 3.14t + your build backend), or drop "
+                "the Free Threading classifier until you ship one.",
+            )
+        )
+
+    # FT002 — ships a free-threaded wheel but no classifier => FT support is
+    # undiscoverable on PyPI; users can't filter for it.
+    if has_ft_wheel and not ft_classifier:
+        findings.append(
+            Finding(
+                "FT002",
+                WARNING,
+                "Ships a free-threaded (cp3XXt) wheel but declares no "
+                "'Programming Language :: Python :: Free Threading' classifier.",
+                "Add e.g. 'Programming Language :: Python :: Free Threading :: "
+                "2 - Beta' to [project].classifiers so PyPI surfaces it.",
+            )
+        )
+
+    # FT003 — extension package with per-platform CPython wheels but no
+    # free-threaded wheel at all: the silent missing-wheel case (users fall back
+    # to an sdist build, or get the GIL if they can't build).
+    if has_ext and not has_ft_wheel and not ft_classifier:
+        findings.append(
+            Finding(
+                "FT003",
+                WARNING,
+                "Ships compiled extension wheels but none for free-threaded "
+                "Python (cp3XXt). Users on 3.14t fall back to an sdist build or "
+                "lose parallelism.",
+                "Add a cp3XXt target to your wheel matrix once the extension is "
+                "free-threading ready.",
+            )
+        )
+
+    # FT004 — abi3/limited-API wheels but no FT wheel. The limited C API / stable
+    # ABI is NOT supported on the free-threaded build, so abi3 wheels do not
+    # cover 3.14t users — a dedicated cp3XXt wheel is required.
+    if abi3_wheels and not has_ft_wheel:
+        findings.append(
+            Finding(
+                "FT004",
+                WARNING,
+                "Ships abi3 (limited-API) wheels but no cp3XXt wheel. The stable "
+                "ABI is unsupported on the free-threaded build, so abi3 wheels "
+                "do NOT cover 3.14t users.",
+                "Build a separate free-threaded wheel; you can keep abi3 for the "
+                "GIL build (e.g. py_limited_api=not sysconfig.get_config_var("
+                "'Py_GIL_DISABLED')).",
+            )
+        )
+
+    # FT005 — requires-python excludes the versions that have free-threading
+    # while the package advertises FT support.
+    if (ft_classifier or has_ft_wheel) and meta and meta.requires_python:
+        if _excludes_free_threading(meta.requires_python):
+            findings.append(
+                Finding(
+                    "FT005",
+                    WARNING,
+                    f"Advertises free-threading but requires-python "
+                    f"'{meta.requires_python}' excludes 3.13+/3.14 where the "
+                    "free-threaded build exists.",
+                    "Widen requires-python to include the interpreter versions "
+                    "that ship a free-threaded build.",
+                )
+            )
+
+    # FT006 — pure-Python package declaring a Free Threading classifier is fine,
+    # but flag over-claiming Stable/Resilient with no test signal we can see.
+    if ft_classifier and not has_ext and ft_level and ft_level >= 3:
+        findings.append(
+            Finding(
+                "FT006",
+                INFO,
+                f"Pure-Python package declares '{ft_classifier}'. Pure Python "
+                "runs on the free-threaded build without a dedicated wheel; make "
+                "sure the Stable/Resilient claim is backed by thread-safety "
+                "tests.",
+                "Run your suite under 3.14t (pytest-run-parallel is useful) "
+                "before claiming level 3 - Stable or higher.",
+            )
+        )
+
+    return findings
+
+
+def _excludes_free_threading(requires_python: str) -> bool:
+    """True if the requires-python specifier admits NO version >= 3.13."""
+    try:
+        from packaging.specifiers import SpecifierSet
+        from packaging.version import Version
+
+        spec = SpecifierSet(requires_python)
+    except Exception:
+        return False
+    return not any(spec.contains(Version(v), prereleases=True) for v in ("3.13", "3.14", "3.15"))

ft_readiness/cli.py

@@ -0,0 +1,125 @@
+"""Command-line entry point for ft-readiness."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List
+
+from . import __version__
+from .checks import ERROR, INFO, WARNING, Finding, run_static_checks
+from .metadata import resolve_meta
+from .runtime import check_imports, is_free_threaded
+
+_LEVEL_ORDER = {ERROR: 0, WARNING: 1, INFO: 2}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ft-readiness",
+        description="Pre-publish free-threading readiness gate for Python "
+        "packages (catch a re-enabled GIL, a missing cp314t wheel, and a stale "
+        "Free Threading classifier before you publish).",
+    )
+    p.add_argument("project", nargs="?", default=".",
+                   help="project directory (default: current dir)")
+    p.add_argument("--dist", default=None,
+                   help="dist directory with built wheels/sdists (default: "
+                        "<project>/dist)")
+    p.add_argument("--import", dest="modules", action="append", default=[],
+                   metavar="MODULE",
+                   help="runtime check: import MODULE on a free-threaded build "
+                        "and fail if it re-enables the GIL (repeatable, or "
+                        "comma-separated)")
+    p.add_argument("--strict", action="store_true",
+                   help="treat warnings as failures (exit 1)")
+    p.add_argument("--format", choices=("text", "json"), default="text",
+                   help="output format (default: text)")
+    p.add_argument("--version", action="version",
+                   version=f"ft-readiness {__version__}")
+    return p
+
+
+def _split_modules(items: List[str]) -> List[str]:
+    out: List[str] = []
+    for it in items:
+        out.extend(m.strip() for m in it.split(",") if m.strip())
+    return out
+
+
+def main(argv: List[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    project_dir = Path(args.project).resolve()
+    dist_dir = Path(args.dist).resolve() if args.dist else project_dir / "dist"
+
+    meta = resolve_meta(project_dir, dist_dir)
+    findings: List[Finding] = run_static_checks(project_dir, dist_dir, meta)
+
+    modules = _split_modules(args.modules)
+    runtime_results = check_imports(modules) if modules else []
+    for r in runtime_results:
+        if r.status == "gil_reenabled":
+            findings.append(Finding(
+                "FT010", ERROR,
+                f"Importing '{r.module}' re-enabled the GIL: {r.detail}",
+                "Add the Py_mod_gil = Py_MOD_GIL_NOT_USED slot (multi-phase "
+                "init) or call PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED) "
+                "(single-phase) in the C extension, then rebuild.",
+            ))
+        elif r.status == "import_error":
+            findings.append(Finding(
+                "FT011", WARNING,
+                f"Could not import '{r.module}' for the runtime GIL check: "
+                f"{r.detail}",
+            ))
+
+    findings.sort(key=lambda f: (_LEVEL_ORDER.get(f.level, 9), f.code))
+
+    if args.format == "json":
+        payload = {
+            "version": __version__,
+            "project": str(project_dir),
+            "dist": str(dist_dir),
+            "meta_source": meta.source if meta else None,
+            "free_threaded_interpreter": is_free_threaded(),
+            "runtime_checks": [
+                {"module": r.module, "status": r.status, "detail": r.detail}
+                for r in runtime_results
+            ],
+            "findings": [f.to_dict() for f in findings],
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        _print_text(findings, runtime_results, modules)
+
+    errors = [f for f in findings if f.level == ERROR]
+    warnings_ = [f for f in findings if f.level == WARNING]
+    if errors or (args.strict and warnings_):
+        return 1
+    return 0
+
+
+def _print_text(findings, runtime_results, modules) -> None:
+    icon = {ERROR: "✗", WARNING: "!", INFO: "·"}
+    if not findings:
+        print("ft-readiness: no issues found.")
+    for f in findings:
+        print(f"{icon.get(f.level, '?')} {f.code} [{f.level}] {f.message}")
+        if f.hint:
+            print(f"    → {f.hint}")
+    if modules and not is_free_threaded():
+        print()
+        print("note: runtime --import checks were SKIPPED — this interpreter is "
+              "not a free-threaded build.")
+        print("      run under python3.14t (or CIBW/tox with a t-ABI env) to "
+              "exercise them.")
+    n_err = sum(1 for f in findings if f.level == ERROR)
+    n_warn = sum(1 for f in findings if f.level == WARNING)
+    print()
+    print(f"ft-readiness {__version__}: {n_err} error(s), {n_warn} warning(s).")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

ft_readiness/metadata.py

@@ -0,0 +1,96 @@
+"""Read project classifiers + requires-python from pyproject.toml, a wheel's
+METADATA, or an sdist's PKG-INFO.
+"""
+
+from __future__ import annotations
+
+import email
+import re
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+try:  # 3.11+
+    import tomllib as _toml
+except ModuleNotFoundError:  # pragma: no cover - exercised on <3.11
+    try:
+        import tomli as _toml  # type: ignore
+    except ModuleNotFoundError:  # pragma: no cover
+        _toml = None  # type: ignore
+
+_FT_CLASSIFIER_RE = re.compile(
+    r"^Programming Language :: Python :: Free Threading :: (\d)\s*-\s*(.+)$"
+)
+
+
+@dataclass
+class ProjectMeta:
+    source: str
+    classifiers: List[str] = field(default_factory=list)
+    requires_python: Optional[str] = None
+
+    @property
+    def ft_classifier(self) -> Optional[str]:
+        for c in self.classifiers:
+            if _FT_CLASSIFIER_RE.match(c.strip()):
+                return c.strip()
+        return None
+
+    @property
+    def ft_level(self) -> Optional[int]:
+        c = self.ft_classifier
+        if not c:
+            return None
+        m = _FT_CLASSIFIER_RE.match(c)
+        return int(m.group(1)) if m else None
+
+
+def from_pyproject(path: Path) -> Optional[ProjectMeta]:
+    if not path.is_file() or _toml is None:
+        return None
+    with path.open("rb") as fh:
+        data = _toml.load(fh)
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return None
+    return ProjectMeta(
+        source=str(path),
+        classifiers=list(project.get("classifiers", []) or []),
+        requires_python=project.get("requires-python"),
+    )
+
+
+def _from_metadata_text(text: str, source: str) -> ProjectMeta:
+    msg = email.message_from_string(text)
+    return ProjectMeta(
+        source=source,
+        classifiers=[v for v in msg.get_all("Classifier", []) or []],
+        requires_python=msg.get("Requires-Python"),
+    )
+
+
+def from_wheel(path: Path) -> Optional[ProjectMeta]:
+    try:
+        with zipfile.ZipFile(path) as zf:
+            names = [n for n in zf.namelist() if n.endswith(".dist-info/METADATA")]
+            if not names:
+                return None
+            text = zf.read(names[0]).decode("utf-8", "replace")
+    except (zipfile.BadZipFile, OSError):
+        return None
+    return _from_metadata_text(text, str(path))
+
+
+def resolve_meta(project_dir: Path, dist_dir: Path) -> Optional[ProjectMeta]:
+    """Prefer pyproject.toml (the source of truth an author edits), then fall
+    back to a built wheel's METADATA."""
+    pp = from_pyproject(project_dir / "pyproject.toml")
+    if pp is not None:
+        return pp
+    if dist_dir.is_dir():
+        for whl in sorted(dist_dir.glob("*.whl")):
+            m = from_wheel(whl)
+            if m is not None:
+                return m
+    return None

ft_readiness/pytest_plugin.py

@@ -0,0 +1,86 @@
+"""pytest plugin: assert your extension modules keep the GIL disabled on a
+free-threaded build.
+
+Usage (in CI, ideally on a 3.14t interpreter)::
+
+    pytest --ft-import mypkg._core --ft-import mypkg._fast
+
+Each module is imported in a fresh subprocess; a module that re-enables the GIL
+fails. On a non-free-threaded interpreter every check is skipped, so the same
+command is safe to run across your whole CI matrix.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from .runtime import check_import, is_free_threaded
+
+
+def pytest_addoption(parser):
+    group = parser.getgroup("ft-readiness")
+    group.addoption(
+        "--ft-import",
+        action="append",
+        dest="ft_import",
+        default=[],
+        metavar="MODULE",
+        help="import MODULE on a free-threaded build and fail if it re-enables "
+             "the GIL (repeatable, or comma-separated)",
+    )
+
+
+def _requested_modules(config):
+    mods = []
+    for it in config.getoption("ft_import") or []:
+        mods.extend(m.strip() for m in it.split(",") if m.strip())
+    return mods
+
+
+class FTImportItem(pytest.Item):
+    def __init__(self, *, module, **kwargs):
+        super().__init__(**kwargs)
+        self.module = module
+
+    def runtest(self):
+        if not is_free_threaded():
+            pytest.skip("interpreter is not a free-threaded build")
+        result = check_import(self.module)
+        if result.status == "gil_reenabled":
+            raise FTGilReenabled(self.module, result.detail)
+        if result.status == "import_error":
+            raise AssertionError(
+                f"could not import {self.module!r} for the GIL check: "
+                f"{result.detail}"
+            )
+
+    def repr_failure(self, excinfo):
+        if isinstance(excinfo.value, FTGilReenabled):
+            return str(excinfo.value)
+        return super().repr_failure(excinfo)
+
+    def reportinfo(self):
+        return self.path, 0, f"ft-gil import check: {self.module}"
+
+
+class FTGilReenabled(Exception):
+    def __init__(self, module, detail):
+        self.module = module
+        self.detail = detail
+        super().__init__(
+            f"Importing {module!r} re-enabled the GIL on a free-threaded build: "
+            f"{detail}\n"
+            "Add Py_mod_gil = Py_MOD_GIL_NOT_USED (multi-phase init) or call "
+            "PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED) (single-phase) in "
+            "the C extension, then rebuild."
+        )
+
+
+def pytest_collection_modifyitems(session, config, items):
+    modules = _requested_modules(config)
+    for module in modules:
+        items.append(
+            FTImportItem.from_parent(
+                session, name=f"ft-gil::{module}", module=module
+            )
+        )

ft_readiness/runtime.py

@@ -0,0 +1,102 @@
+"""Runtime check: import a module on a free-threaded interpreter and verify it
+did NOT force the GIL back on.
+
+An extension that omits the ``Py_mod_gil = Py_MOD_GIL_NOT_USED`` slot (or the
+``PyUnstable_Module_SetGIL`` call for single-phase init) makes CPython
+re-enable the GIL at import and print a warning. Every free-threaded user then
+silently loses parallelism. This can only be observed at runtime, on a
+free-threaded build, so it is separate from the static wheel/classifier checks.
+
+Each module is imported in a fresh subprocess so the GIL-state transition is
+attributable to that one module (the GIL, once re-enabled, stays on for the
+process).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import sysconfig
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+def is_free_threaded(executable: Optional[str] = None) -> bool:
+    """Whether the given interpreter (default: current) is a free-threaded build."""
+    if executable is None or executable == sys.executable:
+        return bool(sysconfig.get_config_var("Py_GIL_DISABLED"))
+    try:
+        out = subprocess.run(
+            [executable, "-c", "import sysconfig,sys;"
+             "sys.stdout.write('1' if sysconfig.get_config_var('Py_GIL_DISABLED') else '0')"],
+            capture_output=True, text=True, timeout=30,
+        )
+        return out.stdout.strip() == "1"
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+@dataclass
+class ImportResult:
+    module: str
+    status: str  # "ok" | "gil_reenabled" | "import_error" | "skipped"
+    detail: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status in ("ok", "skipped")
+
+
+# Runs inside the target interpreter. Prints one JSON line.
+_PROBE = r"""
+import json, sys, warnings, importlib
+mod = sys.argv[1]
+before = sys._is_gil_enabled()
+caught = []
+try:
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        importlib.import_module(mod)
+        caught = [str(x.message) for x in w]
+except BaseException as e:
+    print(json.dumps({"status": "import_error", "detail": f"{type(e).__name__}: {e}"}))
+    sys.exit(0)
+after = sys._is_gil_enabled()
+gil_msg = next((m for m in caught if "GIL" in m or "global interpreter lock" in m), "")
+if (after and not before) or gil_msg:
+    print(json.dumps({"status": "gil_reenabled",
+                      "detail": gil_msg or "GIL was enabled during import"}))
+else:
+    print(json.dumps({"status": "ok", "detail": ""}))
+"""
+
+
+def check_import(module: str, executable: Optional[str] = None,
+                 timeout: float = 60.0) -> ImportResult:
+    exe = executable or sys.executable
+    if not is_free_threaded(exe):
+        return ImportResult(module, "skipped",
+                            "interpreter is not a free-threaded build")
+    try:
+        proc = subprocess.run(
+            [exe, "-c", _PROBE, module],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        return ImportResult(module, "import_error", "import timed out")
+    line = (proc.stdout or "").strip().splitlines()
+    if not line:
+        return ImportResult(module, "import_error",
+                            (proc.stderr or "no output from probe").strip()[:500])
+    try:
+        data = json.loads(line[-1])
+    except json.JSONDecodeError:
+        return ImportResult(module, "import_error", line[-1][:500])
+    return ImportResult(module, data.get("status", "import_error"),
+                        data.get("detail", ""))
+
+
+def check_imports(modules: List[str], executable: Optional[str] = None,
+                  timeout: float = 60.0) -> List[ImportResult]:
+    return [check_import(m, executable, timeout) for m in modules]

ft_readiness/wheels.py

@@ -0,0 +1,98 @@
+"""Parse wheel/sdist filenames in a dist directory and classify their tags.
+
+A wheel filename is:
+    {name}-{version}(-{build})?-{pytag}-{abitag}-{plattag}.whl
+where each tag field may be a compressed set joined by '.'.
+See https://packaging.python.org/en/latest/specifications/binary-distribution-format/
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Set
+
+# A free-threaded CPython ABI tag looks like cp314t, cp315t, ...
+_FT_ABI_RE = re.compile(r"^cp\d{2,}t$")
+# A versioned CPython ABI tag (non-FT) looks like cp313, cp314, cp39, ...
+_CP_ABI_RE = re.compile(r"^cp\d{2,}$")
+
+
+@dataclass
+class Wheel:
+    filename: str
+    name: str
+    version: str
+    pytags: Set[str] = field(default_factory=set)
+    abitags: Set[str] = field(default_factory=set)
+    plattags: Set[str] = field(default_factory=set)
+
+    @property
+    def is_freethreaded(self) -> bool:
+        return any(_FT_ABI_RE.match(t) for t in self.abitags) or any(
+            _FT_ABI_RE.match(t) for t in self.pytags
+        )
+
+    @property
+    def is_abi3(self) -> bool:
+        return "abi3" in self.abitags
+
+    @property
+    def is_pure_python(self) -> bool:
+        # abi 'none' + platform 'any' => no compiled extension in this wheel
+        return self.abitags == {"none"} and self.plattags == {"any"}
+
+    @property
+    def is_extension(self) -> bool:
+        # Ships a compiled extension: has a real platform tag (not 'any')
+        return self.plattags != {"any"} and "any" not in self.plattags
+
+    @property
+    def cpython_versions(self) -> Set[str]:
+        """Extract the numeric CPython versions this wheel's tags name (e.g. {'314'})."""
+        out: Set[str] = set()
+        for t in list(self.abitags) + list(self.pytags):
+            m = re.match(r"^cp(\d{2,})t?$", t)
+            if m:
+                out.add(m.group(1))
+        return out
+
+
+def parse_wheel_filename(filename: str) -> Wheel | None:
+    stem = filename[:-4] if filename.endswith(".whl") else filename
+    parts = stem.split("-")
+    if len(parts) < 5:
+        return None
+    # last three fields are the tag triple; name is parts[0], version parts[1],
+    # anything between version and the tag triple is the optional build tag.
+    plat = parts[-1]
+    abi = parts[-2]
+    py = parts[-3]
+    name = parts[0]
+    version = parts[1]
+    return Wheel(
+        filename=filename,
+        name=name,
+        version=version,
+        pytags=set(py.split(".")),
+        abitags=set(abi.split(".")),
+        plattags=set(plat.split(".")),
+    )
+
+
+def collect_wheels(dist_dir: Path) -> List[Wheel]:
+    wheels: List[Wheel] = []
+    if not dist_dir.is_dir():
+        return wheels
+    for p in sorted(dist_dir.glob("*.whl")):
+        w = parse_wheel_filename(p.name)
+        if w is not None:
+            wheels.append(w)
+    return wheels
+
+
+def find_sdists(dist_dir: Path) -> List[str]:
+    if not dist_dir.is_dir():
+        return []
+    return sorted(p.name for p in dist_dir.glob("*.tar.gz"))

ft_readiness-0.1.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ft-readiness
+Version: 0.1.0
+Summary: Author-side pre-publish gate for free-threaded Python (3.14t): catch the silently re-enabled GIL, a missing cp314t wheel, and a stale Free Threading trove classifier before you ship.
+Project-URL: Homepage, https://github.com/fernforge/ft-readiness
+Project-URL: Source, https://github.com/fernforge/ft-readiness
+Project-URL: Issues, https://github.com/fernforge/ft-readiness/issues
+Author: fernforge
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ci,cp314t,free-threaded,free-threading,gil,linter,packaging,pytest,python-3.14,wheels
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Free Threading :: 3 - Stable
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Requires-Dist: packaging>=21.0
+Provides-Extra: tomli
+Requires-Dist: tomli>=1.1.0; (python_version < '3.11') and extra == 'tomli'
+Description-Content-Type: text/markdown
+
+# ft-readiness
+
+Catch a broken free-threading build before you publish it, not after your users file the bug.
+
+Python 3.14 made free-threading officially supported. If you ship a C extension there are three ways to break it silently — and none of them fail your build:
+
+1. Your extension omits the `Py_mod_gil` slot. CPython **re-enables the GIL** the moment someone imports your module on a free-threaded interpreter. Every 3.14t user loses parallelism; the only signal is a warning buried in stderr.
+2. You ship wheels for regular CPython but **no `cp314t` wheel**. Free-threaded users fall back to an sdist build, or to the GIL build, with nothing telling you they got the slow path.
+3. Your `Free Threading ::` trove classifier says one thing and your wheels say another — you advertise support you didn't ship, or ship support nobody can discover on PyPI.
+
+`ft-readiness` is a pre-publish gate for all three. Run it in CI after `python -m build`; it exits non-zero when your artifacts and your claims don't line up.
+
+```console
+$ ft-readiness .
+✗ FT001 [error] Declares 'Programming Language :: Python :: Free Threading :: 2 - Beta' but ships no free-threaded (cp3XXt) wheel for its compiled extension.
+    → Build a cp3XXt wheel (cibuildwheel with CIBW_ENABLE=cpython-freethreading, or CPython 3.14t + your build backend), or drop the Free Threading classifier until you ship one.
+! FT004 [warning] Ships abi3 (limited-API) wheels but no cp3XXt wheel. The stable ABI is unsupported on the free-threaded build, so abi3 wheels do NOT cover 3.14t users.
+    → Build a separate free-threaded wheel; you can keep abi3 for the GIL build (e.g. py_limited_api=not sysconfig.get_config_var('Py_GIL_DISABLED')).
+
+ft-readiness 0.1.0: 1 error(s), 1 warning(s).
+```
+
+## Install
+
+```console
+pip install ft-readiness
+```
+
+Python 3.9+. Pure Python, one runtime dependency (`packaging`).
+
+## What it checks
+
+The static checks read your built `dist/` and your `pyproject.toml` (or a wheel's `METADATA`). They run on any interpreter — you do **not** need a free-threaded build to run them.
+
+| Code | Level | Fires when |
+|------|-------|-----------|
+| FT001 | error | A `Free Threading ::` classifier is declared, the package has a compiled extension, but no `cp3XXt` wheel ships. You advertise support your artifacts don't deliver. |
+| FT002 | warning | A `cp3XXt` wheel ships but no `Free Threading ::` classifier is declared. Support is real but undiscoverable on PyPI. |
+| FT003 | warning | The package ships compiled-extension wheels but none for free-threaded Python. The silent missing-wheel case. |
+| FT004 | warning | Only `abi3` (limited-API) wheels ship, no `cp3XXt`. The stable ABI is unsupported on the free-threaded build, so abi3 does not cover 3.14t. |
+| FT005 | warning | The package advertises free-threading but `requires-python` excludes the versions (3.13+) that have a free-threaded build. |
+| FT006 | info | A pure-Python package claims `3 - Stable`/`4 - Resilient` — a reminder to back the claim with thread-safety tests. |
+
+The **runtime** check is the one that catches a re-enabled GIL, and it needs a free-threaded interpreter (it imports your module and watches the GIL state):
+
+| Code | Level | Fires when |
+|------|-------|-----------|
+| FT010 | error | Importing a module you named re-enabled the GIL — the `Py_mod_gil` slot is missing. |
+| FT011 | warning | A module named for the runtime check couldn't be imported. |
+
+```console
+# on a python3.14t interpreter, in CI:
+ft-readiness . --import mypkg._core --import mypkg._fast
+```
+
+On a non-free-threaded interpreter the `--import` checks are skipped with a note, so the same command is safe everywhere in your matrix.
+
+## pytest plugin
+
+If you already run a 3.14t leg in CI, wire the runtime check into pytest instead:
+
+```console
+pytest --ft-import mypkg._core --ft-import mypkg._fast
+```
+
+Each module is imported in a fresh subprocess and reported as its own test. On a non-free-threaded build the checks skip.
+
+## GitHub Action
+
+```yaml
+- uses: fernforge/ft-readiness@v1
+  with:
+    project: .        # optional, default '.'
+    strict: 'false'   # optional, treat warnings as errors
+```
+
+The action installs `ft-readiness` and runs the static checks against your `dist/`. Run it after your build step. For the runtime GIL check, add a job on `actions/setup-python` with a `3.14t` interpreter and call `ft-readiness --import ...` there.
+
+## Why these three failures and not others
+
+The GIL re-enable prints a warning, so an attentive porter can catch it by reading stderr. The two failures with *no* signal at all are the missing `cp314t` wheel and the classifier that doesn't match the wheels — a user just gets the slow path and never tells you. ft-readiness turns all three into a build failure you see before the release goes out.
+
+## Options
+
+```
+ft-readiness [PROJECT] [--dist DIR] [--import MODULE ...] [--strict] [--format text|json]
+```
+
+- `PROJECT` — project directory (default `.`); its `dist/` is inspected unless `--dist` is given.
+- `--dist DIR` — directory of built wheels/sdists.
+- `--import MODULE` — runtime GIL check for a module (repeatable or comma-separated).
+- `--strict` — exit 1 on warnings too.
+- `--format json` — machine-readable output for CI dashboards.
+
+Exit code is 1 if there are any errors (or any warnings under `--strict`), else 0.
+
+## License
+
+MIT

ft_readiness-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+ft_readiness/__init__.py,sha256=5E4CSl3RbGvkeMfJmPKZBwpCOjUixJtp1jV-WFr0OpI,157
+ft_readiness/checks.py,sha256=NjCaB-GR3hGN_7i8GASE92WRUWOWvL40bmZKOABuaxU,6938
+ft_readiness/cli.py,sha256=Ey24Ub3BOnJcD2Ps1gjrc2NqxWg6llJNtmn4WpS5ero,4838
+ft_readiness/metadata.py,sha256=pJcg8qTI0aTHawUNY1m7msuvbM_oiXEeCCVaK6n7TPg,2849
+ft_readiness/pytest_plugin.py,sha256=WF2P31ELWoCQohG-GwKDau2mJdi_Oejx6o_JcLurDHA,2716
+ft_readiness/runtime.py,sha256=AcOOkeaf6FfM0l6yru7jdh9pANQirMA1zhHfenMLdH8,3773
+ft_readiness/wheels.py,sha256=6jagzvigFRzfsI3PMeKjUa8I6mCcUXYdSuXRzGAmxUY,3036
+ft_readiness-0.1.0.dist-info/METADATA,sha256=aPt_wQOtCUaIORl6QyAPbF8g60mSYc31p7lcq8tfLSs,6938
+ft_readiness-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ft_readiness-0.1.0.dist-info/entry_points.txt,sha256=9jV5cRaZFZaMJZrXxz7jzztJjpW-2KuSzeHF8yQoHXk,109
+ft_readiness-0.1.0.dist-info/licenses/LICENSE,sha256=lw6uzq8NaSvXCl8vGq2IL9jyMWk4TjiYAz6VEm_Fphw,1066
+ft_readiness-0.1.0.dist-info/RECORD,,

ft_readiness-0.1.0.dist-info/WHEEL

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

ft_readiness-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+ft-readiness = ft_readiness.cli:main
+
+[pytest11]
+ft_readiness = ft_readiness.pytest_plugin

ft_readiness-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fernforge
+
+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.