memydev-base-sdk 0.1.0__py3-none-any.whl

memybase/_types.py

@@ -0,0 +1,91 @@
+"""
+@fileoverview Structured wire-response shapes hand-mirrored from the TypeScript SDK (sdk/js/src/types.ts).
+@module memybase._types
+@description Pure/shared module (like _errors.py/_mapping.py/_filter.py — NOT in gen_sync.py's
+    ASYNC_MODULES, so it has no _sync twin and both _self.py and its generated twin import it by the
+    same absolute path). Collection.list/get/... deliberately keep returning `dict[str, Any]` (this SDK
+    does not transform data-plane response payloads), so these TypedDicts are not new return-type
+    signatures — they are IMPORTABLE SHAPES a caller can use to type-annotate or `cast()` the raw dict
+    they already receive, the same role `RetryConfig` (_transport.py) plays for request options. Field
+    names mirror the wire JSON verbatim (camelCase), not Python's snake_case convention, because they
+    describe payloads parsed directly from server JSON rather than SDK-constructed request bodies.
+@dependencies none
+@relatedFiles ../../js/src/types.ts (ExpandRelationMeta, SchemaActivationJobSummary — the TS twins of
+    these shapes), ./_transport.py (RetryConfig — same TypedDict idiom), ./_self.py (SchemaActivationJobSummary
+    consumer), ./_errors.py (ValidationError.issues / RateLimitedError.retry_after — the SDK's existing
+    idiom for exposing structured detail out of an otherwise-untyped payload)
+@created 2026-08-01
+"""
+from __future__ import annotations
+
+from typing import Literal, Optional, TypedDict
+
+__all__ = [
+    "ExpandRelationMeta",
+    "ExpandMeta",
+    "SchemaActivationJobState",
+    "SchemaActivationJobSummary",
+]
+
+
+class ExpandRelationMeta(TypedDict, total=False):
+    """One relation's read caveats under a record's `expandMeta` envelope — the Python mirror of the JS
+    SDK's `ExpandRelationMeta` (sdk/js/src/types.ts) and the server's `ExpandRelationMeta` /
+    `EXPAND_META_KEY` (src/data/data-access.ts:196,214-220). Written ONLY when a relation named in
+    `expand=` was degraded for THIS record; a nominal read carries no `expandMeta` key at all, so its
+    absence is the promise that every expanded relation came back complete.
+
+    Closes a real consumer hazard: a REST `expand=` request that used to reject with `400 unsafe_query`
+    on an oversized expansion now returns `200` carrying this envelope instead. Code that used to branch
+    on the 400 must check ``record.get("expandMeta")`` to detect truncated/failed relations in an
+    otherwise-200 response::
+
+        meta: ExpandMeta = record.get("expandMeta") or {}
+        if meta.get("tags", {}).get("truncated"):
+            ...  # this record's "tags" relation was rationed, not necessarily short
+    """
+
+    truncated: bool
+    """The relation list was RATIONED: more links exist than this response carries. The list under this
+    flag MAY BE EMPTY — that does not mean the record has no links. Re-request with a narrower
+    `expand=` or a smaller page to see them."""
+
+    failed: bool
+    """The link read for THIS record failed; the relation is empty because of a read error, not because
+    the record has no links. Sibling records in the same page are unaffected — safe to retry."""
+
+
+ExpandMeta = dict[str, ExpandRelationMeta]
+"""A record's full `expandMeta` envelope, keyed by relation field. Present only when `expand=` was
+requested AND at least one named relation was degraded for that record."""
+
+
+SchemaActivationJobState = Literal[
+    "planned", "preparing", "verifying", "activating", "completed", "failed", "rolled-back"
+]
+"""Mirrors the server's `SchemaActivationJobState` (@memydev/base-contract)."""
+
+
+class SchemaActivationJobSummary(TypedDict):
+    """Customer-visible summary of a schema activation job — the response shape of
+    ``SelfService.get_schema_activation`` / ``.rollback_schema_activation``
+    (``GET/POST /api/self/.../schema/activations/{job_id}[/rollback]``).
+
+    Hand-typed to match EXACTLY what the self-service endpoint sends: `CustomerSchemaActivationJob` in
+    src/api/self/self-service.ts:55-57 strips the job's `compensation` block before a customer ever sees
+    it, so the vendored `SchemaActivationJob.compensation` — and with it `deferredIndexBuilds` /
+    `retiredSupersededIndexes` (@memydev/base-contract's `SchemaActivationCompensation`) — is NEVER present
+    on the wire here. Claiming those fields exist would silently mistype every caller; this type models
+    the SERVER'S ACTUAL RESPONSE, not the internal job record it was narrowed from. If a future change
+    surfaces activation-index caveats to customers, widen this type alongside that change.
+    """
+
+    _id: str
+    schemaVersionId: str
+    state: SchemaActivationJobState
+    stage: str
+    error: Optional[str]
+    retryCount: int
+    createdAt: str
+    updatedAt: str
+    completedAt: Optional[str]

memybase/sync/__init__.py

@@ -0,0 +1,41 @@
+"""
+@fileoverview Synchronous MemyBase client — a thin re-export of the unasync-GENERATED sync twins.
+@module memybase.sync
+@description The async modules (memybase/_*.py) are the single source of truth. scripts/gen_sync.py
+             mechanically derives the blocking twins in memybase/_sync/ (async def→def, await-strip,
+             httpx.AsyncClient→Client, asyncio→time, …); this facade only re-exports them so
+             ``from memybase.sync import MemyBase`` keeps working. Because the sync surface is generated,
+             it CANNOT drift from the async one — a new async method appears in the sync client on the next
+             gen_sync run, and tests/test_sync_parity.py + a CI ``gen_sync.py --check`` gate enforce it.
+             Realtime (Collection.subscribe / MemyBase.stream) is async-only (SSE is inherently async; this
+             sync client targets scripts / provisioning tooling with no event loop) and is deliberately
+             absent here — see tests/test_sync_parity.py's documented exclusion.
+
+             Usage::
+
+                 with MemyBase("https://memybase.example.com", api_key="pbk_...") as mb:
+                     customers = mb.collection("customers", project="crm", database="analytics")
+                     page = customers.list(page_size=10)
+@relatedFiles ../scripts/gen_sync.py, .._sync/, ../tests/test_sync_parity.py
+@created 2026-07-04
+@updated 2026-07-05  hand-written asyncio.run/ThreadPoolExecutor mirror → unasync single-source generation.
+"""
+from __future__ import annotations
+
+from .._filter import FilterBuilder  # shared/pure module (no async → no twin), same object as async side
+from .._sync._client import MemyBase
+from .._sync._collection import Collection
+from .._sync._graphql import GraphQLClient
+from .._sync._helpers import with_conflict_retry
+from .._sync._self import SelfService
+from .._sync._transport import RetryConfig
+
+__all__ = [
+    "MemyBase",
+    "Collection",
+    "SelfService",
+    "GraphQLClient",
+    "FilterBuilder",
+    "RetryConfig",
+    "with_conflict_retry",
+]

memydev_base_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: memydev-base-sdk
+Version: 0.1.0
+Summary: Official MemyBase client SDK for Python
+License: Proprietary and unlicensed pending approved service terms.
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: editables==0.5; extra == 'dev'
+Requires-Dist: hatchling==1.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==0.24.0; extra == 'dev'
+Requires-Dist: pytest==8.3.5; extra == 'dev'
+Requires-Dist: respx==0.22.0; extra == 'dev'
+Requires-Dist: unasync==0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# memydev-base-sdk — Official MemyBase Python SDK
+
+Async-first (with sync wrapper) client for the [MemyBase](https://base.memy.dev) hosted data service.
+Mirrors the JS `@memydev/base-sdk` selector→handle API: `mb.collection(slug, project=…, database=…)`.
+
+## Install
+
+Install a released package from the customer-accessible Python registry configured for the hosted
+MemyBase subscription. Keep the release version explicit in application configuration:
+
+```bash
+MEMYBASE_SDK_VERSION="0.1.0"
+MEMYBASE_PYTHON_INDEX_URL="<customer Python index URL>"
+python -m pip install --index-url "$MEMYBASE_PYTHON_INDEX_URL" "memydev-base-sdk==$MEMYBASE_SDK_VERSION"
+```
+
+Do not install this SDK from a workspace path, local wheel, or `file://` dependency in subscriber
+applications. A hosted subscription provides the MemyBase service and SDK integration surface; it does
+not deliver runtime/source/Devtron/MongoDB components.
+
+Release validation produces both the wheel and source distribution through Hatchling, verifies both with
+`twine check`, and installs the wheel into a clean venv from the configured subscriber Python index. The
+package includes `py.typed` and both async `memybase.MemyBase` and sync `memybase._sync.MemyBase` surfaces.
+
+## Usage
+
+```python
+from memybase import MemyBase
+
+mb = MemyBase("https://base.memy.dev", api_key="…")           # or token=… / user_token=…
+users = mb.collection("users", project="acme", database="prod")
+
+rec  = await users.create({"name": "Ada"})                    # omit None keys (reserved-field safe)
+page = await users.list(filter={"active": True}, page=1, page_size=50)
+one  = await users.get(rec["_id"])
+await users.update(rec["_id"], {"name": "Ada L."})
+await users.soft_delete(rec["_id"], reason="gdpr")
+```
+
+Sync facade: `from memybase.sync import MemyBase` (mechanically generated from the async core via
+`scripts/gen_sync.py` — single source, no drift; CRUD + customer management only).
+
+Retry policy mirrors the JS SDK: `retry={"max_retries": 2, "base_delay": 0.5,
+"retryable_statuses": []}` by default. Extra retryable statuses apply only to reads; writes stay limited
+to 429/503. The legacy constructor shortcut `max_retries=` is still accepted as an alias for
+`retry["max_retries"]`.
+
+### The `MemyBaseClient` facade convention (recommended)
+
+Do **not** spray `MemyBase(...)` construction and `except NotFoundError/…` handling across your codebase.
+The memy convention — shared by **every** MemyBase consumer — is a **single-seam `MemyBaseClient` facade**:
+ONE module wraps ONE `MemyBase` instance, and the rest of the app depends on that facade (never on
+`@memydev/base-sdk` / `memybase` directly). This keeps the SDK swappable, centralizes error translation, and
+makes call sites read **identically across languages**:
+
+```python
+# your_app/data/memybase/client.py — the ONLY module that imports `memybase`
+from memybase import MemyBase
+
+class MemyBaseClient:                       # ← the canonical name (same in JS + memybase itself)
+    def __init__(self, base_url: str, api_key: str, project: str, db: str) -> None:
+        self._mb = MemyBase(base_url, api_key=api_key)
+        self._project, self._db = project, db
+
+    def collection(self, slug: str):
+        return self._mb.collection(slug, project=self._project, database=self._db)
+    # + None-on-404 reads, bool-returning deletes, a `normalize_filter` chokepoint, SDK→app error
+    #   translation — whatever adaptations the SDK does not provide.
+
+client = MemyBaseClient(base_url, api_key, project="acme", db="prod")   # usage reads the same everywhere
+```
+
+The **same decision** is implemented in every project: `class MemyBaseClient` in memyswarm
+(`data/memybase/client.py`) and this SDK's Python peer; `class MemyBaseClient` in memyui
+(`apps/server/src/memybase/client.ts`); and `class MemyBaseClient` in memybase's own stdio-MCP consumer
+(`src/mcp/memybase-client.ts`). Reference implementation: memyswarm's `MemyBaseClient`.
+
+> A **producer/engine** (the tier holding the DB connection) is the ONE exception: in-process code binds
+> the data services directly and must NOT loop back through the SDK. `MemyBaseClient` is for **consumers**
+> — anything reaching the engine over the wire (apps, workers, MCP-over-stdio, a separate frontend).
+
+### Realtime (SSE)
+
+Subscribe to live change events over Server-Sent Events (async only — SSE is inherently async; the sync
+facade does not expose it). The callback fires for `ready` / `change` / `heartbeat` / `resync` events;
+the client auto-reconnects with backoff and resumes via `Last-Event-ID`.
+
+```python
+async with MemyBase("https://base.memy.dev", api_key="…") as mb:
+    def on_event(e):        # e: StreamEvent(event, data, id)
+        if e.event == "change":
+            print(e.data["type"], e.data["entity"], e.data["id"])
+
+    sub = await mb.collection("users", project="acme", database="prod").subscribe(on_event)
+    # … or all entities: sub = await mb.stream("acme", "prod", on_event)
+    await sub.wait()        # run until closed / terminal
+    await sub.close()       # stop + drain
+```
+
+## Surface
+
+- **Data plane** — `collection(slug, project=, database=)` → list/get/create/update/soft_delete/restore/versions/audit/hard_delete
+- **Realtime** — `collection(…).subscribe(on_event)` / `mb.stream(project, database, on_event)` → SSE (async only): `RealtimeClient`, `StreamEvent`, `SubscribeOptions`, `Subscription`
+- **Customer management** — `SelfService` for projects, databases, schema, credentials, settings, plans, usage, and lifecycle
+- **GraphQL** — `mb.graphql(project=, database=)`
+- **Filters** — `FilterBuilder`, `OPERATORS`, `serialize_filter`
+- **Errors** — typed hierarchy (`MemyBaseError` + `Conflict`/`NotFound`/`Validation`/`RateLimited`/… `decode_error`)
+- **Helpers** — `with_conflict_retry`, `guard_reserved_fields`, `omit_none`, `RESERVED_FIELDS`
+
+Reserved fields (`_id`, `createdAt`, `updatedAt`, …) are never sent on write; string fields are non-nullable — omit a key rather than sending `null`.
+
+## Versioning
+
+`memybase.__version__` tracks `SDK_VERSION`. Vendored artifacts are regenerated by `memybase/scripts/sdk-pack.sh` (packs this wheel + the JS tgz into their consumer repos).

memydev_base_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+memybase/__init__.py,sha256=B8VNKi6tpH94GZZkQy_GYjS5HxOlj-gWtAFhvjUuRIA,2148
+memybase/_client.py,sha256=vxhOkN973l4cC4uDrVVuXRz8Ab0n6uM6C77h-DOZidM,9100
+memybase/_collection.py,sha256=Tspa3sChfla5E6UUbSYecHKXCf4m16LWZXRz-IpiC3I,16821
+memybase/_errors.py,sha256=vyGEZJ9T7MSmN-YCIlol_j9ltG4-PwG1o37F5yE_wkM,7415
+memybase/_filter.py,sha256=wWLoQwK2HwEGEAIvdw4YREubMugste8SphU6ApreSBE,3499
+memybase/_graphql.py,sha256=Otjs-nIn_AcXxEbJNHSLFeUrVnZs2RpGl0WqUzWOwv8,1728
+memybase/_helpers.py,sha256=qkaycuwkUEDI-Kc_pTQ02r-HkIfpYOsmeBJWR7ZcYpI,1118
+memybase/_mapping.py,sha256=aMTeLCkNUw-ZqDis-6wQYL1Ubled3TtfUe0XjjZ8Qr8,1602
+memybase/_realtime.py,sha256=5OwseUNnCeb55d9NjoAy2ByJTLwXb4NN9XUcpdDlcTg,12505
+memybase/_self.py,sha256=E7n89Fk_hbBN6-_Gm2sHiYDBxd4au2gWLJM6grgADLc,7748
+memybase/_transport.py,sha256=1JuBxYNayxTdEUPbFTQAnNSTAWXBqIJWje9OHaojt8g,10037
+memybase/_types.py,sha256=ThiIdz6q3klJRqHSVSYcrRu2oB4kDo-nf78J9ljCYcE,4796
+memybase/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+memybase/_sync/__init__.py,sha256=H-jWQCc2cF5HStW7tfhwUVb9J8QWlEnwSP6uNwwwxYc,253
+memybase/_sync/_client.py,sha256=p4Gc5SmF8Og_VtWGBTOSAhRLdSy0svS16dQlB_ErvQI,8322
+memybase/_sync/_collection.py,sha256=08gCgp0d_xNSeEjQuOFgg6hydpvRR81F-nnJG1cFnO0,15513
+memybase/_sync/_graphql.py,sha256=dWATdGQ9zjxKWbluSbnaggLpA5imVvA9fbxPCV-dHJA,1864
+memybase/_sync/_helpers.py,sha256=fH44PcpVmXfUsPbLlkqupCJitSW0msbg0axsHiY2yCY,1243
+memybase/_sync/_self.py,sha256=XCw5IXioAR3FowgfveaPjmG1nu53lWG6qV0r0RiLxQ8,7569
+memybase/_sync/_transport.py,sha256=LzRN-NmICgiLXHO7pOqRQv7ym1uEXBguBST5s_MNS7g,8378
+memybase/sync/__init__.py,sha256=x2LyVA_Rv3vOl4EF9kYWHZTGjfHJMZwXK4bAAT0rZRg,2074
+memydev_base_sdk-0.1.0.dist-info/METADATA,sha256=toRsxB7a2lUI3tANHcjaTcyvcIhy8CYFEr4olK8gMnc,6830
+memydev_base_sdk-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+memydev_base_sdk-0.1.0.dist-info/RECORD,,

memydev_base_sdk-0.1.0.dist-info/WHEEL

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