parse-sdk 0.1.0__tar.gz

parse_sdk-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+parse_stubs/
+uv.lock
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.dev/
+
+# Personal working-notes / superpowers plans+specs — keep out of the shared repo.
+docs/superpowers/
+/plans/

parse_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `parse-sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — first public release
+
+Initial public release of the `parse-sdk` runtime + `parse` CLI: a
+dynamic-yet-typed Python SDK that generates a project-local, fully typed client
+for the Parse APIs your key can call.
+
+- **CLI** (`parse`): `init`, `sync`, `login` (API key or browser OAuth via
+  `--web`), `doctor` (diagnose / `--fix`), `list`, `whoami`, `help`, `clean`,
+  and marketplace `add` / `search` / `remove`, plus `[tool.parse]`-driven
+  selective sync.
+- **Typed runtime**: resources, collections, pagination, retries with a
+  wall-clock budget, and host-bound authentication.
+- Ships `py.typed`; supports Python 3.10–3.14.

parse_sdk-0.1.0/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.

parse_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,147 @@
+# 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/parse_sdk/__init__.py

@@ -0,0 +1,57 @@
+"""Parse SDK engine — errors, runtime helpers, and the `parse` CLI.
+
+Typed clients are generated by `parse sync` into a project-local
+`parse_apis/` package and imported directly:
+
+    import parse_sdk as parse                      # errors / runtime helpers
+    from parse_apis.reddit import Reddit           # generated typed client
+
+    try:
+        reddit = Reddit()                          # picks up `parse login` creds
+        for post in reddit.subreddit("smallbusiness").search_posts(query="hiring", limit=10):
+            print(post.title)
+    except parse.RateLimitError:
+        ...
+
+`parse_apis` is a real on-disk namespace package (pyright-resolvable, no
+import magic). `parse_sdk` no longer resolves generated submodules.
+"""
+
+from __future__ import annotations
+
+from parse_sdk._runtime import (
+    AuthError,
+    BadRequestError,
+    BaseAPI,
+    Collection,
+    ForbiddenError,
+    NotFoundError,
+    PaginationError,
+    PaginationLimitError,
+    Paginator,
+    ParseError,
+    QuotaExceededError,
+    RateLimitError,
+    Resource,
+    RequestMeta,
+    UpstreamError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "BaseAPI",
+    "Resource",
+    "Collection",
+    "Paginator",
+    "RequestMeta",
+    "ParseError",
+    "AuthError",
+    "ForbiddenError",
+    "NotFoundError",
+    "BadRequestError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "UpstreamError",
+    "PaginationError",
+    "PaginationLimitError",
+]

parse_sdk-0.1.0/parse_sdk/_labels.py

@@ -0,0 +1,51 @@
+"""Shared parsing for the closed type-label grammar codegen emits
+(``str`` | ``List[X]`` | ``Optional[X]`` | ``Dict[K, V]`` | ``_Paginator[X]`` |
+unions). Single source: ``codegen_reconcile``, ``sample_gate``, and the
+runtime previously each hand-rolled a splitter/unwrapper and drifted
+(``Paginator[`` vs ``_Paginator[``). Stdlib-only — ``_runtime`` imports it."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+_WRAPPERS = ("List[", "Optional[", "_Paginator[")
+
+
+def strip_wrapper(s: str, prefix: str) -> Optional[str]:
+    """The inner of a single ``<prefix>[...]`` layer, or ``None`` if ``s`` is not
+    that shape: ``strip_wrapper('Optional[X]', 'Optional[')`` → ``'X'``. The
+    one-layer primitive that ``unwrap_label`` loops over and ``sample_gate``
+    applies to a known prefix — single source for the ``s[len(prefix):-1]``
+    slice so the grammar parsers cannot drift."""
+    if s.startswith(prefix) and s.endswith("]"):
+        return s[len(prefix):-1].strip()
+    return None
+
+
+def split_top(s: str) -> List[str]:
+    """Split on commas at bracket-depth 0: ``'str, Dict[a, b]'`` →
+    ``['str', 'Dict[a, b]']``."""
+    parts, depth, start = [], 0, 0
+    for i, ch in enumerate(s):
+        if ch == "[":
+            depth += 1
+        elif ch == "]":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            parts.append(s[start:i].strip())
+            start = i + 1
+    parts.append(s[start:].strip())
+    return parts
+
+
+def unwrap_label(s: str, *, max_depth: int = 5) -> str:
+    """Strip wrapper layers down to the leaf: ``'List[Optional[X]]'`` → ``'X'``."""
+    s = s.strip()
+    for _ in range(max_depth):
+        for pfx in _WRAPPERS:
+            inner = strip_wrapper(s, pfx)
+            if inner is not None:
+                s = inner
+                break
+        else:
+            return s
+    return s