feat(python): add Python Tasks TUI quickstart

README.md

@@ -53,6 +53,7 @@ build and run them.
 - [Go TUI](go-tui/README.md)
 - [Javascript TUI](javascript-tui/README.md)
 - [Javascript Web](javascript-web/README.md)
+- [Python TUI](python-tui/README.md)
 - [React Native](react-native/README.md)
 - [React Native Expo](react-native-expo/README.md)
 - [Rust TUI](rust-tui/README.md)

justfile

@@ -33,3 +33,31 @@ tools: cmdline_tools
     @echo "Installing tools"
     {{cmdline_tools_dir}}/latest/bin/sdkmanager --install 'build-tools;35.0.0'
     {{cmdline_tools_dir}}/latest/bin/sdkmanager --install 'platforms;android-34'
+
+# Runs the Python TUI quickstart
+python-tui:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    cd python-tui
+    if command -v uv >/dev/null 2>&1; then
+        uv run --with dittolive-ditto main.py
+    else
+        [[ -d .venv ]] || python3 -m venv .venv
+        .venv/bin/python -m pip install --quiet -e .
+        .venv/bin/python main.py
+    fi
+
+# Runs the Python TUI quickstart's credential-free CRUD self-test
+python-tui-smoke:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    cd python-tui
+    if command -v uv >/dev/null 2>&1; then
+        uv run --with dittolive-ditto main.py --smoke
+    else
+        [[ -d .venv ]] || python3 -m venv .venv
+        .venv/bin/python -m pip install --quiet -e .
+        .venv/bin/python main.py --smoke
+    fi

python-tui/.env.sample

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# Copy this file from ".env.sample" to ".env", then fill in these values
+# A Ditto Database ID, development token, and server URL can be obtained from
+# https://portal.ditto.live
+DITTO_DATABASE_ID=""
+DITTO_DEVELOPMENT_TOKEN=""
+DITTO_SERVER_URL=""

python-tui/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+ditto-python-tui-*/
+*.egg-info/
+uv.lock

python-tui/README.md

@@ -0,0 +1,103 @@
+# Ditto Python Quickstart App 🐍
+
+This directory contains Ditto's quickstart app for the Python SDK.
+This app is a console application that manages a todo list that syncs
+between multiple peers.
+
+It shares the `tasks` collection schema with every other quickstart app in
+this repository, so it syncs with the Swift, Kotlin, Go, Rust, and JavaScript
+quickstarts.
+
+## Requirements
+
+- **Python 3.10 or later.** The SDK is tested against 3.10–3.13; 3.14 also
+  works. See the [Python Compatibility page](https://docs.ditto.live/sdk/latest/compatibility/python).
+- A Ditto [Portal][0] account with a Database configured for **Development**
+  authentication.
+
+[0]: https://portal.ditto.live
+
+The Ditto Python SDK ships prebuilt wheels that bundle the native library, so
+there is no separate shared-library download step.
+
+## Getting Started
+
+Find your Database ID, Development Token, and Server URL in the
+[Ditto Portal][0], then create a `.env` file in this directory:
+
+```bash
+cp .env.sample .env
+```
+
+```bash
+DITTO_DATABASE_ID="your-database-id"
+DITTO_DEVELOPMENT_TOKEN="your-development-token"
+DITTO_SERVER_URL="your-server-url"
+```
+
+Alternatively, set them as environment variables, or use the shared `.env` at
+the root of this repository — the app checks this directory first, then the
+repo root.
+
+## Running
+
+Using [uv][1] (recommended — it installs Python and dependencies for you):
+
+```bash
+uv run --with dittolive-ditto main.py
+```
+
+[1]: https://docs.astral.sh/uv/
+
+Or with a virtual environment and pip:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install dittolive-ditto
+python main.py
+```
+
+### Commands
+
+Once running, the app accepts these commands:
+
+| Command | Description |
+| --- | --- |
+| `add <title>` | Create a task |
+| `done <n>` | Toggle a task's completed state |
+| `edit <n> <title>` | Rename a task |
+| `del <n>` | Delete a task |
+| `list` | Refresh the list |
+| `help` | Show help |
+| `quit` | Exit |
+
+Press Enter (or type `list`) to refresh and pick up changes made by other
+peers.
+
+Pass `--verbose` to see the SDK's own logs, which are suppressed by default so
+they don't scribble over the console UI.
+
+## Sync Data Offline
+
+1. Launch the application on multiple devices, or alongside another quickstart
+   app.
+2. Disconnect from your WiFi network while keeping WiFi enabled on the device,
+   to allow for LAN connections.
+3. Add, edit, and delete tasks and experience offline collaboration!
+
+## Self-test
+
+To verify your installation without any credentials or network access:
+
+```bash
+uv run --with dittolive-ditto main.py --smoke
+```
+
+This opens a temporary local peer and runs the full insert / update / rename /
+delete path, asserting that the store observer reports each change.
+
+Note that `--smoke` does **not** start sync. Starting sync requires an
+activated instance — without a license token the SDK raises
+`DittoError <activation>`. The local store, subscriptions, and observers all
+work regardless; only replication with other peers needs activation.