parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/cli_help.py

@@ -0,0 +1,110 @@
+"""Static plain-text + JSON orientation for the `parse` CLI ("parse help").
+
+The command list is DERIVED from the live Click registry (so it can never list a
+command that doesn't exist or omit a new one); per-command ``requires_auth`` /
+``requires_init`` facts are read from attributes co-located on each ``Command``
+and OMITTED when unset (an honest "unknown", never a silent ``false``). All prose
+lives in module constants read by BOTH the text and JSON renderings, so the two
+cannot drift. ``parse help`` ORIENTS (what commands exist, the workflow, how to
+auth) and routes diagnosis to ``parse doctor`` — it has no state detection of its
+own.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Tuple
+
+import click
+
+from parse_sdk.config import CREDENTIALS_PATH, DEFAULT_BASE_URL
+
+# The happy-path workflow, in order. Other registered commands (whoami, clean,
+# doctor, add, search, remove, …) are listed after, alphabetically — the list
+# itself comes from the registry, so nothing goes stale.
+_ORDER = ["login", "init", "list", "sync"]
+
+_AGENT_MODES = {
+    "json": "add --json to list/sync/whoami/doctor for stable machine output; prefer it",
+    "check": "`uv run parse sync --check` is a CI dry-run (render + gate, no promote, "
+             "exit 1 on findings)",
+}
+_AUTH_HOWTO = (
+    "Create an API key in the Parse dashboard, then `uv run parse login` "
+    "(or `uv run parse login --web` for browser OAuth, or set PARSE_API_KEY)."
+)
+_DIAGNOSE = (
+    "Something not working? `uv run parse doctor` diagnoses (and `--fix` repairs) "
+    "this project's install."
+)
+
+
+def _rows(group: "click.Group") -> List[Tuple[str, str]]:
+    cmds = group.commands
+    ordered = [n for n in _ORDER if n in cmds] + sorted(n for n in cmds if n not in _ORDER)
+    return [(n, cmds[n].get_short_help_str(limit=80)) for n in ordered]
+
+
+def _facts(cmd: "click.Command") -> Dict[str, bool]:
+    """Per-command auth/init facts, read from attrs set at the command's
+    definition. Absent attr → omitted key (never a wrong ``false``)."""
+    out: Dict[str, bool] = {}
+    for attr in ("requires_auth", "requires_init"):
+        v = getattr(cmd, attr, None)
+        if v is not None:
+            out[attr] = bool(v)
+    return out
+
+
+def render_overview(group: "click.Group", *, as_json: bool = False) -> str:
+    rows = _rows(group)
+
+    if as_json:
+        payload: Dict[str, Any] = {
+            "workflow": [n for n in _ORDER if n in group.commands],
+            "commands": [
+                {"name": n, "summary": s, **_facts(group.commands[n])} for n, s in rows
+            ],
+            "agent_modes": _AGENT_MODES,
+            "settings": {
+                "env": ["PARSE_API_KEY", "PARSE_API_BASE_URL"],
+                "credentials_path": str(CREDENTIALS_PATH),
+                "base_url_default": DEFAULT_BASE_URL,
+                "auth": _AUTH_HOWTO,
+            },
+            "diagnose": _DIAGNOSE,
+            "pointers": {
+                "root_pointer": "parse_apis/AGENTS.md",
+                "deep_index": "parse_apis/src/parse_apis/CLAUDE.md",
+            },
+        }
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    workflow = [(n, s) for n, s in rows if n in _ORDER]
+    other = [(n, s) for n, s in rows if n not in _ORDER]
+    lines = [
+        "Parse SDK — generate typed Python clients for the APIs your key can call.",
+        "",
+        "Workflow (run in order):",
+    ]
+    lines += [f"  uv run parse {n:<7} {s}" for n, s in workflow]
+    if other:
+        lines.append(
+            "  Other: " + ", ".join(n for n, _ in other) + "  (uv run parse <cmd> --help)"
+        )
+    lines += [
+        "",
+        "Then: from parse_apis.<slug> import <Root>  "
+        "(per-slug imports raise ModuleNotFoundError until `uv run parse sync`).",
+        "",
+        "Authentication:",
+        "  " + _AUTH_HOWTO,
+        f"  (saved to {CREDENTIALS_PATH}; default base URL {DEFAULT_BASE_URL}).",
+        "",
+        _DIAGNOSE,
+        "",
+        f"Agent mode: {_AGENT_MODES['json']}; {_AGENT_MODES['check']}.",
+        "",
+        "More: `uv run parse <command> --help`; after sync, "
+        "`parse_apis/src/parse_apis/CLAUDE.md` for conventions + the API index.",
+    ]
+    return "\n".join(lines)

parse_sdk/codegen_reconcile.py

@@ -0,0 +1,157 @@
+"""Sample-vs-type reconciliation — the verifier half of codegen.
+
+Kept OUT of ``_normalize_schema`` (the naming-consistency pass): a contradicted
+``resources[*].fields[*].type`` is reconciled against the captured
+``return_schema.sample`` and floored to the sample-gate's ``Dict[str, Any]`` form
+(copy-on-write, so the caller's stored spec stays raw). ``_normalize_schema``
+calls ``reconcile_resources`` as a single named pass; the complete-time persist
+(``sdk_field_gate``) reuses the SAME path, so build-time and serving-time agree.
+
+Imports ``_extract_field_spec``/``_camel`` from ``codegen_v2`` — this module is
+imported lazily (at call time, from inside ``_normalize_schema``), after
+``codegen_v2`` is fully loaded, so the back-import is cycle-safe.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Set
+
+from parse_sdk import sample_gate as _sample_gate
+from parse_sdk._labels import unwrap_label
+from parse_sdk._runtime import unwrap_scraper_envelope
+from parse_sdk.codegen_v2 import _camel, _extract_field_spec
+
+
+def _returns_leaf(returns: Any) -> Optional[str]:
+    """The leaf resource name an operation ``returns`` names — unwrapping
+    ``List[X]`` / ``Optional[X]`` / ``_Paginator[X]`` (repeatedly) down to ``X``;
+    None for a non-string label.
+
+    Used for the EXACT returns-match in sample projection. A substring match
+    (``'Game' in 'List[GameSummary]'``) would bleed one resource's payload into
+    another and corrupt its key field to ``Any`` — so we compare leaf-to-name."""
+    return unwrap_label(returns) if isinstance(returns, str) else None
+
+
+def _iter_operations(rspec: Dict[str, Any]):
+    """Every operation a resource declares — its own ``operations`` block AND
+    each ``sub_resources[*].operations`` block — so an op returning ANOTHER
+    resource (``Post.comments.list -> List[Comment]``) is not missed."""
+    ops = rspec.get("operations")
+    if isinstance(ops, dict):
+        yield from (op for op in ops.values() if isinstance(op, dict))
+    subs = rspec.get("sub_resources")
+    if isinstance(subs, dict):
+        for sub in subs.values():
+            if isinstance(sub, dict) and isinstance(sub.get("operations"), dict):
+                yield from (op for op in sub["operations"].values() if isinstance(op, dict))
+
+
+def project_field_samples(schema: Dict[str, Any]) -> Dict[str, Dict[str, List[Any]]]:
+    """``resource_name → field_name → pooled OBSERVED field values``.
+
+    Buckets every operation (across ALL resources' own + ``sub_resources`` blocks)
+    by its EXACT returns-leaf, so a resource is fed the sample of whatever
+    operation returns it — including a sub-resource/cross-resource op, not just
+    its own block (a resource without its own op but returned by one IS an
+    own-endpoint resource per the projection contract). Then: resolve the op's
+    endpoint → ``return_schema.sample`` → envelope descent FIRST, then
+    ``items_path`` (both branches) → record each declared field's value by its
+    WIRE key (``alias_from or field_name``), distinguishing a missing key
+    (contributes nothing) from an explicit null. A resource no operation returns
+    (truly nested-only / field-type-only) gets no sample → kept verbatim. Pure:
+    reads value-types only, never emits the sample into output."""
+    resources = schema.get("resources") or {}
+    endpoints_by_name = {
+        ep["name"]: ep
+        for ep in (schema.get("endpoints") or [])
+        if isinstance(ep, dict) and isinstance(ep.get("name"), str)
+    }
+    wire_keys = {
+        rname: {fname: (_extract_field_spec(fval)[2] or fname)
+                for fname, fval in rspec["fields"].items()}
+        for rname, rspec in resources.items()
+        if isinstance(rspec, dict) and isinstance(rspec.get("fields"), dict)
+    }
+    # Match an op's returns-leaf to a resource by CANONICAL (``_camel``) name —
+    # resource keys may be snake/lower (``item``) while ``returns`` is the
+    # PascalCase form (``Item``); compare both canonicalized, exactly as the
+    # original per-resource ``_camel(leaf) == _camel(rname)`` match did.
+    # Camel-colliding raw keys ('a_b'/'aB' → 'AB') are SUPPORTED by codegen
+    # (the allocator suffixes the second class), but a camel-keyed sample match
+    # cannot disambiguate them — first-wins would route BOTH resources' samples
+    # into one pool (cross-resource contamination) and starve the loser. Drop
+    # the camel route for an ambiguous canonical instead: both resources get no
+    # projected sample and are kept verbatim (the no-sample path).
+    canon_to_raw: Dict[str, str] = {}
+    _ambiguous: Set[str] = set()
+    for rname in wire_keys:
+        canon = _camel(rname)
+        if canon in canon_to_raw or canon in _ambiguous:
+            _ambiguous.add(canon)
+            canon_to_raw.pop(canon, None)
+            continue
+        canon_to_raw[canon] = rname
+    observed: Dict[str, Dict[str, List[Any]]] = {}
+    for owner in resources.values():
+        if not isinstance(owner, dict):
+            continue
+        for op in _iter_operations(owner):
+            raw = canon_to_raw.get(_camel(_returns_leaf(op.get("returns")) or ""))
+            if raw is None:
+                continue  # feed only a MODELED resource; exact returns-match → no bleed
+            ep = endpoints_by_name.get(op.get("endpoint"))
+            if not isinstance(ep, dict):
+                continue
+            rs = ep.get("return_schema")
+            sample = rs.get("sample") if isinstance(rs, dict) else None
+            if sample is None:
+                continue
+            body = unwrap_scraper_envelope(sample)
+            pg = op.get("pagination")
+            items_path = pg.get("items_path") if isinstance(pg, dict) else None
+            if items_path:
+                items = body.get(items_path) if isinstance(body, dict) else None
+                records = items if isinstance(items, list) else []
+            else:
+                records = [body]  # point lookup: the unwrapped body IS the object
+            per_field = observed.setdefault(raw, {})
+            for rec in records:
+                if not isinstance(rec, dict):
+                    continue
+                for fname, wire in wire_keys[raw].items():
+                    if wire in rec:
+                        per_field.setdefault(fname, []).append(rec[wire])
+    return {rname: per_field for rname, per_field in observed.items() if per_field}
+
+
+def reconcile_resources(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Floor every contradicted ``resources[*].fields[*].type`` to the sample-
+    gate's ``Dict[str, Any]`` form and return the (copy-on-write) resources dict
+    for assignment onto ``schema``. The key field and out-of-scope/CONFIRMED
+    fields are never rewritten; both bare-string and FieldSpec-dict field shapes
+    are handled. Pure CoW — the caller's stored ``request_flow`` stays raw."""
+    observed = project_field_samples(schema)
+    resources = dict(schema.get("resources") or {})
+    if not observed:
+        return resources
+    for rname, rspec in resources.items():
+        if not isinstance(rspec, dict):
+            continue
+        obs_r = observed.get(rname)
+        if not obs_r:
+            continue
+        key_field = rspec.get("keyed_by")
+        fields = dict(rspec.get("fields") or {})
+        changed = False
+        for fname, fval in fields.items():
+            declared, _enum, _alias = _extract_field_spec(fval)
+            verdict = _sample_gate.gate_field(
+                declared, obs_r.get(fname), is_key=(fname == key_field))
+            if verdict.status == "CONTRADICTED" and verdict.repaired_label:
+                fields[fname] = (
+                    {**fval, "type": verdict.repaired_label}
+                    if isinstance(fval, dict) else verdict.repaired_label)
+                changed = True
+        if changed:
+            resources[rname] = {**rspec, "fields": fields}
+    return resources