parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/scaffold.py

@@ -0,0 +1,273 @@
+"""The committed `parse_apis` scaffold + reserved-name vocabulary.
+
+`parse init` materializes a minimal, *committed* `parse_apis` distribution
+(`pyproject.toml`, `src/parse_apis/__init__.py`, `src/parse_apis/py.typed`) and
+`parse sync` fills the generated, gitignored payload around it. The scaffold
+carries no API key, no user id, and no per-key inventory, so it is safe to
+commit; only the generated slug packages / manifest / agent indexes are ignored.
+
+This module owns the static scaffold text and the set of names a generated slug
+directory may never take (because, as a directory under `src/parse_apis/`, the
+name would shadow or be confused with a package-level scaffold/generated
+member). Reservation is compared case-insensitively so it also holds on
+case-insensitive filesystems (macOS/APFS, Windows).
+"""
+from __future__ import annotations
+
+import keyword
+import re
+from pathlib import Path
+from typing import List
+
+# Runtime errors re-exported by the committed scaffold. Key-independent and
+# runtime-owned, so they carry no per-key metadata and are safe to commit
+# (define `__all__` in the committed scaffold, not "post-sync").
+_REEXPORTED = [
+    "ParseError",
+    "AuthError",
+    "ForbiddenError",
+    "NotFoundError",
+    "BadRequestError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "UpstreamError",
+    "PaginationError",
+    "PaginationLimitError",
+    "RequestMeta",
+]
+
+# Case-folded names a generated slug directory may not take. Derived from the
+# package-level scaffold members (`__init__.py`, `py.typed`) and the generated
+# top-level artifacts (`_manifest.json`, `AGENTS.md`, `CLAUDE.md`) plus the
+# runtime module names a reader would confuse with `parse_sdk._runtime` /
+# `parse_sdk.config`. `__init__` is load-bearing — a `parse_apis/__init__/`
+# directory is shadowed by the package initializer and becomes unimportable.
+RESERVED_SLUGS = frozenset({
+    "__init__",
+    "__main__",
+    "py",
+    "py.typed",
+    "pyproject",
+    "_manifest",
+    "_runtime",
+    "_config",
+    "agents",
+    "claude",
+})
+
+
+def is_reserved_slug(name: str) -> bool:
+    """True if ``name`` collides (case-insensitively) with a package-level
+    scaffold/generated member and must be suffixed before use as a slug dir."""
+    return name.casefold() in RESERVED_SLUGS
+
+
+_SLUG_UNSAFE = re.compile(r"[^0-9A-Za-z_]")
+
+
+def safe_slug(name: str) -> str:
+    """A filesystem- and import-safe slug: a valid Python identifier.
+
+    A server slug is an arbitrary value used BOTH as a directory name under
+    ``src/parse_apis/`` AND as an import path (``parse_apis.<slug>``). A hostile
+    or malformed slug (``../../etc``, ``a/b``, ``.``, ``""``) must never escape
+    the package directory (a path-traversal that `rmtree`/`copytree` would then
+    act on — audit SEC-1) or break imports. Any character outside
+    ``[0-9A-Za-z_]`` is replaced with ``_``; a leading digit is prefixed; an
+    empty result falls back to ``"api"``. Reserved/collision handling is the
+    caller's job (see ``cli._assign_slugs``).
+    """
+    cleaned = _SLUG_UNSAFE.sub("_", name)
+    if not cleaned:
+        return "api"
+    if cleaned[0].isdigit():
+        cleaned = "_" + cleaned
+    # A slug that is a (hard) Python keyword (``class``, ``for``, ``from``, ...)
+    # is a valid identifier shape but ``from parse_apis.<slug> import`` is a
+    # SyntaxError — suffix it just like a reserved name. Soft keywords
+    # (``match``/``case``/``type``/``_``) are NOT suffixed: they are not reserved,
+    # so they are valid module names and import fine.
+    if keyword.iskeyword(cleaned):
+        cleaned = cleaned + "_"
+    return cleaned
+
+
+def render_scaffold_init() -> str:
+    """The committed ``src/parse_apis/__init__.py``.
+
+    Importable before any slug exists (so installers have a valid dependency
+    target), re-exports the runtime errors by object identity, exposes no
+    credential writer, and gives a clear "run parse sync" diagnostic for
+    top-level helper access to a not-yet-generated slug.
+    """
+    names = ",\n    ".join(_REEXPORTED)
+    all_list = ",\n    ".join(f'"{n}"' for n in _REEXPORTED)
+    return f'''"""Parse typed APIs.
+
+Generated, typed clients for your Parse APIs appear here as submodules after
+`parse sync`:
+
+    from parse_apis.<slug> import <Root>
+
+Runtime errors are re-exported from `parse_sdk` so callers can
+`from parse_apis import RateLimitError` without importing the engine directly.
+This file is the committed scaffold — `parse sync` only writes the generated
+payload around it.
+"""
+from __future__ import annotations
+
+from parse_sdk import (
+    {names},
+)
+
+__all__ = [
+    {all_list},
+]
+
+
+def __getattr__(name: str):
+    # Submodule imports (`from parse_apis.<slug> import ...`) are handled by the
+    # import system; this only fires for attribute access on the package itself.
+    raise AttributeError(
+        f"module 'parse_apis' has no attribute {{name!r}}. "
+        f"If {{name!r}} is one of your Parse APIs, run `uv run parse sync` to generate it."
+    )
+'''
+
+
+def render_scaffold_pyproject(parse_sdk_version: str) -> str:
+    """The committed ``parse_apis/pyproject.toml``.
+
+    Pins ``parse-sdk`` to the EXACT version the clients were generated against
+    because generated code subclasses the underscore-private
+    ``parse_sdk._runtime`` bases by name, so a loose range would let a fresh
+    `uv sync` pull a runtime the on-disk code was never generated for. `parse
+    init`/`sync` restamp this as the engine moves; regeneration is the upgrade
+    path.
+    """
+    return f'''[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "parse-apis"
+version = "0.0.0"
+requires-python = ">=3.10"
+dependencies = [
+  "parse-sdk=={parse_sdk_version}",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parse_apis"]
+'''
+
+
+def render_gitignore_block() -> str:
+    """Deny-by-default ignore block for the consumer's ``.gitignore``.
+
+    Ignore EVERYTHING under the generated package and re-include only
+    the committed scaffold members, so any future top-level generated file is
+    ignored by construction — not by a hand-maintained per-filename allowlist
+    that leaks per-key data the day codegen adds an artifact.
+    """
+    return (
+        "# Parse SDK — generated payload is per-key (reveals your API inventory).\n"
+        "# Ignore everything under the generated package; keep only the committed scaffold.\n"
+        "parse_apis/src/parse_apis/*\n"
+        "!parse_apis/src/parse_apis/__init__.py\n"
+        "!parse_apis/src/parse_apis/py.typed\n"
+        ".parse/\n"
+    )
+
+
+def render_workflow_core() -> str:
+    """Steady-state workflow block shared (SSOT) by the committed root pointer
+    and ``parse help``: the whoami/list/sync workflow, the import model, and the
+    ``limit=`` cost rule. No leading/trailing blank lines so each caller controls
+    its own surrounding spacing."""
+    return (
+        "Workflow (run from the project root):\n"
+        "- Check auth / base URL / host-trust:   uv run parse whoami --json\n"
+        "- See which APIs your key can call:      uv run parse list --json\n"
+        "- Generate / refresh typed clients:      uv run parse sync --json\n"
+        "  (machine-readable status: written / skipped / quarantined / failures)\n"
+        "\n"
+        "Import a client:  from parse_apis.<slug> import <Root>\n"
+        "The exact <slug> and <Root> come from the generated tree, not `parse list`\n"
+        "(sync may sanitize/pin slugs): read `src/parse_apis/<slug>/README.md`, or\n"
+        "`uv run parse sync --json` (its `written[]` lists each slug + root).\n"
+        "\n"
+        "Before list/search calls, pass `limit=` unless exhaustive traversal is\n"
+        "explicitly requested — each page is a live, billed request."
+    )
+
+
+def render_root_pointer() -> str:
+    """The committed top-level agent pointer (``parse_apis/AGENTS.md`` and the
+    byte-identical ``parse_apis/CLAUDE.md``).
+
+    The cold-start surface — the first file an agent reads when it opens
+    ``parse_apis/``, and (unlike the generated index) it survives a fresh clone.
+    It names the workflow (via ``render_workflow_core``), one fresh-clone
+    recovery line (the generated tree is absent until ``parse init``/``sync``;
+    routes to ``parse help``/``parse doctor``), the ``limit=`` cost rule, and
+    where the on-demand reference lives. Kept tiny so it costs ~O(1) context;
+    refreshed content-compared on every sync. No HTML sentinel.
+    """
+    return (
+        "# Parse APIs — start here\n"
+        "\n"
+        "This package holds typed clients for this project's Parse APIs, generated\n"
+        "by the `parse` CLI (installed editable — imports resolve from any cwd).\n"
+        "`parse sync` overwrites generated files; change an API at parse.bot, then\n"
+        "re-sync.\n"
+        "\n"
+        "Fresh checkout? The generated tree (clients, per-API READMEs/examples,\n"
+        "`src/parse_apis/CLAUDE.md`) does not exist until `uv run parse init` (or\n"
+        "`uv run parse login` + `uv run parse sync`); until then importing a generated\n"
+        "client raises ModuleNotFoundError. Guided setup: `uv run parse help`;\n"
+        "diagnose a broken install: `uv run parse doctor`.\n"
+        "\n"
+        f"{render_workflow_core()}\n"
+        "\n"
+        "Conventions + the API index (generated; appear after `parse sync`):\n"
+        "`src/parse_apis/CLAUDE.md`. Per-API (generated): `src/parse_apis/<slug>/README.md`\n"
+        "+ runnable `example.py`.\n"
+    )
+
+
+def write_scaffold(project_dir: Path, parse_sdk_version: str) -> List[Path]:
+    """Write the committed scaffold under ``project_dir/parse_apis``.
+
+    Idempotent: overwrites the scaffold files (they are static modulo the
+    version stamp) and never touches generated payload. Returns the paths
+    written, sorted.
+    """
+    project_dir = Path(project_dir)
+    root = project_dir / "parse_apis"
+    pkg = root / "src" / "parse_apis"
+    pkg.mkdir(parents=True, exist_ok=True)
+
+    written: List[Path] = []
+
+    pyproject = root / "pyproject.toml"
+    pyproject.write_text(render_scaffold_pyproject(parse_sdk_version))
+    written.append(pyproject)
+
+    init = pkg / "__init__.py"
+    init.write_text(render_scaffold_init())
+    written.append(init)
+
+    py_typed = pkg / "py.typed"
+    py_typed.write_text("")
+    written.append(py_typed)
+
+    # Committed cold-start pointer at the package top (sibling to pyproject,
+    # outside the src/parse_apis gitignore glob → tracked). Byte-identical pair.
+    pointer = render_root_pointer()
+    for name in ("AGENTS.md", "CLAUDE.md"):
+        ptr = root / name
+        ptr.write_text(pointer)
+        written.append(ptr)
+
+    return sorted(written)

parse_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: parse-sdk
+Version: 0.1.0
+Summary: Dynamic-yet-typed Python SDK for Parse APIs
+Project-URL: Homepage, https://parse.bot
+Project-URL: Changelog, https://pypi.org/project/parse-sdk/#history
+Author-email: Parse <team@parse.bot>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,api-client,codegen,parse,scraping,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.408; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
+Description-Content-Type: text/markdown
+
+# parse-sdk
+
+Typed Python SDK tooling for [Parse](https://parse.bot) APIs.
+
+`parse-sdk` is the shared **runtime + CLI**. It generates a project-local
+`parse_apis` package — a real, installed, editable dependency — that holds the
+typed client for every API your key can call. Your application code imports from
+`parse_apis`; `parse-sdk` provides the runtime bases and errors those clients use.
+
+## Quickstart
+
+In a uv-managed project (`uv init` first if you don't have a `pyproject.toml`):
+
+```bash
+uv add parse-sdk            # installs the runtime + `parse` CLI into your project
+uv run parse init           # prompts for your API key, then scaffolds + syncs parse_apis
+```
+
+Non-interactive (CI, agents, scripts): authenticate first with
+`uv run parse login --api-key YOUR_KEY` (add `--base-url …` for a non-default
+host), or export `PARSE_API_KEY` — then `uv run parse init` runs without prompts.
+
+`parse init` is the one-time setup. It:
+
+1. ensures credentials (prompts and stores to `~/.config/parse/credentials`, or run `parse login` first);
+2. creates the committed `parse_apis` scaffold;
+3. records `parse_apis` as an **editable path dependency** (and a `[tool.uv.sources]` entry);
+4. appends a deny-by-default `.gitignore` block (commits the scaffold, ignores generated payload);
+5. migrates — or safely refuses — any legacy flat `parse_apis/` layout;
+6. runs the first `parse sync`.
+
+Then use it:
+
+```python
+from parse_apis.reddit_com_api import Reddit   # generated, typed client (slugs look like <domain>_<tld>_api)
+from parse_apis import RateLimitError          # runtime errors, re-exported
+
+reddit = Reddit()                              # picks up `parse login` credentials
+try:
+    # Navigate from a constructible resource, with a bounded fetch:
+    for post in reddit.subreddit("smallbusiness").search_posts(query="hiring", limit=10):
+        print(post.title)
+except RateLimitError:
+    ...
+```
+
+(The exact methods are generated from *your* API's spec — `parse_apis/<slug>/README.md`
+and `example.py` document each client's real surface.)
+
+```bash
+uv run python app.py        # run your app in the project environment
+uv run parse sync           # later: refresh after you change APIs in Parse
+```
+
+## Running commands (`uv run` vs. activation)
+
+`uv add parse-sdk` installs the `parse` console script into your project's `.venv`,
+which isn't on your shell `PATH` by default. Two equivalent ways to reach it:
+
+- **`uv run parse <cmd>`** — runs the venv's `parse` with no activation, auto-syncing first. (Recommended.)
+- **`source .venv/bin/activate`** then `parse <cmd>` directly.
+
+Prefer one of these over a global `uv tool install parse-sdk`: codegen must run with
+the **same** pinned `parse-sdk` your project runs against (see *Versioning* below), and a
+global copy can drift out of sync. Your end users running their *app* never invoke `parse` —
+they just `import parse_apis`.
+
+## On-disk layout
+
+```text
+parse_apis/
+  pyproject.toml                 # committed: name="parse-apis", pinned parse-sdk==X
+  src/parse_apis/
+    __init__.py                  # committed scaffold — re-exports runtime errors
+    py.typed                     # committed
+    reddit/__init__.py           # generated (gitignored)
+    _manifest.json               # generated (gitignored)
+    AGENTS.md  CLAUDE.md         # generated cross-API index (gitignored)
+```
+
+Commit the three scaffold files; the generated payload is per-key (it reveals your API
+inventory) and stays gitignored. `parse sync` builds the next payload in a staging tree,
+self-tests it (secret scan, import-model, no-stale-docs), and promotes it with an atomic
+directory swap — a failed sync never leaves broken or secret-bearing files in your project.
+
+## Import model
+
+- Application code imports generated clients from `parse_apis.<slug>`.
+- Runtime errors/base types are re-exported from `parse_apis` (sourced from `parse_sdk`).
+- Because `parse_apis` is an **installed** editable package, imports resolve from any
+  directory — no `sys.path` or editor `extraPaths` tricks.
+- Generated files are project-local and differ per Parse API key.
+
+## Fresh clone & CI (post-publish)
+
+```bash
+uv sync                     # installs deps incl. the editable parse_apis scaffold
+uv run parse sync           # regenerate the per-key payload
+uv run pytest && uv run pyright   # pyright must run against the PROJECT env —
+                                  # add both as dev deps (`uv add --dev pytest pyright`);
+                                  # a bare/global `pyright` can't resolve parse_apis
+```
+
+The committed scaffold is a valid dependency target before any slugs exist, so `uv sync`
+succeeds on a clean checkout.
+
+## CLI
+
+| Command | What it does |
+| --- | --- |
+| `parse login` | Save API key + base URL to local credentials. No project changes. |
+| `parse init` | One-time: ensure creds, scaffold `parse_apis`, record deps + gitignore, first sync. |
+| `parse sync` | Regenerate the typed payload into `parse_apis/src/parse_apis` (staged + atomic). |
+| `parse clean` | Remove generated payload; keep the committed scaffold. |
+| `parse list` | Print the APIs the current key can call (no generation). |
+| `parse whoami` | Show the current key + base URL. |
+
+Run `parse <cmd> --help` for full per-command help.
+
+## Versioning
+
+`parse_apis/pyproject.toml` pins the **exact** `parse-sdk` it was generated against — generated
+code subclasses the runtime by name. After upgrading `parse-sdk`, **re-run `parse sync`** to
+regenerate against the new runtime; `init`/`sync` restamp the pin.
+
+## Env vars
+
+| Var | Default | Notes |
+| --- | --- | --- |
+| `PARSE_API_KEY` | – | Auth for real requests (or use `parse login`). |
+| `PARSE_API_BASE_URL` | `https://api.parse.bot` | Locally: `http://localhost:8001`. |
+
+## Changelog
+
+Release history is on the PyPI project page:
+<https://pypi.org/project/parse-sdk/#history>.
+
+## Security
+
+To report a security issue, email **security@parse.bot** — please do not open
+a public issue.
+
+## License
+
+[MIT](LICENSE) © 2026 Parse. The license covers the `parse-sdk` runtime,
+codegen, and CLI; use of the Parse API/service is governed separately by
+Parse's terms.

parse_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+parse_sdk/__init__.py,sha256=cUCmf5MtpnAf14LKuwZXCnADVYxg1QwH1FWz3EesWmg,1434
+parse_sdk/_labels.py,sha256=pX9ZQ7ZyOo1f3ZIKOqrbH1_H54XO-0s-ZBsjJKw6cSU,1877
+parse_sdk/_oauth.py,sha256=HifVNsECBu1ZLx6da6hHMz5odcOTsAIVynn5_g1M_U4,13427
+parse_sdk/_project.py,sha256=ivMCJ857OMjjAsGXdkewa0cDfKzljlrrGikshTrlwjg,8160
+parse_sdk/_runtime.py,sha256=6E5ekavCouRUFAs3fxaquIvvpjCOz9VflQ9wZsGmoLk,107463
+parse_sdk/_sanitize.py,sha256=kp6v_QiE60KMZZEfzqOSZS6D3RrMzipa9RGps6ZXeS0,788
+parse_sdk/_sync.py,sha256=-uT_iYxsstEcOudP9XLD5CtB_keCXWHqBSQ_QELJfp0,42928
+parse_sdk/checks.py,sha256=Cqsv_cnf118YC5gHRVy_XE65q6MOPVNLpf_xhrsIflg,31375
+parse_sdk/cli.py,sha256=iiJDfqjmgxCIbWwxZ-wwbi6ItDFCnNciaxxXuGwL1xg,79440
+parse_sdk/cli_help.py,sha256=tWuzg49Yphu1qQo47y8UOixYoil_bFOYGMY174w5h5k,4274
+parse_sdk/codegen_reconcile.py,sha256=6_vRNX-Q4WuuUd3dk4QUi5IgiGT9fxU9C3L9hHAjPQ4,7961
+parse_sdk/codegen_v2.py,sha256=MPC_XAfQFK0b8RLBZL1oKx1vnUHhbGubykUegNMASjg,169864
+parse_sdk/config.py,sha256=5R2h-WNYp5gJKZ1L_dXS7Ex_eo0FxHTTBz127o7MuoU,16064
+parse_sdk/docgen.py,sha256=qD6Zqr5TsWNwIa19auO-7C04s2aPvVsFuJpsmHvvH-A,29702
+parse_sdk/doctor.py,sha256=6J7lA2_S1IF1jYII_PI94PCPU386UfU6x1rBagYC3Ns,14509
+parse_sdk/migrate.py,sha256=VHATy8TTYijVwpZdM4Gt7z-SBzVU7HTcIb5sALRQZ3M,8998
+parse_sdk/preview.py,sha256=6v10VM-WYFZ-slWrFQ826zo_TcMy8Z1xk-1DLYYAW-8,26595
+parse_sdk/resource_surface.py,sha256=zrGlNxxLXkGBLVopDxRipYpMVZO6ORSRCZ8lRiQOXqQ,9682
+parse_sdk/sample_gate.py,sha256=cnVa70vvtzy-CHcmKJNdn76Ob2sPYW2NalXZbVdbCkI,10757
+parse_sdk/scaffold.py,sha256=8kh9ROdcVmPA6rX2lyYP2f_xPOC4DHxWpDECESh_jIo,10728
+parse_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+parse_sdk-0.1.0.dist-info/METADATA,sha256=sEwJ_1WpSVnxCNPCtK8H40lFkf7M-rXKIBdYqmo-XVY,7356
+parse_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+parse_sdk-0.1.0.dist-info/entry_points.txt,sha256=NmdGaxEvLmPom9KsbpKXv5vZ3PrVeYLuT88Ka3YcI-s,44
+parse_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=bw_tWB6oxPxx0sPmtPQocG-4JH-_f2jjI3GhmapEQ2o,1062
+parse_sdk-0.1.0.dist-info/RECORD,,

parse_sdk-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

parse_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+parse = parse_sdk.cli:cli

parse_sdk-0.1.0.dist-info/licenses/LICENSE

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