lodol 0.2.0__tar.gz

lodol-0.2.0/LICENSE

@@ -0,0 +1,185 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of such
+entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the purposes
+of this definition, "submitted" means any form of electronic, verbal, or
+written communication sent to the Licensor or its representatives, including
+but not limited to communication on electronic mailing lists, source code
+control systems, and issue tracking systems that are managed by, or on behalf
+of, the Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise designated
+in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed by
+their Contribution(s) alone or by combination of their Contribution(s) with the
+Work to which such Contribution(s) was submitted. If You institute patent
+litigation against any entity (including a cross-claim or counterclaim in a
+lawsuit) alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent
+licenses granted to You under this License for that Work shall terminate as of
+the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any
+part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a
+whole, provided Your use, reproduction, and distribution of the Work otherwise
+complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright 2026 Lodol
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

lodol-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# The tests ship with the source, whole, so they can be run from it.
+graft tests
+global-exclude __pycache__
+global-exclude *.py[cod]

lodol-0.2.0/PKG-INFO

@@ -0,0 +1,367 @@
+Metadata-Version: 2.4
+Name: lodol
+Version: 0.2.0
+Summary: Run your Lodol workflows from Python: start runs, wait for them, and answer approvals
+Author: Lodol
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://lodol.com
+Project-URL: Documentation, https://docs.lodol.com
+Project-URL: Source, https://github.com/LodolAI/lodol-python
+Project-URL: Issues, https://github.com/LodolAI/lodol-python/issues
+Project-URL: Changelog, https://github.com/LodolAI/lodol-python/blob/main/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.15
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx2<3,>=2.14.0
+Requires-Dist: anyio<5,>=4.15.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=7.1.0; extra == "test"
+Requires-Dist: trio>=0.34.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: black==26.10.1; extra == "lint"
+Requires-Dist: mypy==2.4.0; extra == "lint"
+Requires-Dist: pylint==4.1.3; extra == "lint"
+Provides-Extra: dev
+Requires-Dist: lodol[lint,test]; extra == "dev"
+Dynamic: license-file
+
+# Lodol for Python
+
+Run your Lodol workflows from Python: start runs, wait for them, follow their history, and answer the approvals they ask for.
+
+```bash
+pip install lodol
+```
+
+Python 3.10 or later.
+
+## Quickstart
+
+Create an API key in Lodol under **Settings > API Keys**, then:
+
+```bash
+export LODOL_API_KEY="sk_live_..."
+```
+
+```python
+from lodol import Lodol
+
+lodol = Lodol()
+
+run = lodol.workflows.run("665f...", inputs={"client": "Acme"}, wait=True)
+print(run.outputs)  # {"total": 1250}
+```
+
+That starts the workflow, waits for it to finish, and gives you what it handed back: `run.outputs` holds each output the workflow declares, by name. If the run fails or is stopped, it raises `RunFailedError` instead, so a script never carries on as if it worked.
+
+Make one `Lodol()` and reuse it. It keeps connections open between calls and can be shared between threads.
+
+## Run a workflow
+
+```python
+workflow = lodol.workflows.get("665f...")
+
+for workflow_input in workflow.inputs:
+    print(workflow_input.name, workflow_input.type, workflow_input.required)
+for output in workflow.outputs:
+    print(output.name, output.type)  # what run.outputs will hold
+
+run = lodol.workflows.run(workflow, inputs={"client": "Acme", "month": "2026-05"})
+print(run.id, run.status)  # "683b...", "queued"
+```
+
+Without `wait=True`, `run` returns as soon as the run is queued. A run started while the workspace already has as many going as its plan allows comes back `queued` too, and starts when one of them finishes. A workflow's `id` stays the same when it's edited, so it's safe to store.
+
+**Inputs** are given by name and converted to each input's type, so `"21"` reaches a number input as `21`, and an optional input you leave out takes its default. Dates, times and `Decimal`s are sent as text Lodol reads (`date(2026, 5, 1)` becomes `"2026-05-01"`). An input the workflow doesn't declare, a missing required one, or a value of the wrong type raises `BadRequestError` naming the input, and nothing runs.
+
+**Running something exactly once.** A retried request never starts a second run. To make sure a run happens once even across separate attempts, such as a nightly job that may be restarted, pass the same `idempotency_key` each time:
+
+```python
+lodol.workflows.run(
+    "665f...",
+    inputs={"client": "Acme", "month": "2026-05"},
+    idempotency_key="monthly-report:acme:2026-05",
+)
+```
+
+Within 24 hours, the same key with the same inputs returns the run it already started, even if the first attempt is still under way. The same key with different inputs raises `UnprocessableEntityError`. Any text up to 256 characters works as a key.
+
+**Workflows that start themselves.** A workflow that starts from its own trigger or schedule, which `workflow.starts_from_trigger` says, doesn't run to an end: running it sets it listening, and each event it catches starts a run of its own, which `runs.list` lists. The listening run has `run.is_trigger_listener` set, and its status reads `"running"` for as long as it listens. Waiting on it, with `wait=True` or `runs.wait`, returns it at once, with a warning, since there's no end to wait for.
+
+## Wait for a run
+
+```python
+from lodol import RunFailedError, WaitTimeoutError
+
+try:
+    run = lodol.runs.wait("683b...", timeout=600)
+except RunFailedError as error:
+    print("It didn't work:", error.run.error)
+except WaitTimeoutError:
+    print("Still going after 10 minutes. It carries on in Lodol.")
+else:
+    print(run.outputs)
+    for step in run.steps or []:
+        print(step.index, step.status, step.result)
+```
+
+`wait` checks on the run often at first, then less often, at most every 10 seconds, and never faster than your plan's API allowance (the Free plan's 5 requests a minute means a check every 12 seconds). Rate limits and brief outages don't end a wait: it slows down and keeps going, and gives up only when `timeout` passes, or after five minutes without a successful check.
+
+The finished run comes with its outputs (`run.outputs`) and its step results (`run.steps`). An output the run never set is `None`. `RunFailedError` carries the run too, as `error.run`, so you can see which step failed. If the run has finished but its step results can't be fetched in time, you get the run without them rather than an error. Without a `timeout`, `wait` waits as long as the run takes, including while it waits for someone to answer an approval.
+
+Each step's `status` is one of `StepStatus`: `"completed"`, `"failed"`, `"continued"` (it failed, but its setting let the run carry on; `step.error` says what went wrong) or `"skipped"` (it's turned off, so it has no result, and `step.reason` says so). A step that retried says how many tries it took in `step.attempts`.
+
+## Retry a failed run
+
+```python
+from lodol import RunFailedError
+
+try:
+    run = lodol.workflows.run("5c3d...", wait=True)
+except RunFailedError as error:
+    print(error.run.error)  # "The accounting system didn't answer"
+    # Once it's back, pick up at the step that failed:
+    run = lodol.runs.retry(error.run, wait=True)
+
+print(run.outputs)  # {"synced": 12}
+```
+
+A retry is a new run, with the data the failed one started with (its inputs, or the event its trigger caught), and its `retry_of` is the failed run's `id`. By default it picks up at the step that failed, without running the steps before it again, so what they did (an email sent, a row added) isn't done twice. If the workflow has been edited since, the retry runs it as it is now when the steps before the one that failed are unchanged, so a fix to that step is picked up. `from_start=True` runs the whole workflow again instead. `wait`, `timeout` and `idempotency_key` work as they do for `workflows.run`.
+
+`runs.get(run).retry_options` says which retries a failed run offers. A run that didn't fail can't be retried, nor can one a run calling its workflow started (retry that run instead), and one that failed before Lodol kept where runs fail can only be retried from the start. Asking for a retry a run doesn't offer raises `ConflictError` with `code` `"run_not_retryable"`.
+
+## Follow runs
+
+```python
+for run in lodol.runs.list(workflow="665f...", limit=20):
+    print(run.created_at, run.status)
+```
+
+Runs come newest first. Loop over the result and pages are fetched as you go, so stopping early costs nothing extra. Leave out `limit` to go through all of them, and `workflow` to see every workflow's runs. Listed runs leave out `outputs` and `steps`; `runs.get` has them. A failed run says why in `run.error`, listed or not.
+
+```python
+from datetime import date
+
+for run in lodol.runs.list(status="failed", started_from=date(2026, 10, 1)):
+    print(run.started_at, run.workflow_name, run.error)
+```
+
+`status` takes one status or several (`status=["failed", "stopped"]`). `started_from` and `started_to` bound when runs started, `started_to` itself left out: a `date` is the start of that day, UTC, and a `datetime` without a timezone is taken as UTC. `search` finds runs by their workflow's name or a value in their data, such as a client's name in their inputs. A status runs can't be listed by, such as a typo, raises `ValueError` before anything is sent, rather than quietly listing every run.
+
+```python
+run = lodol.runs.get("683b...", include_steps=True)
+lodol.runs.stop(run)
+```
+
+`run.workflow_id` is the workflow's `id`. `run.version_id` is the version of the workflow that ran, which changes as the workflow is edited. Times are timezone-aware `datetime`s.
+
+Stopping a run doesn't undo the steps it already finished. `stop` returns the run, as `runs.get` would, with status `"stopping"` while it finishes the step it's on, or `"stopped"`. If the run had already finished, `stop` returns it as it finished rather than raising.
+
+```python
+run = lodol.runs.get("683b...")
+lodol.runs.stop(run)
+lodol.runs.delete(run)
+```
+
+Deleting a run removes it from the history, as deleting it in Lodol does, along with the runs it started: its trigger's, or the workflows it called. It can't be undone. A run still going has to be stopped first, or deleting it raises `ConflictError` with `code` `"run_not_finished"`. It needs a key with the **Delete runs** scope, which isn't ticked by default, made by a member who's allowed to delete runs. Like a workflow delete, it's never sent twice.
+
+## Answer approvals
+
+A workflow's **Request approval** step pauses its run until someone answers. Your own system can answer instead of a person in Lodol:
+
+```python
+run = lodol.workflows.run("4e8d...")
+
+approval = lodol.approvals.wait_for(run)  # until the run asks
+if approval is not None:
+    print(approval.title)  # "Pay invoice #4471?"
+    lodol.approvals.approve(approval, comment="Matches the purchase order")
+
+run = lodol.runs.wait(run)
+print(run.outputs)  # {"paid": True}
+```
+
+`wait_for` waits until the run asks for an answer and returns the request it's waiting on, or `None` if the run succeeds without asking. It paces itself as `runs.wait` does, raises `RunFailedError` if the run fails or is stopped first, and takes a `timeout` too. A run can ask more than once: call `wait_for` again after each answer. A workflow that starts from its own trigger never asks itself, since the runs its events start do, so `wait_for` returns `None` for it at once, with a warning.
+
+To answer whatever is waiting, from any run:
+
+```python
+for approval in lodol.approvals.list():  # pending ones, newest first
+    print(approval.title, approval.details, approval.workflow_name)
+
+    if approval.kind == "reply":
+        lodol.approvals.reply(approval, "The PO number is 4471")
+    else:
+        lodol.approvals.approve(approval, comment="Matches the purchase order")
+        # or lodol.approvals.reject(approval, comment="Wrong amount")
+```
+
+The run carries on as soon as it's answered. An answer sent with an API key is recorded as that key's. `approvals.list(status="all")` includes answered requests, with `approval.decision` saying who answered, when and how. `approvals.list(run=...)` lists one run's requests, and `workflow=` one workflow's.
+
+A request that's no longer pending can't be answered: you get `ConflictError`, whose `code` says what happened to it. `"approval_already_answered"`: someone answered it first. `"approval_expired"`: nobody answered in time, so it closed, or the step's time limit decided it automatically. `"approval_withdrawn"`: the run was stopped, or its workflow deleted, before anyone answered.
+
+## Workflows
+
+```python
+workflows = lodol.workflows.list()
+drafts = [workflow for workflow in workflows if workflow.is_draft]
+
+deleted = lodol.workflows.delete("665f...")
+```
+
+Deleting removes the workflow and every version of it, as deleting it in Lodol does: runs in progress stop, and its trigger or schedule stops listening. It can't be undone. Its past runs stay readable. It needs a key with the **Delete workflows** scope, which isn't ticked by default, made by a member who's allowed to delete workflows.
+
+A delete is never sent twice. If it times out, check with `lodol.workflows.get(...)` before trying again, since it may have happened.
+
+## Create and change workflows
+
+```python
+program = {
+    "kind": "Program",
+    "version": 1,
+    "body": [
+        {
+            "kind": "ExprStmt",
+            "expr": {
+                "kind": "DisplayBuiltIn",
+                "value": {"kind": "Literal", "value": "Hello from Lodol"},
+            },
+        }
+    ],
+}
+
+check = lodol.workflows.validate(program)  # saves nothing
+if not check.valid:
+    raise ValueError(check.error)
+
+workflow = lodol.workflows.create("Say hello", program, description="A first workflow")
+print(workflow.url)  # where to open it in Lodol
+
+workflow = lodol.workflows.edit(
+    workflow,
+    [{"op": "replace", "path": "/body/0/expr/value/value", "value": "Hello again"}],
+)
+workflow = lodol.workflows.update(workflow, name="Say hello again")
+```
+
+A workflow's steps are its `program`, the same structure `workflows.get(...).program` gives you. `validate` checks one without saving it: `check.error` says what to fix, and for a valid program, `check.warnings` names likely mistakes. It checks the program, not what the key's member may use (connections, and the workflows it calls), so a program that passes can still be refused when saved. `create` saves a new workflow, published, and private to the key's member until they share it in Lodol. It doesn't run it. A program Lodol can't save raises `BadRequestError` with `code` `"invalid_workflow"`, and nothing is saved.
+
+`update` replaces a workflow's `program`, `name` or `description`, leaving the rest as it is, and `edit` changes its program with JSON Patch operations (`"replace"`, `"add"` or `"remove"`), applied in order to the program as it is now. Each is saved as an edit in Lodol is: as a new version, or, when the workflow was saved within the last few minutes, over that version; `workflow.version_id` names the version saved. Saving pauses the trigger of a workflow that was listening, and `workflow.trigger_paused` says so: run it again to set it listening on the new version. After any save, `workflow.apps_to_connect` names the apps it uses that the key's member has yet to connect in Lodol, which it can't run without.
+
+These need a key with the **Create and edit workflows** scope (`workflows:write`), which is ticked by default, made by a member allowed to create or edit workflows. A save is never made twice: a retried request gets back the workflow the first one saved.
+
+## Errors
+
+When Lodol or the network says no, the SDK raises a `LodolError`. Errors from the API carry Lodol's own explanation as their message, and `code`, a stable name for what went wrong (such as `"run_already_finished"`): decide what to do from `code`, since the wording may change. `request_id` names the request; it's also in the error's text, so quote that when you contact Lodol's support. A call that can't be made as written (inputs that aren't a dict, a timeout that isn't a number) raises `TypeError` or `ValueError` before anything is sent.
+
+| Exception | When | What to do |
+| --- | --- | --- |
+| `RunFailedError` | A run you waited for failed or was stopped | Look at `error.run` |
+| `WaitTimeoutError` | A run wasn't finished within `timeout` | Wait again, or stop it. The run carries on |
+| `BadRequestError` | The request was refused, such as inputs that don't fit | Read the message: it names the problem |
+| `AuthenticationError` | The key is missing, wrong, revoked or expired | Check `LODOL_API_KEY` |
+| `PermissionDeniedError` | The key's scopes, or its creator's role, don't allow this | Give the key the scope, or use another key |
+| `NotFoundError` | No such workflow, run or approval in this workspace | Check the id |
+| `ConflictError` | An approval was already answered, expired or was withdrawn (`code` says which); or Lodol was still working on an earlier attempt of a request after five minutes | For an approval, nothing. Otherwise check before trying again: the message has the key to retry with |
+| `RunLimitError` | This month's runs are used up | Runs come back at `error.resets_at` |
+| `RateLimitError` | Too many requests, for longer than the SDK waits on its own | Wait `error.retry_after` seconds |
+| `APIConnectionError`, `APITimeoutError` | Lodol couldn't be reached, didn't answer, or had a certificate that couldn't be verified | Try again later; for a certificate, see the message |
+
+## What happens automatically
+
+- **Retries.** A request that fails for a passing reason (a dropped connection, a server error, a rate limit that clears within a minute) is sent again, up to `max_retries` times, with growing pauses. Only requests that can't take effect twice are retried: reads, and checking a workflow; runs, run retries, stops, approval answers and workflow saves, which carry an idempotency key; and anything a rate limit refused, since Lodol refuses before doing anything. A delete that fails otherwise, and limits that last longer, are reported at once.
+- **Idempotency keys.** Every run, run retry, stop, approval answer and workflow save gets one, so a retry can never start a second run, answer twice or save twice. If a retry finds Lodol still working on the first attempt, it waits for that, up to five minutes, rather than starting again.
+- **Timeouts.** Each request may take 30 seconds (`timeout`). Waiting for a run has its own `timeout`.
+- **Security.** Your key is only sent over HTTPS, except to Lodol Local on your own machine, which is reached directly, never through a proxy. It never appears in logs or reprs.
+
+## Async
+
+```python
+from lodol import AsyncLodol
+
+async with AsyncLodol() as lodol:
+    run = await lodol.workflows.run("665f...", inputs={"client": "Acme"}, wait=True)
+
+    async for approval in lodol.approvals.list():
+        print(approval.title)
+```
+
+`AsyncLodol` does everything `Lodol` does, with every call awaited and lists looped over with `async for`. It works with asyncio and trio.
+
+## Lodol Local
+
+Point the client at your own installation:
+
+```python
+from lodol import Lodol
+
+lodol = Lodol(base_url="http://localhost:3901")
+```
+
+or set `LODOL_BASE_URL`. Plain `http://` is allowed only for this machine (`localhost`, or `host.docker.internal` from a container); anything else must be `https://`.
+
+## Settings
+
+| Argument | Environment variable | Default |
+| --- | --- | --- |
+| `api_key` | `LODOL_API_KEY` | (required) |
+| `base_url` | `LODOL_BASE_URL` | `https://api-prod.lodol.com/api/v1` |
+| `timeout` | | `30` seconds per request |
+| `max_retries` | | `2` |
+| `http_client` | | Your own `httpx2.Client` (or `httpx2.AsyncClient`) for proxies, custom certificates or tests |
+
+Proxies and custom certificates are also picked up from the usual environment variables (`HTTPS_PROXY`, `SSL_CERT_FILE`).
+
+## Logging
+
+Set `LODOL_LOG=info` to see retries and what runs you're waiting for are doing, or `LODOL_LOG=debug` to see every request too. Or configure the `lodol` logger with Python's `logging`. Requests are logged by method, path and status only, never with your key or the inputs you send.
+
+## Testing your code
+
+Give the client an `httpx2` mock transport and answer as Lodol would:
+
+```python
+import httpx2
+from lodol import Lodol
+
+
+def fake_lodol(request: httpx2.Request) -> httpx2.Response:
+    if request.url.path.endswith("/run-async"):
+        return httpx2.Response(202, json={"execution_id": "683b", "status": "queued"})
+    return httpx2.Response(404, json={"error": "Workflow not found"})
+
+
+lodol = Lodol(
+    api_key="sk_live_test",
+    http_client=httpx2.Client(transport=httpx2.MockTransport(fake_lodol)),
+)
+```
+
+Models are plain data, so you can also build them directly: `Run(id="683b", status="success")`. They can be compared, hashed and pickled, and so can the SDK's errors.
+
+## Endpoints the SDK doesn't cover yet
+
+```python
+body = lodol.request("GET", "/approvals", params={"status": "all"})
+```
+
+`request` reaches any Developer API endpoint and returns its JSON. Errors raise as they do everywhere else. A write is retried only when you give it an `idempotency_key`.
+
+## Upgrading from 0.1
+
+0.2 renames executions to runs, to match Lodol, and changes a few behaviors. See [CHANGELOG.md](CHANGELOG.md) for the full list.