chore: import upstream snapshot with attribution

docs/md/how_to/python/join.md

@@ -0,0 +1,64 @@
+# Joining Tables
+
+`perspective.join()` creates a read-only `Table` by joining two source tables on
+a shared key column. The result is reactive — it updates automatically when
+either source table changes. See [`Join`](../../explanation/join.md) for
+conceptual details.
+
+## Basic Inner Join
+
+```python
+orders = perspective.table([
+    {"id": 1, "product_id": 101, "qty": 5},
+    {"id": 2, "product_id": 102, "qty": 3},
+    {"id": 3, "product_id": 101, "qty": 7},
+])
+
+products = perspective.table([
+    {"product_id": 101, "name": "Widget"},
+    {"product_id": 102, "name": "Gadget"},
+])
+
+joined = perspective.join(orders, products, "product_id")
+view = joined.view()
+json = view.to_json()
+```
+
+## Join Types
+
+Pass `join_type` to select inner, left, or outer join behavior:
+
+```python
+# Left join: all left rows, nulls for unmatched right columns
+left_joined = perspective.join(left, right, "id", join_type="left")
+
+# Outer join: all rows from both tables
+outer_joined = perspective.join(left, right, "id", join_type="outer")
+```
+
+## Reactive Updates
+
+The joined table recomputes automatically when either source table is updated:
+
+```python
+left = perspective.table([{"id": 1, "x": 10}])
+right = perspective.table([{"id": 2, "y": "b"}])
+
+joined = perspective.join(left, right, "id")
+view = joined.view()
+
+json = view.to_json()
+# [] — no matching keys yet
+
+right.update([{"id": 1, "y": "a"}])
+json = view.to_json()
+# [{"id": 1, "x": 10, "y": "a"}] — new match detected
+```
+
+## Async Client
+
+The async client has the same API:
+
+```python
+joined = await client.join(orders, products, "product_id", join_type="left")
+```