backd 0.0.1__tar.gz

backd-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+uv.lock

backd-0.0.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+- First version: `Client` and `AsyncClient` with the request pipeline, errors, retries, token storage and the size helpers.
+- `client.auth`: sign-up, login and the sign-in steps, MFA, magic links, providers (redirect and ID token), `reauth`/`with_proof`, sessions, the email flows, `client.org` and `on_auth_change`.
+- Collections: `list`, `iterate`, `search`, `aggregate`, `get`, `create`, `replace`, `patch`, `delete`, `restore`, `db.batch`, `in_team`/`in_org`, the query-language helpers, `expand` and `fill_buckets`.
+- The revalidation cache (`If-None-Match`/`304`, LRU by entries and bytes, per credential; `cache_stats`, `clear_cache`, `cache=False` per read) and `client.config` (`load`, `get`, `get_sync`, `view`, `on`, persisted copies through `config_storage`).
+- Files: `files(id, field)` (`list`, `get`, `put`, `delete`, `link`, `version`), `upload_file` (through backd, direct to the bucket, in parts), `prepare_upload`, `download_file` (streams to a path or file, checks the SHA-256), `file_url`, `public_url`, `version_status`, `Upload` and progress callbacks.
+- Functions and jobs: `db.fn`, `collection.fn`, `client.functions.call` / `run`, `Job` with `status`, `wait` (polling, timeout, progress) and `steps`, and `JobTimeoutError`.
+- `client.orgs` (organizations, members, teams and team-role windows, email templates, invitations, sign-in connections), `client.consents`, `client.push` (`register`, `devices`, `unregister`, `register_on_launch`) and `client.account` (data export: request, wait, download).
+- Realtime: `client.realtime.subscribe` and `collection.subscribe` over one multiplexed SSE stream, `LiveView` (threads) and `AsyncLiveView` (tasks) with `LiveState`, resume tokens, reset with jitter, reconnect with backoff, references, `access_lost`, and `client.config.live` (the configuration follows the stream). Closing the client leaves no thread or task running.
+- Generated types: `backd types --lang python` writes `types.py` (`TypedDict`s, `Literal`s, field constants, `Realm` and `AsyncRealm` wrappers); the Shelf example's types are checked with `mypy --strict` and for drift.
+- Release tooling: `scripts/check-python-package.sh` (`make python-package`) builds the sdist and the wheel, checks their metadata and contents and uses the wheel from a fresh virtualenv; `publish-python.yml` publishes to PyPI on `py-v*` tags with trusted publishing.

backd-0.0.1/LICENSE

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

backd-0.0.1/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: backd
+Version: 0.0.1
+Summary: Python client for backd: auth, sessions and data for services, scripts and notebooks.
+Project-URL: Homepage, https://fernandezvara.github.io/backd/docs/build/clients/python/
+Project-URL: Issues, https://github.com/fernandezvara/backd/issues
+Project-URL: Source, https://github.com/fernandezvara/backd/tree/main/clients/python
+Author: Antonio Fdez.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,backd,client,httpx,mongodb,rest,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# backd (Python)
+
+Python client for [backd](https://github.com/fernandezvara/backd): auth, sessions and data for services, scripts and notebooks.
+
+```python
+from backd import Client
+
+with Client(url="http://localhost:8080", realm="shelf", api_key=key) as backd:
+    ...
+```
+
+`AsyncClient` has the same calls with `async with` and `await`. One runtime dependency: [`httpx`](https://www.python-httpx.org/).
+`pip install backd` (PyPI, from the first release; until then `pip install "backd @ git+https://github.com/fernandezvara/backd#subdirectory=clients/python"`). Python 3.10 or later. The client is under construction (milestone 38); the [docs page](https://fernandezvara.github.io/backd/docs/build/clients/python/) lists what exists. `backd types --lang python` generates `TypedDict`s and typed wrappers for a realm.
+
+The admin API is not part of the client, for the same reason it isn't in the JavaScript, Dart and Go clients.
+
+## Development
+
+```sh
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python scripts/unasync.py     # writes src/backd/_sync from src/backd/_async
+.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy && .venv/bin/pytest
+```
+
+The async client is the source: `src/backd/_sync` is generated from `src/backd/_async` and checked in, and a test fails when it is out of date. Edit the async file, then run `scripts/unasync.py`. Files with no twin (the realtime stream, where a thread and a task differ in more than syntax) are written by hand.

backd-0.0.1/README.md

@@ -0,0 +1,25 @@
+# backd (Python)
+
+Python client for [backd](https://github.com/fernandezvara/backd): auth, sessions and data for services, scripts and notebooks.
+
+```python
+from backd import Client
+
+with Client(url="http://localhost:8080", realm="shelf", api_key=key) as backd:
+    ...
+```
+
+`AsyncClient` has the same calls with `async with` and `await`. One runtime dependency: [`httpx`](https://www.python-httpx.org/).
+`pip install backd` (PyPI, from the first release; until then `pip install "backd @ git+https://github.com/fernandezvara/backd#subdirectory=clients/python"`). Python 3.10 or later. The client is under construction (milestone 38); the [docs page](https://fernandezvara.github.io/backd/docs/build/clients/python/) lists what exists. `backd types --lang python` generates `TypedDict`s and typed wrappers for a realm.
+
+The admin API is not part of the client, for the same reason it isn't in the JavaScript, Dart and Go clients.
+
+## Development
+
+```sh
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python scripts/unasync.py     # writes src/backd/_sync from src/backd/_async
+.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy && .venv/bin/pytest
+```
+
+The async client is the source: `src/backd/_sync` is generated from `src/backd/_async` and checked in, and a test fails when it is out of date. Edit the async file, then run `scripts/unasync.py`. Files with no twin (the realtime stream, where a thread and a task differ in more than syntax) are written by hand.

backd-0.0.1/examples/shelf/README.md

@@ -0,0 +1,16 @@
+# The Python client against the Shelf tutorial stack
+
+`main.py` signs in to the tutorial's `shelf` realm, lists the published assets with the generated types, saves a note
+and follows the assets live for ten seconds.
+
+```sh
+pip install -e clients/python
+SHELF_EMAIL=ada@example.com SHELF_PASSWORD='dev-p4ssw0rd!' python clients/python/examples/shelf/main.py
+```
+
+`BACKD_URL` is the address of the stack (`http://localhost:8080` by default). The session is kept in
+`~/.backd-shelf-python.session`: only the first run signs in.
+
+`shelf_types/types.py` is generated and checked by CI (`make shelf-types`); after a change to the Shelf's schema,
+`make shelf-types-update` rewrites it. The guide is
+[Python client](https://fernandezvara.github.io/backd/docs/build/clients/python/).

backd-0.0.1/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "backd"
+dynamic = ["version"]
+description = "Python client for backd: auth, sessions and data for services, scripts and notebooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Antonio Fdez." }]
+keywords = ["backd", "client", "sdk", "rest", "mongodb", "auth", "httpx"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://fernandezvara.github.io/backd/docs/build/clients/python/"
+Issues = "https://github.com/fernandezvara/backd/issues"
+Source = "https://github.com/fernandezvara/backd/tree/main/clients/python"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-timeout>=2.3", "ruff>=0.6", "mypy>=1.11", "build", "twine"]
+
+[tool.hatch.version]
+path = "src/backd/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/backd"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["src", "examples/shelf"]
+addopts = "-ra"
+timeout = 60  # a hang in the realtime tests fails the test instead of the whole run
+
+[tool.ruff]
+line-length = 120
+src = ["src", "tests"]
+extend-exclude = ["src/backd/_sync", "examples/shelf/shelf_types"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["RUF059"]  # a fixture's unused parts are fine in a test
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests", "scripts", "examples"]
+mypy_path = "src:examples/shelf"
+explicit_package_bases = true

backd-0.0.1/src/backd/__init__.py

@@ -0,0 +1,284 @@
+"""Python client for backd: auth, sessions and data for services, scripts and notebooks.
+
+``Client`` is the sync client and ``AsyncClient`` the async one; both have the same calls.
+"""
+
+from ._async.client import AsyncClient
+from ._async.data import AsyncCollection, AsyncDatabase
+from ._async.functions import AsyncJob
+from ._async.realtime import AsyncLiveView
+from ._live import LiveState, LiveStatus, LiveSubscriptionState, ReferenceSpec, SubscribeOptions, SubscriptionSpec
+from ._retry import Retry
+from ._sync.client import Client
+from ._sync.data import Collection, Database
+from ._sync.functions import Job
+from ._sync.realtime import LiveView
+from .cache import CacheOptions, CacheStats
+from .config_storage import ConfigStorage, FileConfigStorage, MemoryConfigStorage
+from .errors import (
+    AggregateNotEnabledError,
+    AggregateTooExpensiveError,
+    AuthenticationError,
+    BackdError,
+    ConflictError,
+    ConsentRequiredError,
+    ErrorDetail,
+    ExpandTooLargeError,
+    FieldEncryptedError,
+    ForbiddenError,
+    IdTakenError,
+    IndexBuildingError,
+    InvalidAggregateError,
+    InvalidExpandError,
+    InvalidIdError,
+    InvalidResumeTokenError,
+    JobTimeoutError,
+    LastOrgManagerError,
+    NetworkError,
+    NotAllowedError,
+    NotFoundError,
+    NotOrgMemberError,
+    NotTeamMemberError,
+    OrgRequiresMFAError,
+    OrgRoleRequiresMFAError,
+    PasswordExpiredError,
+    RealtimeNotEnabledError,
+    RetryableError,
+    SearchNotEnabledError,
+    SearchTooExpensiveError,
+    SecondStepRequiredError,
+    SessionEndedError,
+    SsoRequiredError,
+    SsoSessionError,
+    TeamError,
+    TooManySubscriptionsError,
+    ValidationError,
+    VerificationRequiredError,
+    VersionMismatchError,
+)
+from .files import public_url, version_status
+from .models import (
+    AggregateGroup,
+    AggregateResult,
+    BatchOperation,
+    ConsentChallenge,
+    ConsentInfo,
+    ConsentState,
+    ConsentText,
+    DataExport,
+    Device,
+    DeviceInput,
+    Doc,
+    EnrollmentChallenge,
+    FileDetails,
+    FileField,
+    FileLink,
+    Identity,
+    JobData,
+    JobResult,
+    JobStep,
+    Me,
+    Meta,
+    MfaChallenge,
+    Org,
+    OrgConnection,
+    OrgInvitation,
+    OrgMember,
+    OrgTeam,
+    OrgTeamMember,
+    OrgTeamRoleGrant,
+    OrgTemplate,
+    OrgTemplateText,
+    Page,
+    PreparedUpload,
+    Profile,
+    ProviderSession,
+    RoleOrigin,
+    Session,
+    SessionInfo,
+    SignInResult,
+    User,
+    VersionState,
+)
+from .oauth import MemoryOAuthStorage, OAuthReturn, OAuthStorage
+from .query import (
+    Where,
+    and_,
+    between,
+    bucket_key,
+    contains,
+    ends_with,
+    eq,
+    expand,
+    fill_buckets,
+    gt,
+    gte,
+    icontains,
+    iends_with,
+    ilike,
+    in_,
+    is_null,
+    istarts_with,
+    like,
+    lt,
+    lte,
+    ne,
+    nin,
+    not_null,
+    or_,
+    search,
+    starts_with,
+)
+from .size import SizeFamily, format_bytes, parse_size
+from .storage import FileStorage, MemoryStorage, SlotStorage, TokenStorage
+from .upload import Progress, Upload, UploadSource, part_size_for
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AggregateGroup",
+    "AggregateNotEnabledError",
+    "AggregateResult",
+    "AggregateTooExpensiveError",
+    "AsyncClient",
+    "AsyncCollection",
+    "AsyncDatabase",
+    "AsyncJob",
+    "AsyncLiveView",
+    "AuthenticationError",
+    "BackdError",
+    "BatchOperation",
+    "CacheOptions",
+    "CacheStats",
+    "Client",
+    "Collection",
+    "ConfigStorage",
+    "ConflictError",
+    "ConsentChallenge",
+    "ConsentInfo",
+    "ConsentRequiredError",
+    "ConsentState",
+    "ConsentText",
+    "DataExport",
+    "Database",
+    "Device",
+    "DeviceInput",
+    "Doc",
+    "EnrollmentChallenge",
+    "ErrorDetail",
+    "ExpandTooLargeError",
+    "FieldEncryptedError",
+    "FileConfigStorage",
+    "FileDetails",
+    "FileField",
+    "FileLink",
+    "FileStorage",
+    "ForbiddenError",
+    "IdTakenError",
+    "Identity",
+    "IndexBuildingError",
+    "InvalidAggregateError",
+    "InvalidExpandError",
+    "InvalidIdError",
+    "InvalidResumeTokenError",
+    "Job",
+    "JobData",
+    "JobResult",
+    "JobStep",
+    "JobTimeoutError",
+    "LastOrgManagerError",
+    "LiveState",
+    "LiveStatus",
+    "LiveSubscriptionState",
+    "LiveView",
+    "Me",
+    "MemoryConfigStorage",
+    "MemoryOAuthStorage",
+    "MemoryStorage",
+    "Meta",
+    "MfaChallenge",
+    "NetworkError",
+    "NotAllowedError",
+    "NotFoundError",
+    "NotOrgMemberError",
+    "NotTeamMemberError",
+    "OAuthReturn",
+    "OAuthStorage",
+    "Org",
+    "OrgConnection",
+    "OrgInvitation",
+    "OrgMember",
+    "OrgRequiresMFAError",
+    "OrgRoleRequiresMFAError",
+    "OrgTeam",
+    "OrgTeamMember",
+    "OrgTeamRoleGrant",
+    "OrgTemplate",
+    "OrgTemplateText",
+    "Page",
+    "PasswordExpiredError",
+    "PreparedUpload",
+    "Profile",
+    "Progress",
+    "ProviderSession",
+    "RealtimeNotEnabledError",
+    "ReferenceSpec",
+    "Retry",
+    "RetryableError",
+    "RoleOrigin",
+    "SearchNotEnabledError",
+    "SearchTooExpensiveError",
+    "SecondStepRequiredError",
+    "Session",
+    "SessionEndedError",
+    "SessionInfo",
+    "SignInResult",
+    "SizeFamily",
+    "SlotStorage",
+    "SsoRequiredError",
+    "SsoSessionError",
+    "SubscribeOptions",
+    "SubscriptionSpec",
+    "TeamError",
+    "TokenStorage",
+    "TooManySubscriptionsError",
+    "Upload",
+    "UploadSource",
+    "User",
+    "ValidationError",
+    "VerificationRequiredError",
+    "VersionMismatchError",
+    "VersionState",
+    "Where",
+    "__version__",
+    "and_",
+    "between",
+    "bucket_key",
+    "contains",
+    "ends_with",
+    "eq",
+    "expand",
+    "fill_buckets",
+    "format_bytes",
+    "gt",
+    "gte",
+    "icontains",
+    "iends_with",
+    "ilike",
+    "in_",
+    "is_null",
+    "istarts_with",
+    "like",
+    "lt",
+    "lte",
+    "ne",
+    "nin",
+    "not_null",
+    "or_",
+    "parse_size",
+    "part_size_for",
+    "public_url",
+    "search",
+    "starts_with",
+    "version_status",
+]

backd-0.0.1/src/backd/_aio.py

@@ -0,0 +1,29 @@
+"""The few places where the async client needs a different function from the sync one.
+``scripts/unasync.py`` swaps this module for ``_sio`` when it writes ``_sync``."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Coroutine
+from typing import Any, TypeVar, cast
+
+T = TypeVar("T")
+
+
+async def sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+_tasks: set[asyncio.Task[None]] = set()
+
+
+def spawn(fn: Callable[..., Awaitable[None]], *args: Any) -> None:
+    """Runs ``fn(*args)`` in the background: a task here, a thread in the sync client."""
+    task: asyncio.Task[None] = asyncio.get_running_loop().create_task(cast("Coroutine[Any, Any, None]", fn(*args)))
+    _tasks.add(task)  # a task nothing refers to may be collected before it ends
+    task.add_done_callback(_tasks.discard)
+
+
+async def run_blocking(fn: Callable[..., T], *args: Any) -> T:
+    """Runs a blocking function (hashing a big file) without stopping the event loop; the sync client just calls it."""
+    return await asyncio.to_thread(fn, *args)

backd-0.0.1/src/backd/_async/__init__.py

@@ -0,0 +1 @@
+"""The async client. These files are the source of ``_sync``; run ``python scripts/unasync.py``."""