w6w 0.2.1__tar.gz

w6w-0.2.1/LICENSE

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

w6w-0.2.1/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.4
+Name: w6w
+Version: 0.2.1
+Summary: Typed, dependency-free Python client for the w6w workflow API.
+Author: w6w
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/w6w-io/w6w-wrappers/tree/main/python
+Project-URL: Repository, https://github.com/w6w-io/w6w-wrappers
+Project-URL: Issues, https://github.com/w6w-io/w6w-wrappers/issues
+Keywords: w6w,workflow,automation,api,client,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0; extra == "dev"
+Dynamic: license-file
+
+# w6w
+
+Typed Python client for the w6w workflow API.
+
+It is a thin wrapper: transport, auth, error mapping. Documents, variables,
+connections, workflows and runs — the same surface the Node SDK and the `w6w`
+CLI expose, at the same version. All three wrappers implement one shared
+contract and release together, so `w6w==X` gives you the same operations as
+`@w6w/sdk@X`.
+
+**Status: pre-release.** The full surface is in — `me`, `run`,
+`connections.list`, `workflows.list` / `workflows.run`, and the complete
+`documents.*` and `vars.*` CRUD. Below `1.0.0`, breaking changes may arrive in a
+minor bump — that grace ends at `1.0.0`.
+
+MIT licensed — see [LICENSE](./LICENSE).
+
+## Install
+
+```bash
+pip install w6w
+```
+
+Python 3.9 or newer.
+
+## Zero runtime dependencies
+
+`dependencies` in `pyproject.toml` is empty and stays empty. HTTP goes through
+`urllib.request` from the standard library — no `requests`, no `httpx`, no
+`aiohttp`.
+
+Two reasons, in order of importance:
+
+1. **A client library should never join a dependency fight.** Installing this
+   package cannot conflict with the versions you have already pinned.
+2. **It is the only honest choice for how this package is developed.** The
+   environment it is built in has no package installer available at all, so a
+   third-party HTTP or test dependency would make the package untestable by the
+   people writing it.
+
+The package is fully annotated and ships a [PEP 561](https://peps.python.org/pep-0561/)
+`py.typed` marker, so mypy and pyright see the types without a stub package.
+
+## Usage
+
+```python
+from w6w import W6wClient, ApiError
+
+client = W6wClient()                      # from the environment
+# …or explicitly, which always wins over the environment:
+client = W6wClient(base_url="https://api.example.com", token="tok_…")
+
+try:
+    identity = client.me()                # who am I, and what answered?
+except ApiError as err:
+    print(err.status, err.code, err.message)
+
+# What can I run? `run` is addressed by a conn_… / fn_… / ep_… / wf_… id, and
+# these two operations are how you discover one.
+connections = client.connections.list()
+workflows = client.workflows.list()
+```
+
+### Run anything addressable by a URN
+
+`run` returns a `kind`-tagged envelope — the parsed body, exactly as it arrived.
+Discriminate it before reading a field, because the arms use different field
+names on purpose (`value` vs `output` vs `runId` + `status`):
+
+```python
+import w6w
+
+env = client.run(
+    connections[0].id,                    # "conn_…"
+    action="send_message",                # which of the app's actions to invoke
+    payload={"channel": "#general", "text": "Hello from w6w"},
+)
+
+if w6w.is_action_run(env):
+    print(env["value"])                   # the action's return value
+```
+
+A `fn_…` or `ep_…` id runs the same way with no `action`; a `wf_…` id is
+enqueued and comes back `202` with `runId` and `status` — which is success, not
+an error. A `kind` this release has never heard of is handed back verbatim
+rather than raised, so a newer server cannot break an installed client.
+
+### Run a workflow, and optionally wait
+
+`workflows.run` is the typed path, and the only one that can wait for the result
+**server-side** — this package contains no polling loop of its own:
+
+```python
+run = client.workflows.run(workflows[0].id, wait=True, variables={"customerId": "cus_1"})
+
+# A failed run is DATA, not a raised error. `terminal` says whether it finished.
+if run.terminal and run.status == "failed":
+    print(run.error)
+elif run.terminal:
+    print(run.output)
+```
+
+### Documents and vars
+
+```python
+doc = client.documents.create("welcome", "# Hi", format="markdown")
+client.documents.update(doc.id, content="# Hello")
+client.documents.delete(doc.id)
+
+v = client.vars.create("sender_email", "string", "a@b.c")
+client.vars.update(v.id, value="c@d.e")
+```
+
+Documents are project-scoped (every operation takes an optional `project`);
+**variables are not** — they are scoped by tenant/subject only, so no `vars.*`
+signature has a `project` argument. The asymmetry is the server's, and this
+package documents it rather than papering over it with an argument the server
+ignores.
+
+`update` distinguishes *leave this field alone* from *set this field to null*:
+every patchable parameter defaults to `w6w.UNSET` (send nothing), and passing
+`None` explicitly sends JSON `null`.
+
+### Reaching an endpoint this version does not model
+
+`client.request` is public and returns `(status, body)` — the status comes back
+because a `202` is a normal outcome on this API, not an error. When any part of
+a path comes from the caller, build it with `w6w.path` rather than by
+concatenation; it percent-encodes every interpolated value:
+
+```python
+from w6w import path
+
+client.request("GET", path("/documents/by-key/{key}", key="notes/2026"))
+# -> GET https://api.example.com/documents/by-key/notes%2F2026
+```
+
+That is not defensive ceremony. Document keys are user-chosen and the server
+accepts almost anything, so an unencoded `"notes/2026"` becomes two path
+segments — a **different route**, answered with a `200` and no error anywhere.
+
+## Configuration
+
+Two environment variables, read once when a client is constructed:
+
+| Variable | Meaning |
+|---|---|
+| `W6W_BASE_URL` | The **origin** of your w6w API — e.g. `https://api.example.com`. The API is served at the root of that host, so the client appends nothing. There is no default. |
+| `W6W_TOKEN` | Your API token. Sent as `Authorization: Bearer <token>` on every request. |
+
+These variables are part of the published contract and are identical across all
+three wrappers.
+
+**Explicit constructor arguments always win over the environment.**
+`W6wClient(base_url=…, token=…)` overrides `W6W_BASE_URL` / `W6W_TOKEN`, and an
+argument you pass explicitly — including an empty string — is never quietly
+replaced by an environment variable behind your back.
+
+Credentials are per-client **instance state**, never module globals: two clients
+in one process can point at two servers with two tokens and not interfere.
+
+### `W6W_BASE_URL` is an origin
+
+The API is served at the **root** of its own host — `https://api.example.com/vars`,
+not `…/api/vars` — so nothing is appended. Trailing slashes never matter, and a
+path you configure is preserved verbatim, because it is indistinguishable from a
+real gateway prefix:
+
+| You set | The client uses |
+|---|---|
+| `https://api.example.com` | `https://api.example.com` |
+| `https://api.example.com/` | `https://api.example.com` |
+| `https://api.example.com///` | `https://api.example.com` |
+| `https://api.example.com/gw` | `https://api.example.com/gw` |
+
+> **Breaking in `0.2.0`.** The client used to append `/api`. If your
+> `W6W_BASE_URL` ends in `/api` because of that, **drop the suffix** — a stale
+> one now 404s on every call. It is not stripped for you: a configured path is
+> exactly how a deployment behind a gateway prefix is addressed.
+
+**A blank value is not a base URL.** An environment variable that is set but
+empty or whitespace-only is treated as **absent**: `W6W_BASE_URL=`,
+`W6W_BASE_URL="   "` and an unset `W6W_BASE_URL` all behave identically and all
+raise the same `ConfigError` naming the variable. (`export W6W_BASE_URL=`, a
+Dockerfile `ENV` with no build arg, and a CI variable whose template did not
+interpolate are the common cases, and they look unset in every log line.) The
+same rule applies to `W6W_TOKEN`.
+
+**It must be absolute.** `W6W_BASE_URL=/foo` or `W6W_BASE_URL=api.example.com`
+raises a `ConfigError` naming the variable, at construction — not a confusing
+"the server may be down" on the first request. Scheme and host, `http` or
+`https`.
+
+A client with no token can still be **constructed** — the error surfaces on the
+first request instead, so offline `--help`-style uses work. A client with no
+base URL raises immediately, at construction.
+
+**A token is validated as a header value.** A token containing a carriage
+return, newline or other control character raises a `ConfigError` before any
+request is made, because CR/LF in a header value is header injection — and the
+usual way this happens is entirely innocent: `W6W_TOKEN=$(cat token.txt)` keeps
+the file's trailing newline. The message names the offending codepoint and
+position and never echoes the token.
+
+## Errors
+
+Two exception types, and the split is deliberate:
+
+| Type | Means |
+|---|---|
+| `ConfigError` | The client was never in a position to make a request — no base URL, or no token. No HTTP exchange happened. |
+| `ApiError` | The server answered, or could not be reached. Carries `status`, `code`, `message` and `raw` (the parsed body, kept because error bodies carry fields the message drops). |
+
+`ApiError` has exactly three shapes: `status=0` / `code="network_error"` for a
+transport failure, `code="bad_response"` for a non-JSON body on a failing status
+(a proxy's HTML error page), and the server's own `code` / `message` for an error
+envelope. Classify by `status` and by a code *prefix* (`unknown_*` → 404,
+`invalid_*` → 400, `*_exists` → 409) rather than by an exhaustive list of codes:
+the server mints codes freely.
+
+A `424` is an app or upstream **execute-phase** failure, not a transport fault
+and not a server error — it is a 4xx on purpose. It reaches you with its code and
+body intact.
+
+## Tests
+
+The suite runs from a source checkout with **no installation step and no test
+runner to install** — `unittest` from the standard library:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -t . -v
+```
+
+Run it from the repository root. A single file:
+
+```bash
+PYTHONPATH=src python3 -m unittest tests.test_version -v
+```
+
+No test reaches the network. Client behaviour is exercised against an injected
+transport seam, never a live server — conformance against a running server is a
+separate, environment-dependent step and is not part of this suite.
+
+`tests/test_surface.py` is the exception in kind rather than in method: it reads
+the shared `endpoints.json` sitting **beside** this repository and asserts that
+every contracted operation is reachable under the symbol the contract names it —
+and that no namespace has grown one the contract does not have. It never
+vendors a copy, and it fails naming the path it looked for rather than skipping,
+because a guard that passes quietly when its input is missing is worse than no
+guard.
+
+### Why coverage is measured in CI and not locally
+
+Coverage is gated at **90 %**, enforced by CI, and there is deliberately no
+local coverage command.
+
+`coverage` is the one development-only tool this repo uses, and it is a
+third-party package. The environment this wrapper is developed in has **no
+package installer available** (`python3 -m pip` and `python3 -m ensurepip` both
+fail there), so `coverage` cannot be installed alongside the code it would
+measure. Rather than publish a local gate that nobody can actually run, the
+number is enforced where the tool does exist:
+
+```bash
+pip install -e '.[dev]'
+coverage run -m unittest discover -s tests -t .
+coverage report          # fail_under = 90, configured in pyproject.toml
+```
+
+The local bar is different and, for the thing that actually matters, stricter:
+**the suite runs with no install, every operation is exercised, and every error
+path has a test.** A percentage catches a whole operation going untested; it
+does not catch an operation tested badly. If you are adding an operation, the
+list above is your gate, not the number.
+
+## The surface
+
+Which operations exist is not decided in this repository. It is defined by the
+shared machine-readable contract **`endpoints.json`**, which all three w6w
+wrappers implement and which each one's conformance test reads directly — the
+same file, never a vendored copy. An operation missing from a wrapper, or one it
+has grown alone, is a failing test rather than a preference.
+
+Some operations may be marked `planned` in that contract: they are implemented
+and unit-tested here, but the corresponding server route is not live yet, so
+calling one against a server today returns `404`. The marker records **server**
+readiness, not wrapper completeness.
+
+## Versioning
+
+The version appears in three places — `src/w6w/_version.py`, `pyproject.toml`,
+and the wrappers' shared `VERSION` contract that sits beside this repository —
+and `tests/test_version.py` fails if any of them disagree. All three are
+written from the shared file at release time; none is ever bumped on its own.
+That is the mechanism behind "one surface, one version, released together".
+
+## Contributing
+
+Conventions worth knowing before the first patch:
+
+- **`src/` layout.** Tests import the package via `PYTHONPATH=src` (or an
+  install), never the working directory, so what is tested is what ships.
+- **The barrel rule.** Every public symbol is re-exported from `w6w/__init__.py`
+  and listed in `__all__`. Modules with a leading underscore are private
+  implementation detail and may move.
+- **Type annotations use `typing.Optional` / `Dict` / `List` form**, so they
+  stay valid on Python 3.9 even where they are evaluated at runtime; every
+  module also starts with `from __future__ import annotations`.
+- **Exactly one module reads the environment** — `src/w6w/_env.py`. `os.environ`
+  and `os.getenv` appear there and nowhere else; every other module receives
+  resolved configuration as a value, so no operation can acquire a hidden
+  dependency on ambient process state.
+- **Every caller-supplied value in a URL goes through `w6w.path`.** One
+  primitive at the transport seam, never a `quote()` at each call site — "every
+  call site remembered to encode" is not a property anyone can verify later.
+- **Stdlib only, in tests too.** No file in this repository imports a
+  third-party module. The transport is constructor-injected, so no test opens a
+  socket.
+- **The surface is not decided here.** Which operations exist, and what each is
+  called in each language, is pinned by the shared wrapper contract. Adding an
+  operation to this client alone would break the promise the three wrappers
+  make together.