parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/doctor.py

@@ -0,0 +1,348 @@
+"""`parse doctor` — diagnose a project's Parse SDK install and explain/fix hiccups.
+
+Read-only DETECTION lives here: ``run_diagnostics`` is a pure function over the
+project paths + the resolved ``Config`` + an injectable import-probe, so it is
+unit-testable without a real venv or network. The CLI command
+(``parse_sdk.cli.doctor``) formats the findings, drives ``--fix``, and owns the
+side-effecting remediations (the helpers it already has: ``_ensure_consumer_pyproject``,
+``uv sync``).
+
+The single most valuable check is the project-interpreter import probe: a fresh
+``parse init`` can leave ``parse_sdk`` unresolvable in the consumer venv (pre-PyPI,
+or a wrong selected interpreter), and that is exactly what silently kills editor
+autocomplete on the generated modules (they ``from parse_sdk._runtime import …``).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import urllib.parse
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # 3.10 — tomllib landed in 3.11; tomli is its backport
+    import tomli as tomllib  # type: ignore[no-redef]
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Dict, List, Optional
+
+from parse_sdk._sync import _find_pin
+from parse_sdk.config import (
+    CANONICAL_HOST, Config, _host_is_trusted, _read_credentials_file,
+    extra_trusted_hosts,
+)
+
+# Finding levels (ordered by severity for sorting/summary).
+OK = "ok"
+WARN = "warn"
+ERROR = "error"
+_SEVERITY = {OK: 0, WARN: 1, ERROR: 2}
+
+
+@dataclass
+class Finding:
+    """One diagnostic result. ``kind`` tags how ``parse doctor --fix`` may act:
+    ``manual`` (show the fix, don't auto-run), ``record_deps`` (re-record the
+    consumer pyproject deps/source), ``uv_sync`` (run ``uv sync``), ``sync``
+    (needs a network ``parse sync`` regen — shown, never auto-run), ``login``,
+    ``init``."""
+    level: str
+    title: str
+    detail: str = ""
+    fix: str = ""
+    kind: str = "manual"
+
+    def as_dict(self) -> dict:
+        return {"level": self.level, "title": self.title,
+                "detail": self.detail, "fix": self.fix, "kind": self.kind}
+
+
+# --------------------------------------------------------------------------- #
+# pyproject parsing (self-contained — doctor is imported BY cli, so it must not
+# import back from cli to reach _dep_present; this mirrors that canonicalization)
+# --------------------------------------------------------------------------- #
+
+def _canonical(name: str) -> str:
+    """PEP 503 distribution-name canonicalization (``Parse_SDK`` → ``parse-sdk``)."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def _declared_project_deps(text: str) -> set:
+    """Canonicalized names in ``[project].dependencies`` (empty set on bad TOML)."""
+    try:
+        deps = tomllib.loads(text).get("project", {}).get("dependencies", [])
+    except Exception:
+        return set()
+    out: set = set()
+    if isinstance(deps, list):
+        for d in deps:
+            if isinstance(d, str):
+                m = re.match(r"\s*([A-Za-z0-9][A-Za-z0-9._-]*)", d)
+                if m:
+                    out.add(_canonical(m.group(1)))
+    return out
+
+
+def _uv_sources(text: str) -> dict:
+    try:
+        return tomllib.loads(text).get("tool", {}).get("uv", {}).get("sources", {}) or {}
+    except Exception:
+        return {}
+
+
+def _hostname(url: str) -> str:
+    try:
+        return (urllib.parse.urlsplit(url).hostname or "").rstrip(".")
+    except ValueError:
+        return ""
+
+
+# --------------------------------------------------------------------------- #
+# the project-interpreter import probe (the autocomplete predictor)
+# --------------------------------------------------------------------------- #
+
+_PROBE = (
+    "import json,sys\n"
+    "r={}\n"
+    "for m in ('parse_sdk','parse_apis'):\n"
+    "    try:\n"
+    "        __import__(m)\n"
+    "        r[m]=True\n"
+    "    except Exception as e:\n"
+    "        r[m]=type(e).__name__+': '+str(e)\n"
+    "sys.stdout.write(json.dumps(r))\n"
+)
+
+
+def _venv_python(project: Path) -> Optional[Path]:
+    """The project's ``.venv`` interpreter (uv's convention), or None.
+
+    Only ``.venv`` is probed — a differently-named or external interpreter
+    (conda, pyenv) is the user's to point their editor at; doctor degrades to a
+    WARN rather than guessing wrong."""
+    for rel in (
+        Path(".venv") / "bin" / "python",
+        Path(".venv") / "bin" / "python3",
+        Path(".venv") / "Scripts" / "python.exe",  # Windows
+    ):
+        p = project / rel
+        if p.exists():
+            return p
+    return None
+
+
+def probe_project_imports(project: Path) -> Dict[str, object]:
+    """Try ``import parse_sdk`` / ``import parse_apis`` in the project's ``.venv``.
+
+    Returns ``{"_venv": <str|None>, "parse_sdk": True|errstr, "parse_apis": ...}``;
+    ``{"_venv": None}`` when no ``.venv`` exists; ``{"_venv": str, "_error": ...}``
+    if the probe subprocess itself fails. Bounded so a wedged interpreter can't
+    hang the command."""
+    py = _venv_python(project)
+    if py is None:
+        return {"_venv": None}
+    try:
+        r = subprocess.run([str(py), "-c", _PROBE],
+                           capture_output=True, text=True, timeout=60)
+    except (subprocess.TimeoutExpired, OSError) as e:
+        return {"_venv": str(py), "_error": str(e)}
+    data: Dict[str, object]
+    try:
+        data = json.loads(r.stdout or "{}")
+    except ValueError:
+        data = {"_error": (r.stderr or r.stdout or "probe produced no output").strip()[:300]}
+    if not isinstance(data, dict):  # defensive: a non-object body is unusable
+        data = {"_error": "import probe returned non-object JSON"}
+    data["_venv"] = str(py)
+    return data
+
+
+# --------------------------------------------------------------------------- #
+# the checks
+# --------------------------------------------------------------------------- #
+
+def run_diagnostics(
+    project: Path,
+    cfg: Config,
+    *,
+    version: str,
+    probe: Optional[Callable[[Path], Dict[str, object]]] = None,
+) -> List[Finding]:
+    """All diagnostics for ``project``, in display order. Pure except for the
+    injectable ``probe`` (defaults to the real ``.venv`` subprocess)."""
+    probe = probe or probe_project_imports
+    root = project / "parse_apis"
+    pkg = root / "src" / "parse_apis"
+    consumer = project / "pyproject.toml"
+    initialized = (root / "pyproject.toml").exists() and (pkg / "__init__.py").exists()
+
+    findings: List[Finding] = []
+
+    # 1. uv on PATH (the documented install flow runs `uv sync` / `uv run parse`).
+    if shutil.which("uv") is None:
+        findings.append(Finding(
+            WARN, "uv is not on PATH",
+            "The Parse SDK install flow uses uv (`uv sync`, `uv run parse`).",
+            fix="Install uv (https://docs.astral.sh/uv/), or manage the venv with pip yourself."))
+    else:
+        findings.append(Finding(OK, "uv is installed"))
+
+    # 2. a consumer project must exist before anything else is meaningful.
+    if not consumer.exists():
+        findings.append(Finding(
+            ERROR, "no pyproject.toml in the project root",
+            f"Looked in {project}. The Parse SDK installs into a uv/pip project here.",
+            fix="Run `uv init` (or add a pyproject.toml), then `parse init`.", kind="init"))
+        return findings
+
+    # 3. initialized scaffold?
+    if not initialized:
+        findings.append(Finding(
+            ERROR, "parse_apis is not initialized",
+            f"No initialized package at {pkg}.",
+            fix="Run `parse init` from the project root.", kind="init"))
+        findings.extend(_credential_findings(cfg))  # let the user fix both at once
+        return findings
+    findings.append(Finding(OK, "parse_apis package is initialized"))
+
+    findings.extend(_consumer_dep_findings(consumer))
+    findings.extend(_pin_findings(root, version))
+    findings.extend(_import_findings(project, probe))
+    findings.extend(_credential_findings(cfg))
+    return findings
+
+
+def _consumer_dep_findings(consumer: Path) -> List[Finding]:
+    out: List[Finding] = []
+    try:
+        text = consumer.read_text()
+    except OSError as e:
+        return [Finding(WARN, "couldn't read the project pyproject.toml", str(e))]
+    declared = _declared_project_deps(text)
+    missing = [d for d in ("parse-sdk", "parse-apis") if _canonical(d) not in declared]
+    if missing:
+        out.append(Finding(
+            WARN, f"missing dependency: {', '.join(missing)}",
+            "Your project's pyproject.toml doesn't declare these, so `uv sync` won't "
+            "install the SDK runtime and/or your typed clients.",
+            fix="parse doctor --fix   (re-records them), then `uv sync`", kind="record_deps"))
+    else:
+        out.append(Finding(OK, "parse-sdk + parse-apis are declared dependencies"))
+    if not any(_canonical(k) == "parse-apis" for k in _uv_sources(text)):
+        out.append(Finding(
+            WARN, "no editable source for parse-apis",
+            "[tool.uv.sources] doesn't point parse-apis at ./parse_apis, so uv can't "
+            "resolve your local generated package (it is never published).",
+            fix="parse doctor --fix   (adds the editable source), then `uv sync`",
+            kind="record_deps"))
+    return out
+
+
+def _pin_findings(root: Path, version: str) -> List[Finding]:
+    out: List[Finding] = []
+    try:
+        text = (root / "pyproject.toml").read_text()
+    except OSError:
+        return out
+    m = _find_pin(text)
+    if m is None:
+        out.append(Finding(
+            WARN, "no parse-sdk pin in parse_apis/pyproject.toml",
+            "The generated package should pin the exact parse-sdk it was generated against.",
+            fix="parse sync   (re-stamps the pin)", kind="sync"))
+    elif m.group(1) != version:
+        out.append(Finding(
+            WARN, f"parse-sdk version skew (pinned {m.group(1)}, CLI is {version})",
+            "Your generated clients were built against a different parse_sdk runtime "
+            "than the one you're running — imports may break or types may drift.",
+            fix=f"parse sync   (regenerates against {version} and re-stamps the pin)",
+            kind="sync"))
+    else:
+        out.append(Finding(OK, f"parse-sdk pin matches the CLI ({version})"))
+    return out
+
+
+def _import_findings(project: Path, probe: Callable[[Path], Dict[str, object]]) -> List[Finding]:
+    data = probe(project)
+    venv = data.get("_venv")
+    if venv is None:
+        return [Finding(
+            WARN, "no .venv in the project (couldn't verify autocomplete)",
+            "Only ./.venv is probed for whether parse_sdk + parse_apis import. If you "
+            "use a different interpreter, ensure it has both installed.",
+            fix="uv sync   (creates ./.venv and installs the deps)", kind="uv_sync")]
+    if "_error" in data and "parse_sdk" not in data:
+        return [Finding(
+            WARN, "couldn't probe the project interpreter",
+            str(data.get("_error")), fix="uv sync", kind="uv_sync")]
+
+    sdk_ok = data.get("parse_sdk") is True
+    apis_ok = data.get("parse_apis") is True
+    if sdk_ok and apis_ok:
+        return [Finding(
+            OK, "project interpreter imports parse_sdk + parse_apis "
+                "(editor autocomplete will resolve)")]
+
+    out: List[Finding] = []
+    if not sdk_ok:
+        out.append(Finding(
+            ERROR, "the project interpreter can't import parse_sdk",
+            f"{data.get('parse_sdk')}\n"
+            "This is the usual cause of dead editor autocomplete: generated modules do "
+            "`from parse_sdk._runtime import …`, which can't resolve when parse_sdk isn't "
+            "installed in the selected interpreter.",
+            fix="uv sync   — if that fails with 'unsatisfiable'/'parse-sdk', the package "
+                "isn't on the index yet; install from a local checkout: "
+                "`uv add --editable /path/to/Parse-sdk`", kind="uv_sync"))
+    if not apis_ok:
+        out.append(Finding(
+            ERROR, "the project interpreter can't import parse_apis",
+            f"{data.get('parse_apis')}\n"
+            "Your typed clients aren't installed into the interpreter.",
+            fix="uv sync   (then `parse sync` if no clients are generated yet)",
+            kind="uv_sync"))
+    out.append(Finding(
+        WARN, "point your editor at the project interpreter",
+        f"VSCode: Cmd/Ctrl-Shift-P → 'Python: Select Interpreter' → {venv}, then reload."))
+    return out
+
+
+def _credential_findings(cfg: Config) -> List[Finding]:
+    host = _hostname(cfg.base_url)
+    cred = "API key" if cfg.api_key else ("web-login token" if cfg.access_token else None)
+    if cred:
+        if host in extra_trusted_hosts():
+            return [Finding(
+                WARN, f"{cred} is configured for {cfg.base_url} (opted in via PARSE_EXTRA_TRUSTED_HOSTS)",
+                "Trusted only because you opted this host in — fine for staging QA; unset "
+                "PARSE_EXTRA_TRUSTED_HOSTS for production.")]
+        return [Finding(OK, f"{cred} is configured for {cfg.base_url}")]
+    # No credential will be sent. Distinguish "none anywhere" from "withheld by host trust".
+    creds = _read_credentials_file()
+    _o = creds.get("oauth")
+    oauth = _o if isinstance(_o, dict) else {}
+    configured = bool(os.environ.get("PARSE_API_KEY") or creds.get("api_key")
+                      or os.environ.get("PARSE_ACCESS_TOKEN") or oauth.get("access_token"))
+    if configured and not _host_is_trusted(cfg.base_url):
+        return [Finding(
+            ERROR, f"credential withheld — {cfg.base_url} is not a trusted host",
+            f"A credential IS configured but won't be sent to {host or cfg.base_url}: it "
+            f"rides only to https://{CANONICAL_HOST}, loopback, or a PARSE_EXTRA_TRUSTED_HOSTS host.",
+            fix=f"For staging QA: export PARSE_EXTRA_TRUSTED_HOSTS={host}   "
+                f"(or point base_url at https://{CANONICAL_HOST})")]
+    return [Finding(
+        WARN, "no credentials configured",
+        "Commands that reach Parse (sync, list) need an API key or web login.",
+        fix="parse login   (API key)  ·  parse login --web   (browser)", kind="login")]
+
+
+def has_errors(findings: List[Finding]) -> bool:
+    return any(f.level == ERROR for f in findings)
+
+
+def sort_key(f: Finding) -> int:
+    """Sort errors first, then warnings, then OKs (stable within a level)."""
+    return -_SEVERITY.get(f.level, 0)

parse_sdk/migrate.py

@@ -0,0 +1,212 @@
+"""Flat-layout migration ownership detection.
+
+Before `parse init` creates the `src/` scaffold, it must decide whether an
+existing flat ``parse_apis/`` tree is Parse-owned generated output (safe to move
+aside to ``.parse/legacy-…``) or contains files a user hand-wrote (refuse the
+migration and list them, so we never silently destroy work).
+
+The decision is multi-signal on purpose. A single "this looks generated" guess
+is unsafe: a hand-written ``__init__.py`` or a JSON file that merely parses is
+NOT proof of Parse ownership. Each generated artifact carries an explicit
+provenance marker that codegen/docgen stamp at write time:
+
+  * slug ``__init__.py``     → the codegen banner (:data:`CODEGEN_BANNER`).
+  * ``.md`` / ``example.py`` → the docgen banner (``docgen.BANNER_TEXT``).
+  * root ``_manifest.json``  → a ``{uuid: slug}`` shape only codegen produces.
+
+Anything else under the tree is UNKNOWN and blocks the move. Interpreter debris
+(``__pycache__`` contents, ``*.pyc`` / ``*.pyo``) is ignored as debris — it is
+neither user work to preserve nor a provenance signal.
+
+The predicate functions are pure (string/dict in, ``bool`` out) so they can be
+reused and unit-tested in isolation. Classification only ever *reads* metadata
+and never follows symlinks: a symlink pointing into the tree must not be able to
+launder an outside file into "owned" (and following it risks cycles / escaping
+the tree entirely).
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, List
+
+from parse_sdk.docgen import BANNER_TEXT as _DOCGEN_BANNER
+
+# The marker codegen stamps into every generated slug ``__init__.py``. Kept as a
+# literal here (not imported from codegen) so this detector has no heavy import
+# dependency and the contract is visible at the migration boundary.
+CODEGEN_BANNER = "Auto-generated by `parse sync`. Do not edit by hand."
+
+# 8-4-4-4-12 hex, case-insensitive — the canonical UUID string shape codegen
+# uses for manifest keys. Anchored so a value merely *containing* a UUID does
+# not pass.
+_UUID_RE = re.compile(
+    r"\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\Z",
+    re.IGNORECASE,
+)
+
+# Docs / example artifacts docgen owns, by suffix.
+_DOC_SUFFIXES = frozenset({".md"})
+
+# Interpreter debris suffixes — bytecode caches, never source.
+_DEBRIS_SUFFIXES = frozenset({".pyc", ".pyo"})
+
+
+def is_generated_slug_init(text: str) -> bool:
+    """True iff ``text`` carries the codegen banner for a generated slug
+    ``__init__.py``. A banner-less ``__init__.py`` (hand-written package marker)
+    is intentionally NOT owned — provenance must be explicit."""
+    return isinstance(text, str) and CODEGEN_BANNER in text
+
+
+def is_generated_doc(text: str) -> bool:
+    """True iff ``text`` carries the docgen banner (README / index / example
+    body). Pure substring presence so it holds for the markdown-comment form
+    (``<!-- … -->``) and the python-comment form (``# …``) alike."""
+    return isinstance(text, str) and _DOCGEN_BANNER in text
+
+
+def is_generated_manifest(data: Any) -> bool:
+    """True iff ``data`` has the generated manifest shape: a non-empty ``dict``
+    mapping UUID-shaped string keys to non-empty string slug values.
+
+    Rejects the obvious impostors a plain ``json.loads`` would otherwise admit:
+    a ``list`` (e.g. ``["reddit"]``), an empty dict, a versioned config dict
+    (``{"version": 2, "data": []}``), or any entry whose key is not a UUID or
+    whose value is not a non-empty string. Every entry must conform — one bad
+    pair disqualifies the whole file (mixed shapes are not Parse output).
+    """
+    if not isinstance(data, dict) or not data:
+        return False
+    for key, value in data.items():
+        if not isinstance(key, str) or _UUID_RE.match(key) is None:
+            return False
+        if not isinstance(value, str) or not value.strip():
+            return False
+    return True
+
+
+@dataclass
+class FlatLayoutReport:
+    """The classification of an existing flat ``parse_apis/`` tree.
+
+    ``owned`` files are provably Parse-generated (safe to move aside), ``debris``
+    is interpreter cache to discard, and ``unknown`` is everything else — any
+    non-empty ``unknown`` blocks an automatic migration so user work is never
+    clobbered. Paths are absolute and sorted for stable reporting.
+    """
+
+    owned: List[Path] = field(default_factory=list)
+    unknown: List[Path] = field(default_factory=list)
+    debris: List[Path] = field(default_factory=list)
+
+    @property
+    def is_fully_owned(self) -> bool:
+        """True iff nothing is unknown — i.e. every non-debris file is provably
+        Parse-generated and the tree can be moved aside automatically."""
+        return not self.unknown
+
+
+def _is_debris(path: Path) -> bool:
+    """A bytecode cache file or anything inside a ``__pycache__`` directory."""
+    if path.suffix in _DEBRIS_SUFFIXES:
+        return True
+    return "__pycache__" in path.parts
+
+
+def _is_owned_file(path: Path, root: Path) -> bool:
+    """Whether a regular file is a provably Parse-generated artifact.
+
+    Reads the file's text/JSON to check the provenance marker. Returns ``False``
+    for anything unreadable or off-contract rather than guessing — an unknown
+    file blocks migration, which is the safe default.
+    """
+    # Name/suffix comparisons are case-folded: on case-insensitive filesystems
+    # (macOS/APFS, Windows) ``README.MD`` IS ``README.md`` and ``__INIT__.PY``
+    # is the same file codegen wrote in lowercase, so a banner-carrying generated
+    # file must not be misclassified as unknown merely on suffix casing. This
+    # only ever promotes an actually-banner'd file out of "unknown" — it never
+    # marks an unbanner'd file owned, so the safety filter's recall is preserved.
+    name = path.name.casefold()
+    suffix = path.suffix.casefold()
+
+    # Root-level generated manifest: shape check on parsed JSON.
+    if name == "_manifest.json" and path.parent == root:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return False
+        return is_generated_manifest(data)
+
+    # Slug package initializer: codegen banner required.
+    if name == "__init__.py":
+        try:
+            return is_generated_slug_init(path.read_text(encoding="utf-8"))
+        except OSError:
+            return False
+
+    # Docs / example artifacts: docgen banner required.
+    if suffix in _DOC_SUFFIXES or name == "example.py":
+        try:
+            return is_generated_doc(path.read_text(encoding="utf-8"))
+        except OSError:
+            return False
+
+    return False
+
+
+def classify_flat_layout(root: Path) -> FlatLayoutReport:
+    """Walk ``root`` and classify every file as owned / debris / unknown.
+
+    Directories themselves are not classified (only their files), so an empty
+    directory contributes nothing and a nested user package directory is judged
+    purely by the files it contains. Symlinks are never followed and never
+    counted as owned: a symlink (to a file or a directory, inside or outside the
+    tree) is treated as unknown so it can neither launder an external file into
+    "owned" nor cause us to walk outside ``root``.
+    """
+    root = Path(root)
+    report = FlatLayoutReport()
+    if not root.exists():
+        return report
+
+    # ``Path.walk`` with ``follow_symlinks=False`` (default) does not descend
+    # into symlinked directories; we additionally skip symlinked entries by hand
+    # so a symlink is never read or classified as owned.
+    for dirpath, dirnames, filenames in _walk(root):
+        for fname in filenames:
+            fpath = dirpath / fname
+            if fpath.is_symlink():
+                report.unknown.append(fpath)
+                continue
+            if _is_debris(fpath):
+                report.debris.append(fpath)
+            elif _is_owned_file(fpath, root):
+                report.owned.append(fpath)
+            else:
+                report.unknown.append(fpath)
+        # Surface symlinked subdirectories as unknown without descending — they
+        # are not Parse output and following them risks escaping the tree.
+        for dname in list(dirnames):
+            dpath = dirpath / dname
+            if dpath.is_symlink():
+                report.unknown.append(dpath)
+                dirnames.remove(dname)
+
+    report.owned.sort()
+    report.unknown.sort()
+    report.debris.sort()
+    return report
+
+
+def _walk(root: Path):
+    """``os.walk``-style traversal over ``root`` that does not follow symlinked
+    directories, yielding ``(Path, list[str], list[str])`` and allowing the
+    caller to prune ``dirnames`` in place. Kept separate so the classification
+    logic reads cleanly and the no-follow guarantee lives in one place."""
+    import os
+
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        yield Path(dirpath), dirnames, filenames