cweb-forge 0.1.0__tar.gz

cweb_forge-0.1.0/LICENSE

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

cweb_forge-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: cweb-forge
+Version: 0.1.0
+Summary: Python SDK for cWeb Forge serverless data, for applications and notebooks
+Author: PyStrap
+License-Expression: MIT
+Project-URL: Homepage, https://cweb.app
+Project-URL: Documentation, https://github.com/pystrap/cweb-forge-python#readme
+Project-URL: Source, https://github.com/pystrap/cweb-forge-python
+Project-URL: Issues, https://github.com/pystrap/cweb-forge-python/issues
+Keywords: cweb,forge,serverless,database,sdk,notebooks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28
+Dynamic: license-file
+
+# cWeb Forge · Python
+
+**Serverless data and authentication API for your next application.**
+
+Use cWeb Forge collections from Python backends, scripts and notebooks without
+building a separate data API. This is the official Python SDK for
+[cWeb Forge](https://cweb.app), with synchronous and asynchronous clients for
+applications on cWeb or any other host.
+
+- JSON document operations with collection access rules.
+- Cursor pagination, equality filters and streaming iteration over pages.
+- Version checks for concurrent edits and idempotency keys for create retries.
+- Backend service keys or application-user access tokens.
+- Works with Django, FastAPI, cWeb Studio and other Python notebook environments.
+
+[Getting started](#getting-started) · [Async usage](#async-usage) ·
+[Notebooks](#notebooks) · [Contributing](#contributing)
+
+## Installation
+
+Requires Python 3.10 or later.
+
+The first PyPI release is being prepared. Until it is available, clone this
+repository and install from its local path:
+
+```sh
+python -m pip install ./cweb-forge-python
+```
+
+Once published, install from PyPI:
+
+```sh
+python -m pip install cweb-forge
+```
+
+The package name is `cweb-forge`; import it as `cweb_forge`.
+
+## Getting started
+
+1. Create a Forge application in the [cWeb dashboard](https://portal.cweb.app)
+   and copy its API endpoint, including `/v1/`.
+2. Create a service key restricted to the collections and actions your backend
+   needs. Supply it as `CWEB_FORGE_KEY` through your environment or secret manager.
+3. Use the application's `records` collection to try the SDK:
+
+```python
+import os
+from cweb_forge import ForgeClient
+
+endpoint = 'https://my-app.forge.cweb.app/v1/'  # Replace with your endpoint.
+
+with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+    records = forge.collection('records')
+    created = records.create({'title': 'Draft', 'status': 'active'})
+    saved = records.update(
+        created['id'], {'title': 'Published'}, version=created['version']
+    )
+    print(saved['id'])
+```
+
+Use a context manager to close connections, or call `forge.close()` when
+finished. A service key may access records across application users according
+to its scopes. Never embed one in frontend code, mobile apps or shared notebooks.
+
+### Application-user tokens
+
+`token` can instead be an application user's access token or a callable that
+returns a fresh token before each request. The asynchronous client also accepts
+an async callable. Token validation and collection policies are enforced by the
+service; default owner access keeps a user's documents private to that user.
+
+The Python SDK does not perform interactive sign-in or automatically refresh a
+fixed token string. Your application's authentication integration must supply
+and refresh its tokens. Use the
+[JavaScript SDK](https://github.com/pystrap/cweb-forge-js#authentication) for
+browser sign-in. Never use a cWeb dashboard login token as a Forge application token.
+
+### Public reads without a token
+
+Set the collection's read policy to **Anyone (public)** under **Collections &
+rules**, then omit `token`:
+
+```python
+from cweb_forge import ForgeClient
+
+with ForgeClient('https://my-app.forge.cweb.app/v1/') as forge:
+    page = forge.collection('products').list(limit=50)
+    for document in page['items']:
+        print(document['data'])
+```
+
+Every document and field in that collection is public. Keep private data in
+separate collections. Anonymous writes are not supported, and public reads
+still consume the application's request allowances.
+
+## Working with documents
+
+Your JSON object is returned in `document['data']`, alongside metadata including
+`id`, `owner`, `version`, `created_at` and `updated_at`.
+
+| Method | Purpose |
+| --- | --- |
+| `list(limit=50, after=None, field=None, equals=None)` | Read a page with `items` and `next_cursor`. |
+| `get(document_id)` | Read one document. |
+| `create(data, idempotency_key=None)` | Create a document; a key is generated if omitted. |
+| `update(document_id, data, version=...)` | Patch the supplied fields. |
+| `replace(document_id, data, version=...)` | Replace the document's data. |
+| `delete(document_id, version=...)` | Delete a document. |
+| `iterate(limit=50, field=None, equals=None)` | Iterate over documents across successive pages. |
+
+Collection names start with a lowercase letter, contain lowercase letters,
+numbers or underscores, and have a maximum length of 64 characters. Document
+IDs are UUIDs returned by Forge.
+
+```python
+with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+    records = forge.collection('records')
+    page = records.list(limit=50, field='status', equals='active')
+    if page['next_cursor']:
+        next_page = records.list(
+            limit=50, after=page['next_cursor'], field='status', equals='active'
+        )
+
+    for document in records.iterate(limit=100, field='status', equals='active'):
+        print(document['id'])
+```
+
+Equality filters accept scalar field values. Page limits range from 1 to 100
+documents. Iteration fetches one page at a time; collecting every result into a
+list still uses memory for the entire result.
+
+Use the latest returned `version` for each update, replacement or deletion.
+On a `409` conflict, reload and resolve the change before retrying. To retry a
+create after an uncertain network outcome, reuse the same `idempotency_key`
+for that logical operation within the server's 24-hour window. The SDK does not
+automatically retry writes.
+
+## Async usage
+
+Use `AsyncForgeClient` in asynchronous applications. Await document operations,
+and use `async for` when iterating:
+
+```python
+import asyncio
+import os
+from cweb_forge import AsyncForgeClient
+
+async def main():
+    async with AsyncForgeClient(
+        'https://my-app.forge.cweb.app/v1/',
+        token=os.environ['CWEB_FORGE_KEY'],
+    ) as forge:
+        records = forge.collection('records')
+        created = await records.create({'title': 'Async example'})
+        print(created['id'])
+        async for document in records.iterate(limit=100):
+            print(document['id'])
+
+asyncio.run(main())
+```
+
+In notebooks with an existing event loop, use `await main()` instead of
+`asyncio.run(main())`. Close a manually managed async client with
+`await forge.close()`.
+
+## Notebooks
+
+The SDK can fetch data for pandas, DuckDB or your own analysis code. Those
+libraries are optional and installed separately. Start with a read-only key and
+a bounded sample:
+
+```python
+import os
+import pandas as pd
+from cweb_forge import ForgeClient
+
+# Configure this secret in the notebook environment; do not paste it into a cell.
+with ForgeClient(
+    'https://my-app.forge.cweb.app/v1/',
+    token=os.environ['CWEB_FORGE_KEY'],
+) as forge:
+    page = forge.collection('sales').list(limit=100)
+    frame = pd.DataFrame([document['data'] for document in page['items']])
+```
+
+This reads a page of JSON documents; it does not mount a database or automatically
+copy the whole collection into Studio's catalog. Do not save credentials or
+sensitive results in notebook outputs that you intend to share.
+
+## Errors and timeouts
+
+Catch `ForgeError` for API or transport failures. It includes `status`, `code`
+and `request_id`; network failures use status `0`.
+
+| Status | Suggested handling |
+| --- | --- |
+| `401` | Renew credentials or sign the application user in again. |
+| `403` | Check collection rules and service-key permissions. |
+| `409` | Resolve a concurrent edit or idempotency conflict. |
+| `429` | Inspect the error code for rate or quota limits before retrying. |
+| `503` | Retry later with bounded backoff when safe. |
+
+```python
+from cweb_forge import ForgeError
+
+try:
+    with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+        page = forge.collection('records').list()
+except ForgeError as error:
+    print(f'Forge request failed: {error.status} {error.code}')
+    # Share error.request_id with support if present; never log credentials.
+```
+
+HTTPX timeouts default to 15 seconds and can be configured with `timeout=30`
+on the client. These are transport timeouts, not a deadline for a complete
+multi-page iteration. HTTPS is required except on localhost; redirects and
+proxy settings inherited from environment variables are disabled.
+
+## Security and support
+
+Use narrowly scoped keys and rotate them if exposed. Keep keys, application-user
+tokens, private data and authentication headers out of logs and Git commits.
+For vulnerabilities, follow the
+[security policy](https://github.com/pystrap/cweb-forge-python/blob/main/SECURITY.md).
+
+Report SDK bugs through
+[GitHub issues](https://github.com/pystrap/cweb-forge-python/issues), with the
+SDK/Python versions and a minimal reproduction. For account or billing help,
+contact cWeb Support at [support@cweb.app](mailto:support@cweb.app).
+
+## Contributing
+
+Focused fixes, regression tests and documentation improvements are welcome.
+From a clone of this repository:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+Tests use mocked HTTP responses and do not require a live Forge account.
+Include tests for changed behavior and never submit customer data or credentials.
+
+## License
+
+[MIT](https://github.com/pystrap/cweb-forge-python/blob/main/LICENSE).
+Maintained by [PyStrap](https://pystrap.co.uk), the team behind cWeb.

cweb_forge-0.1.0/README.md

@@ -0,0 +1,249 @@
+# cWeb Forge · Python
+
+**Serverless data and authentication API for your next application.**
+
+Use cWeb Forge collections from Python backends, scripts and notebooks without
+building a separate data API. This is the official Python SDK for
+[cWeb Forge](https://cweb.app), with synchronous and asynchronous clients for
+applications on cWeb or any other host.
+
+- JSON document operations with collection access rules.
+- Cursor pagination, equality filters and streaming iteration over pages.
+- Version checks for concurrent edits and idempotency keys for create retries.
+- Backend service keys or application-user access tokens.
+- Works with Django, FastAPI, cWeb Studio and other Python notebook environments.
+
+[Getting started](#getting-started) · [Async usage](#async-usage) ·
+[Notebooks](#notebooks) · [Contributing](#contributing)
+
+## Installation
+
+Requires Python 3.10 or later.
+
+The first PyPI release is being prepared. Until it is available, clone this
+repository and install from its local path:
+
+```sh
+python -m pip install ./cweb-forge-python
+```
+
+Once published, install from PyPI:
+
+```sh
+python -m pip install cweb-forge
+```
+
+The package name is `cweb-forge`; import it as `cweb_forge`.
+
+## Getting started
+
+1. Create a Forge application in the [cWeb dashboard](https://portal.cweb.app)
+   and copy its API endpoint, including `/v1/`.
+2. Create a service key restricted to the collections and actions your backend
+   needs. Supply it as `CWEB_FORGE_KEY` through your environment or secret manager.
+3. Use the application's `records` collection to try the SDK:
+
+```python
+import os
+from cweb_forge import ForgeClient
+
+endpoint = 'https://my-app.forge.cweb.app/v1/'  # Replace with your endpoint.
+
+with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+    records = forge.collection('records')
+    created = records.create({'title': 'Draft', 'status': 'active'})
+    saved = records.update(
+        created['id'], {'title': 'Published'}, version=created['version']
+    )
+    print(saved['id'])
+```
+
+Use a context manager to close connections, or call `forge.close()` when
+finished. A service key may access records across application users according
+to its scopes. Never embed one in frontend code, mobile apps or shared notebooks.
+
+### Application-user tokens
+
+`token` can instead be an application user's access token or a callable that
+returns a fresh token before each request. The asynchronous client also accepts
+an async callable. Token validation and collection policies are enforced by the
+service; default owner access keeps a user's documents private to that user.
+
+The Python SDK does not perform interactive sign-in or automatically refresh a
+fixed token string. Your application's authentication integration must supply
+and refresh its tokens. Use the
+[JavaScript SDK](https://github.com/pystrap/cweb-forge-js#authentication) for
+browser sign-in. Never use a cWeb dashboard login token as a Forge application token.
+
+### Public reads without a token
+
+Set the collection's read policy to **Anyone (public)** under **Collections &
+rules**, then omit `token`:
+
+```python
+from cweb_forge import ForgeClient
+
+with ForgeClient('https://my-app.forge.cweb.app/v1/') as forge:
+    page = forge.collection('products').list(limit=50)
+    for document in page['items']:
+        print(document['data'])
+```
+
+Every document and field in that collection is public. Keep private data in
+separate collections. Anonymous writes are not supported, and public reads
+still consume the application's request allowances.
+
+## Working with documents
+
+Your JSON object is returned in `document['data']`, alongside metadata including
+`id`, `owner`, `version`, `created_at` and `updated_at`.
+
+| Method | Purpose |
+| --- | --- |
+| `list(limit=50, after=None, field=None, equals=None)` | Read a page with `items` and `next_cursor`. |
+| `get(document_id)` | Read one document. |
+| `create(data, idempotency_key=None)` | Create a document; a key is generated if omitted. |
+| `update(document_id, data, version=...)` | Patch the supplied fields. |
+| `replace(document_id, data, version=...)` | Replace the document's data. |
+| `delete(document_id, version=...)` | Delete a document. |
+| `iterate(limit=50, field=None, equals=None)` | Iterate over documents across successive pages. |
+
+Collection names start with a lowercase letter, contain lowercase letters,
+numbers or underscores, and have a maximum length of 64 characters. Document
+IDs are UUIDs returned by Forge.
+
+```python
+with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+    records = forge.collection('records')
+    page = records.list(limit=50, field='status', equals='active')
+    if page['next_cursor']:
+        next_page = records.list(
+            limit=50, after=page['next_cursor'], field='status', equals='active'
+        )
+
+    for document in records.iterate(limit=100, field='status', equals='active'):
+        print(document['id'])
+```
+
+Equality filters accept scalar field values. Page limits range from 1 to 100
+documents. Iteration fetches one page at a time; collecting every result into a
+list still uses memory for the entire result.
+
+Use the latest returned `version` for each update, replacement or deletion.
+On a `409` conflict, reload and resolve the change before retrying. To retry a
+create after an uncertain network outcome, reuse the same `idempotency_key`
+for that logical operation within the server's 24-hour window. The SDK does not
+automatically retry writes.
+
+## Async usage
+
+Use `AsyncForgeClient` in asynchronous applications. Await document operations,
+and use `async for` when iterating:
+
+```python
+import asyncio
+import os
+from cweb_forge import AsyncForgeClient
+
+async def main():
+    async with AsyncForgeClient(
+        'https://my-app.forge.cweb.app/v1/',
+        token=os.environ['CWEB_FORGE_KEY'],
+    ) as forge:
+        records = forge.collection('records')
+        created = await records.create({'title': 'Async example'})
+        print(created['id'])
+        async for document in records.iterate(limit=100):
+            print(document['id'])
+
+asyncio.run(main())
+```
+
+In notebooks with an existing event loop, use `await main()` instead of
+`asyncio.run(main())`. Close a manually managed async client with
+`await forge.close()`.
+
+## Notebooks
+
+The SDK can fetch data for pandas, DuckDB or your own analysis code. Those
+libraries are optional and installed separately. Start with a read-only key and
+a bounded sample:
+
+```python
+import os
+import pandas as pd
+from cweb_forge import ForgeClient
+
+# Configure this secret in the notebook environment; do not paste it into a cell.
+with ForgeClient(
+    'https://my-app.forge.cweb.app/v1/',
+    token=os.environ['CWEB_FORGE_KEY'],
+) as forge:
+    page = forge.collection('sales').list(limit=100)
+    frame = pd.DataFrame([document['data'] for document in page['items']])
+```
+
+This reads a page of JSON documents; it does not mount a database or automatically
+copy the whole collection into Studio's catalog. Do not save credentials or
+sensitive results in notebook outputs that you intend to share.
+
+## Errors and timeouts
+
+Catch `ForgeError` for API or transport failures. It includes `status`, `code`
+and `request_id`; network failures use status `0`.
+
+| Status | Suggested handling |
+| --- | --- |
+| `401` | Renew credentials or sign the application user in again. |
+| `403` | Check collection rules and service-key permissions. |
+| `409` | Resolve a concurrent edit or idempotency conflict. |
+| `429` | Inspect the error code for rate or quota limits before retrying. |
+| `503` | Retry later with bounded backoff when safe. |
+
+```python
+from cweb_forge import ForgeError
+
+try:
+    with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+        page = forge.collection('records').list()
+except ForgeError as error:
+    print(f'Forge request failed: {error.status} {error.code}')
+    # Share error.request_id with support if present; never log credentials.
+```
+
+HTTPX timeouts default to 15 seconds and can be configured with `timeout=30`
+on the client. These are transport timeouts, not a deadline for a complete
+multi-page iteration. HTTPS is required except on localhost; redirects and
+proxy settings inherited from environment variables are disabled.
+
+## Security and support
+
+Use narrowly scoped keys and rotate them if exposed. Keep keys, application-user
+tokens, private data and authentication headers out of logs and Git commits.
+For vulnerabilities, follow the
+[security policy](https://github.com/pystrap/cweb-forge-python/blob/main/SECURITY.md).
+
+Report SDK bugs through
+[GitHub issues](https://github.com/pystrap/cweb-forge-python/issues), with the
+SDK/Python versions and a minimal reproduction. For account or billing help,
+contact cWeb Support at [support@cweb.app](mailto:support@cweb.app).
+
+## Contributing
+
+Focused fixes, regression tests and documentation improvements are welcome.
+From a clone of this repository:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+Tests use mocked HTTP responses and do not require a live Forge account.
+Include tests for changed behavior and never submit customer data or credentials.
+
+## License
+
+[MIT](https://github.com/pystrap/cweb-forge-python/blob/main/LICENSE).
+Maintained by [PyStrap](https://pystrap.co.uk), the team behind cWeb.

cweb_forge-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "cweb-forge"
+version = "0.1.0"
+description = "Python SDK for cWeb Forge serverless data, for applications and notebooks"
+readme = "README.md"
+authors = [{name = "PyStrap"}]
+keywords = ["cweb", "forge", "serverless", "database", "sdk", "notebooks"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.28,<1"]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Database :: Front-Ends",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+[project.urls]
+Homepage = "https://cweb.app"
+Documentation = "https://github.com/pystrap/cweb-forge-python#readme"
+Source = "https://github.com/pystrap/cweb-forge-python"
+Issues = "https://github.com/pystrap/cweb-forge-python/issues"
+[tool.setuptools.packages.find]
+where = ["src"]
+[tool.setuptools.package-data]
+cweb_forge = ["py.typed"]

cweb_forge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cweb_forge-0.1.0/src/cweb_forge/__init__.py

@@ -0,0 +1,134 @@
+"""cWeb Forge: bounded HTTP clients, no hidden global credentials or retries."""
+import asyncio
+import json
+import re
+import uuid
+from urllib.parse import urlsplit
+import httpx
+
+__all__ = ['ForgeClient', 'AsyncForgeClient', 'ForgeError']
+
+
+class ForgeError(Exception):
+    def __init__(self, message, status=0, code='network_error', request_id=''):
+        super().__init__(message)
+        self.status, self.code, self.request_id = status, code, request_id
+
+
+def _endpoint(url):
+    p = urlsplit(url)
+    local = p.hostname in ('localhost', '127.0.0.1', '::1') or (p.hostname or '').endswith('.localhost')
+    if not p.hostname or (p.scheme != 'https' and not (p.scheme == 'http' and local)) or p.username or p.password or p.query or p.fragment:
+        raise ValueError('Use an HTTPS endpoint; HTTP is permitted only for local development.')
+    return url.rstrip('/')
+
+
+def _name(value):
+    if not re.fullmatch(r'[a-z][a-z0-9_]{0,63}', value):
+        raise ValueError('Invalid collection name.')
+    return value
+
+
+def _result(response):
+    if response.status_code == 204:
+        return None
+    try:
+        value = response.json()
+    except ValueError:
+        raise ForgeError('Forge returned an invalid response.', response.status_code, 'invalid_response')
+    if not response.is_success:
+        error = value.get('error', {})
+        raise ForgeError(error.get('message', 'Forge request failed.'), response.status_code,
+                         error.get('code', 'request_failed'), response.headers.get('X-Request-ID', ''))
+    return value
+
+
+class ForgeClient:
+    def __init__(self, endpoint: str, token=None, *, timeout: float = 15, transport=None):
+        self.endpoint, self.token = _endpoint(endpoint), token
+        self._http = httpx.Client(timeout=timeout, follow_redirects=False, trust_env=False, transport=transport)
+
+    def request(self, method, path, *, body=None, headers=None, params=None):
+        token = self.token() if callable(self.token) else self.token
+        auth = {'Authorization': 'Bearer ' + token} if token else {}
+        try:
+            return _result(self._http.request(method, self.endpoint + path, json=body, params=params,
+                           headers={**auth, **(headers or {})}))
+        except httpx.HTTPError:
+            raise ForgeError('Unable to complete the Forge request.') from None
+
+    def collection(self, name: str):
+        return Collection(self, name)
+
+    def close(self): self._http.close()
+    def __enter__(self): return self
+    def __exit__(self, *args): self.close()
+
+
+class Collection:
+    def __init__(self, client, name):
+        self.client, self.path = client, '/collections/' + _name(name) + '/documents'
+
+    def list(self, *, limit=50, after=None, field=None, equals=None):
+        params = {'limit': limit}
+        if after: params['after'] = after
+        if field: params.update(field=field, value=json.dumps(equals, allow_nan=False))
+        return self.client.request('GET', self.path, params=params)
+
+    def get(self, document_id):
+        return self.client.request('GET', self.path + '/' + str(uuid.UUID(str(document_id))))
+
+    def create(self, data, *, idempotency_key=None):
+        return self.client.request('POST', self.path, body=data, headers={'Idempotency-Key': idempotency_key or str(uuid.uuid4())})
+
+    def replace(self, document_id, data, *, version):
+        return self.client.request('PUT', self.path + '/' + str(uuid.UUID(str(document_id))), body=data, headers={'If-Match': f'"{version}"'})
+
+    def update(self, document_id, data, *, version):
+        return self.client.request('PATCH', self.path + '/' + str(uuid.UUID(str(document_id))), body=data, headers={'If-Match': f'"{version}"'})
+
+    def delete(self, document_id, *, version):
+        return self.client.request('DELETE', self.path + '/' + str(uuid.UUID(str(document_id))), headers={'If-Match': f'"{version}"'})
+
+    def iterate(self, **options):
+        after = None
+        while True:
+            result = self.list(after=after, **options)
+            yield from result['items']
+            cursor = result.get('next_cursor')
+            if not cursor: return
+            if cursor == after: raise ForgeError('Invalid pagination cursor.', code='invalid_response')
+            after = cursor
+
+
+class AsyncForgeClient:
+    def __init__(self, endpoint: str, token=None, *, timeout: float = 15, transport=None):
+        self.endpoint, self.token = _endpoint(endpoint), token
+        self._http = httpx.AsyncClient(timeout=timeout, follow_redirects=False, trust_env=False, transport=transport)
+
+    async def request(self, method, path, *, body=None, headers=None, params=None):
+        import inspect
+        token = self.token() if callable(self.token) else self.token
+        if inspect.isawaitable(token): token = await token
+        auth = {'Authorization': 'Bearer ' + token} if token else {}
+        try:
+            return _result(await self._http.request(method, self.endpoint + path, json=body, params=params, headers={**auth, **(headers or {})}))
+        except httpx.HTTPError:
+            raise ForgeError('Unable to complete the Forge request.') from None
+
+    def collection(self, name: str): return AsyncCollection(self, name)
+    async def close(self): await self._http.aclose()
+    async def __aenter__(self): return self
+    async def __aexit__(self, *args): await self.close()
+
+
+class AsyncCollection(Collection):
+    async def iterate(self, **options):
+        after = None
+        while True:
+            result = await self.list(after=after, **options)
+            for item in result['items']: yield item
+            cursor = result.get('next_cursor')
+            if not cursor: return
+            if cursor == after: raise ForgeError('Invalid pagination cursor.', code='invalid_response')
+            after = cursor

cweb_forge-0.1.0/src/cweb_forge.egg-info/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: cweb-forge
+Version: 0.1.0
+Summary: Python SDK for cWeb Forge serverless data, for applications and notebooks
+Author: PyStrap
+License-Expression: MIT
+Project-URL: Homepage, https://cweb.app
+Project-URL: Documentation, https://github.com/pystrap/cweb-forge-python#readme
+Project-URL: Source, https://github.com/pystrap/cweb-forge-python
+Project-URL: Issues, https://github.com/pystrap/cweb-forge-python/issues
+Keywords: cweb,forge,serverless,database,sdk,notebooks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28
+Dynamic: license-file
+
+# cWeb Forge · Python
+
+**Serverless data and authentication API for your next application.**
+
+Use cWeb Forge collections from Python backends, scripts and notebooks without
+building a separate data API. This is the official Python SDK for
+[cWeb Forge](https://cweb.app), with synchronous and asynchronous clients for
+applications on cWeb or any other host.
+
+- JSON document operations with collection access rules.
+- Cursor pagination, equality filters and streaming iteration over pages.
+- Version checks for concurrent edits and idempotency keys for create retries.
+- Backend service keys or application-user access tokens.
+- Works with Django, FastAPI, cWeb Studio and other Python notebook environments.
+
+[Getting started](#getting-started) · [Async usage](#async-usage) ·
+[Notebooks](#notebooks) · [Contributing](#contributing)
+
+## Installation
+
+Requires Python 3.10 or later.
+
+The first PyPI release is being prepared. Until it is available, clone this
+repository and install from its local path:
+
+```sh
+python -m pip install ./cweb-forge-python
+```
+
+Once published, install from PyPI:
+
+```sh
+python -m pip install cweb-forge
+```
+
+The package name is `cweb-forge`; import it as `cweb_forge`.
+
+## Getting started
+
+1. Create a Forge application in the [cWeb dashboard](https://portal.cweb.app)
+   and copy its API endpoint, including `/v1/`.
+2. Create a service key restricted to the collections and actions your backend
+   needs. Supply it as `CWEB_FORGE_KEY` through your environment or secret manager.
+3. Use the application's `records` collection to try the SDK:
+
+```python
+import os
+from cweb_forge import ForgeClient
+
+endpoint = 'https://my-app.forge.cweb.app/v1/'  # Replace with your endpoint.
+
+with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+    records = forge.collection('records')
+    created = records.create({'title': 'Draft', 'status': 'active'})
+    saved = records.update(
+        created['id'], {'title': 'Published'}, version=created['version']
+    )
+    print(saved['id'])
+```
+
+Use a context manager to close connections, or call `forge.close()` when
+finished. A service key may access records across application users according
+to its scopes. Never embed one in frontend code, mobile apps or shared notebooks.
+
+### Application-user tokens
+
+`token` can instead be an application user's access token or a callable that
+returns a fresh token before each request. The asynchronous client also accepts
+an async callable. Token validation and collection policies are enforced by the
+service; default owner access keeps a user's documents private to that user.
+
+The Python SDK does not perform interactive sign-in or automatically refresh a
+fixed token string. Your application's authentication integration must supply
+and refresh its tokens. Use the
+[JavaScript SDK](https://github.com/pystrap/cweb-forge-js#authentication) for
+browser sign-in. Never use a cWeb dashboard login token as a Forge application token.
+
+### Public reads without a token
+
+Set the collection's read policy to **Anyone (public)** under **Collections &
+rules**, then omit `token`:
+
+```python
+from cweb_forge import ForgeClient
+
+with ForgeClient('https://my-app.forge.cweb.app/v1/') as forge:
+    page = forge.collection('products').list(limit=50)
+    for document in page['items']:
+        print(document['data'])
+```
+
+Every document and field in that collection is public. Keep private data in
+separate collections. Anonymous writes are not supported, and public reads
+still consume the application's request allowances.
+
+## Working with documents
+
+Your JSON object is returned in `document['data']`, alongside metadata including
+`id`, `owner`, `version`, `created_at` and `updated_at`.
+
+| Method | Purpose |
+| --- | --- |
+| `list(limit=50, after=None, field=None, equals=None)` | Read a page with `items` and `next_cursor`. |
+| `get(document_id)` | Read one document. |
+| `create(data, idempotency_key=None)` | Create a document; a key is generated if omitted. |
+| `update(document_id, data, version=...)` | Patch the supplied fields. |
+| `replace(document_id, data, version=...)` | Replace the document's data. |
+| `delete(document_id, version=...)` | Delete a document. |
+| `iterate(limit=50, field=None, equals=None)` | Iterate over documents across successive pages. |
+
+Collection names start with a lowercase letter, contain lowercase letters,
+numbers or underscores, and have a maximum length of 64 characters. Document
+IDs are UUIDs returned by Forge.
+
+```python
+with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+    records = forge.collection('records')
+    page = records.list(limit=50, field='status', equals='active')
+    if page['next_cursor']:
+        next_page = records.list(
+            limit=50, after=page['next_cursor'], field='status', equals='active'
+        )
+
+    for document in records.iterate(limit=100, field='status', equals='active'):
+        print(document['id'])
+```
+
+Equality filters accept scalar field values. Page limits range from 1 to 100
+documents. Iteration fetches one page at a time; collecting every result into a
+list still uses memory for the entire result.
+
+Use the latest returned `version` for each update, replacement or deletion.
+On a `409` conflict, reload and resolve the change before retrying. To retry a
+create after an uncertain network outcome, reuse the same `idempotency_key`
+for that logical operation within the server's 24-hour window. The SDK does not
+automatically retry writes.
+
+## Async usage
+
+Use `AsyncForgeClient` in asynchronous applications. Await document operations,
+and use `async for` when iterating:
+
+```python
+import asyncio
+import os
+from cweb_forge import AsyncForgeClient
+
+async def main():
+    async with AsyncForgeClient(
+        'https://my-app.forge.cweb.app/v1/',
+        token=os.environ['CWEB_FORGE_KEY'],
+    ) as forge:
+        records = forge.collection('records')
+        created = await records.create({'title': 'Async example'})
+        print(created['id'])
+        async for document in records.iterate(limit=100):
+            print(document['id'])
+
+asyncio.run(main())
+```
+
+In notebooks with an existing event loop, use `await main()` instead of
+`asyncio.run(main())`. Close a manually managed async client with
+`await forge.close()`.
+
+## Notebooks
+
+The SDK can fetch data for pandas, DuckDB or your own analysis code. Those
+libraries are optional and installed separately. Start with a read-only key and
+a bounded sample:
+
+```python
+import os
+import pandas as pd
+from cweb_forge import ForgeClient
+
+# Configure this secret in the notebook environment; do not paste it into a cell.
+with ForgeClient(
+    'https://my-app.forge.cweb.app/v1/',
+    token=os.environ['CWEB_FORGE_KEY'],
+) as forge:
+    page = forge.collection('sales').list(limit=100)
+    frame = pd.DataFrame([document['data'] for document in page['items']])
+```
+
+This reads a page of JSON documents; it does not mount a database or automatically
+copy the whole collection into Studio's catalog. Do not save credentials or
+sensitive results in notebook outputs that you intend to share.
+
+## Errors and timeouts
+
+Catch `ForgeError` for API or transport failures. It includes `status`, `code`
+and `request_id`; network failures use status `0`.
+
+| Status | Suggested handling |
+| --- | --- |
+| `401` | Renew credentials or sign the application user in again. |
+| `403` | Check collection rules and service-key permissions. |
+| `409` | Resolve a concurrent edit or idempotency conflict. |
+| `429` | Inspect the error code for rate or quota limits before retrying. |
+| `503` | Retry later with bounded backoff when safe. |
+
+```python
+from cweb_forge import ForgeError
+
+try:
+    with ForgeClient(endpoint, token=os.environ['CWEB_FORGE_KEY']) as forge:
+        page = forge.collection('records').list()
+except ForgeError as error:
+    print(f'Forge request failed: {error.status} {error.code}')
+    # Share error.request_id with support if present; never log credentials.
+```
+
+HTTPX timeouts default to 15 seconds and can be configured with `timeout=30`
+on the client. These are transport timeouts, not a deadline for a complete
+multi-page iteration. HTTPS is required except on localhost; redirects and
+proxy settings inherited from environment variables are disabled.
+
+## Security and support
+
+Use narrowly scoped keys and rotate them if exposed. Keep keys, application-user
+tokens, private data and authentication headers out of logs and Git commits.
+For vulnerabilities, follow the
+[security policy](https://github.com/pystrap/cweb-forge-python/blob/main/SECURITY.md).
+
+Report SDK bugs through
+[GitHub issues](https://github.com/pystrap/cweb-forge-python/issues), with the
+SDK/Python versions and a minimal reproduction. For account or billing help,
+contact cWeb Support at [support@cweb.app](mailto:support@cweb.app).
+
+## Contributing
+
+Focused fixes, regression tests and documentation improvements are welcome.
+From a clone of this repository:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+Tests use mocked HTTP responses and do not require a live Forge account.
+Include tests for changed behavior and never submit customer data or credentials.
+
+## License
+
+[MIT](https://github.com/pystrap/cweb-forge-python/blob/main/LICENSE).
+Maintained by [PyStrap](https://pystrap.co.uk), the team behind cWeb.

cweb_forge-0.1.0/src/cweb_forge.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/cweb_forge/__init__.py
+src/cweb_forge/py.typed
+src/cweb_forge.egg-info/PKG-INFO
+src/cweb_forge.egg-info/SOURCES.txt
+src/cweb_forge.egg-info/dependency_links.txt
+src/cweb_forge.egg-info/requires.txt
+src/cweb_forge.egg-info/top_level.txt
+tests/test_client.py

cweb_forge-0.1.0/src/cweb_forge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cweb_forge-0.1.0/src/cweb_forge.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx<1,>=0.28

cweb_forge-0.1.0/src/cweb_forge.egg-info/top_level.txt

@@ -0,0 +1 @@
+cweb_forge

cweb_forge-0.1.0/tests/test_client.py

@@ -0,0 +1,29 @@
+import unittest
+import httpx
+from cweb_forge import ForgeClient, AsyncForgeClient, ForgeError
+
+URL = 'https://my-app.forge.cweb.app/v1/'
+
+class ClientTests(unittest.TestCase):
+    def test_headers_and_concurrency(self):
+        calls = []
+        def handler(request):
+            calls.append(request)
+            return httpx.Response(200, json={'id': 'example'})
+        with ForgeClient(URL, 'fg_secret', transport=httpx.MockTransport(handler)) as client:
+            client.collection('records').create({'a': 1}, idempotency_key='stable')
+            client.collection('records').update('00000000-0000-4000-8000-000000000001', {'a': 2}, version=1)
+        self.assertEqual(calls[0].headers['Idempotency-Key'], 'stable')
+        self.assertEqual(calls[1].headers['If-Match'], '"1"')
+        self.assertEqual(calls[0].headers['Authorization'], 'Bearer fg_secret')
+
+    def test_errors_and_redirects(self):
+        with ForgeClient(URL, transport=httpx.MockTransport(lambda r: httpx.Response(429, json={'error': {'message': 'Limit', 'code': 'quota_exceeded'}}))) as client:
+            with self.assertRaises(ForgeError) as result: client.collection('records').list()
+        self.assertEqual(result.exception.code, 'quota_exceeded')
+        with self.assertRaises(ValueError): ForgeClient('http://example.org')
+
+class AsyncTests(unittest.IsolatedAsyncioTestCase):
+    async def test_async_iteration(self):
+        async with AsyncForgeClient(URL, transport=httpx.MockTransport(lambda r: httpx.Response(200, json={'items': [{'id': '1'}], 'next_cursor': None}))) as client:
+            self.assertEqual([x async for x in client.collection('records').iterate()], [{'id': '1'}])