docs: split Python External Stream into source/sink pages

Refactor the single python-external-stream page into source/sink MDX
wrappers backed by three shared partials (basics, read, write), matching
the Kafka/Pulsar/NATS pattern. Add read- and write-side worked examples:
streaming generator, batch list, init/deinit lifecycle, local API
credential callback, materialized-view sink, and webhook POST. Drop
internal engine-version gates in favor of a single Timeplus Enterprise
3.2+ product note.

- New: docs/python-external-stream-source.mdx and -sink.mdx, plus shared
  partials under docs/shared/.
- Sidebar entries repointed; /python-external-stream redirects to
  /python-external-stream-source.
- Incoming links in docs/external-stream.md and
  docs/sql-create-external-stream.md updated to reference both pages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: yokofly

docs/external-stream.md

@@ -8,7 +8,7 @@ Timeplus supports 6 types of external streams:
 * [Kafka External Stream](/kafka-source)
 * [Pulsar External Stream](/pulsar-source)
 * [NATS JetStream External Stream](/nats-jetstream-source)
-* [Python External Stream](/python-external-stream), only available in Timeplus Enterprise
+* [Python External Stream Source](/python-external-stream-source) and [Sink](/python-external-stream-sink), only available in Timeplus Enterprise
 * [Timeplus External Stream](/timeplus-source), only available in Timeplus Enterprise
 * [Log External Stream](/log-stream) (experimental)
 

docs/python-external-stream-sink.mdx

@@ -0,0 +1,10 @@
+---
+id: python-external-stream-sink
+title: Python Sink
+---
+
+import ExternalPythonBasics from './shared/python-external-stream.md';
+import ExternalPythonWrite from './shared/python-external-stream-write.md';
+
+<ExternalPythonBasics />
+<ExternalPythonWrite />

docs/python-external-stream-source.mdx

@@ -0,0 +1,10 @@
+---
+id: python-external-stream-source
+title: Python Source
+---
+
+import ExternalPythonBasics from './shared/python-external-stream.md';
+import ExternalPythonRead from './shared/python-external-stream-read.md';
+
+<ExternalPythonBasics />
+<ExternalPythonRead />

docs/python-external-stream.md

@@ -0,0 +1,112 @@
+## Read Data from a Python External Stream
+
+The read function is the entry point Timeplus calls to pull rows from your Python code. It is **synchronous** (no `async`/`await`) and receives **no implicit arguments** — any configuration must arrive through the init function. Each value it produces is a row whose columns match the stream's schema in declared order; for a single-column stream you may yield bare scalars.
+
+### Streaming source (generator)
+
+Yield a row or a batch of rows at a time. The query stays alive as long as the generator does, which makes generators the right shape for clocks, polling loops, websocket feeds, message-bus consumers, and other long-lived sources.
+
+```sql
+CREATE EXTERNAL STREAM py_clock (tick uint32, label string)
+AS $$
+import time
+
+def py_clock():
+    n = 0
+    while True:
+        yield (n, "tick")
+        n += 1
+        time.sleep(1)
+$$
+SETTINGS
+    type = 'python',
+    mode = 'streaming';
+```
+
+`read_function_name` is omitted, so it defaults to the stream name `py_clock`. Setting `mode = 'streaming'` makes the engine reject a non-generator return value, which catches mistakes like returning a list early.
+
+### Batch source (list)
+
+Return a list of rows once. Use this shape for one-shot pulls — REST snapshots, file scans, or any source where a single call yields the full result.
+
+```sql
+CREATE EXTERNAL STREAM py_users (id int32, name string)
+AS $$
+import json
+import urllib.request
+
+def py_users():
+    with urllib.request.urlopen("https://api.example.com/users") as r:
+        payload = json.load(r)
+    return [(u["id"], u["name"]) for u in payload]
+$$
+SETTINGS
+    type = 'python',
+    mode = 'batch';
+```
+
+### Long-lived setup with init / deinit
+
+Open a client once, stash it on `builtins`, and tear it down at the end of the query. Init parameters arrive as a single string, so JSON is convenient when you have more than one value to pass.
+
+```sql
+CREATE EXTERNAL STREAM py_cookie_counter
+(
+  previous_cleanup_count int32,
+  secret_flavor string
+)
+AS $$
+import builtins, json
+
+def open_bakery(config):
+    builtins._tp_cookie_secret_flavor = json.loads(config)["flavor"]
+
+def close_bakery():
+    if hasattr(builtins, "_tp_cookie_secret_flavor"):
+        del builtins._tp_cookie_secret_flavor
+
+def serve_cookie_report():
+    return [(0, getattr(builtins, "_tp_cookie_secret_flavor", ""))]
+$$
+SETTINGS
+    type = 'python',
+    read_function_name = 'serve_cookie_report',
+    init_function_name = 'open_bakery',
+    init_function_parameters = '{"flavor":"double-chocolate"}',
+    deinit_function_name = 'close_bakery';
+```
+
+Remember that init and deinit run **per query**, not once per stream creation — the `builtins` state above is set up and torn down each time a query reads from `py_cookie_counter`. Use stream-specific `builtins` attribute names and delete them in deinit so later Python sessions do not see stale state.
+
+### Calling back to `timeplusd`
+
+The injected `__timeplus_local_api_user` and `__timeplus_local_api_password` globals let the read function authenticate to the same server without hard-coded credentials. The example below queries an internal stream over the REST interface and turns the result into a row.
+
+```sql
+CREATE EXTERNAL STREAM py_user_count (total int64)
+AS $$
+import base64, urllib.request
+
+def py_user_count():
+    creds = base64.b64encode(
+        f"{__timeplus_local_api_user}:{__timeplus_local_api_password}".encode()
+    ).decode()
+    req = urllib.request.Request(
+        "http://localhost:8123/?query=SELECT+count()+FROM+table(users)",
+        headers={"Authorization": f"Basic {creds}"},
+    )
+    with urllib.request.urlopen(req) as r:
+        return [(int(r.read().strip()),)]
+$$
+SETTINGS
+    type = 'python',
+    mode = 'batch';
+```
+
+Treat `__timeplus_local_api_password` as a secret — do not log it, do not echo it back into output rows, and do not pass it into subprocesses.
+
+### Cancellation and errors
+
+When a query is cancelled (for example by `KILL QUERY` or by closing the client), the running Python code receives a `KeyboardInterrupt`. Streaming generators stop at the next yield point; long-blocking calls inside C extensions may delay the interrupt until they return.
+
+If the read function raises, the query fails and the Python traceback is included in the error response — wrap recoverable errors inside the function and decide explicitly whether to re-raise or continue.

docs/shared/python-external-stream-read.md

@@ -0,0 +1,84 @@
+## Write Data to a Python External Stream
+
+The write function is invoked once per chunk, not once per row. Its arguments are **column-oriented**: one Python list per output column, in declared order, all of equal length. Iterate with `zip` to recover row tuples.
+
+### Sink basics
+
+```sql
+CREATE EXTERNAL STREAM py_metric_sink (host string, value float32)
+AS $$
+def py_metric_sink(host, value):
+    for h, v in zip(host, value):
+        print(f"{h}={v}")
+$$
+SETTINGS type = 'python';
+```
+
+Insert a few rows:
+
+```sql
+INSERT INTO py_metric_sink (host, value) VALUES ('a', 1.0), ('b', 2.0);
+```
+
+Behind the scenes Timeplus calls `py_metric_sink(['a', 'b'], [1.0, 2.0])` — one call carrying both rows. A larger INSERT or a downstream query that delivers many chunks results in one call per chunk.
+
+If `write_function_name` is omitted Timeplus uses `read_function_name` (which itself defaults to the stream name), so the Python function above only needs to be named once.
+
+### Materialized view → external stream
+
+Routing a continuous query into a sink is the most common production pattern. Define the sink once, then point a materialized view at it:
+
+```sql
+CREATE EXTERNAL STREAM py_alert_sink (host string, value float32)
+AS $$
+def py_alert_sink(host, value):
+    for h, v in zip(host, value):
+        notify(h, v)   # your notifier
+$$
+SETTINGS type = 'python';
+
+CREATE MATERIALIZED VIEW high_value_alerts INTO py_alert_sink AS
+  SELECT host, value FROM metrics WHERE value > 100;
+```
+
+The materialized view feeds chunks into the sink as they are produced; each chunk becomes one call to `py_alert_sink`.
+
+### Custom protocol example: webhook POST
+
+Load the destination URL in init, reuse that configuration for every chunk, and clear it in deinit. Init parameters carry the URL so the Python body is reusable across environments. To pool an actual HTTP connection, swap `urllib` for a session-aware client (for example `requests.Session()`) and stash the session itself on `builtins`.
+
+```sql
+CREATE EXTERNAL STREAM py_webhook (event_id string, body string)
+AS $$
+import builtins, json, urllib.request
+
+def open_client(config):
+    builtins._tp_webhook = json.loads(config)["url"]
+
+def close_client():
+    if hasattr(builtins, "_tp_webhook"):
+        del builtins._tp_webhook
+
+def post_event(event_id, body):
+    for eid, b in zip(event_id, body):
+        req = urllib.request.Request(
+            builtins._tp_webhook,
+            data=json.dumps({"id": eid, "body": b}).encode(),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(req).read()
+$$
+SETTINGS
+    type = 'python',
+    init_function_name = 'open_client',
+    init_function_parameters = '{"url":"https://hooks.example.com/notify"}',
+    deinit_function_name = 'close_client',
+    write_function_name = 'post_event';
+```
+
+Replace `urllib` with any HTTP, S3, queue, or proprietary client your environment ships with. Manage Python dependencies through the [Python UDF](/py-udf) library configuration — the same runtime backs both features.
+
+### Failure behavior
+
+If the write function raises, the INSERT fails and the Python traceback is included in the error response. Side effects already performed by your Python code (HTTP requests sent, files written, queue messages published) are **not** rolled back by Timeplus — design idempotent writes, or batch your side effect inside a single transactional call your downstream system controls.