document the proxy example

sdk/python/examples/proxy/README.md

@@ -0,0 +1,48 @@
+
+# zrok Python Proxy Example
+
+This demonstrates using the ProxyShare class to forward requests from the public frontend to a target URL.
+
+## Run the Example
+
+```bash
+LOG_LEVEL=INFO python ./proxy.py http://127.0.0.1:3000
+```
+
+Expected output:
+
+```txt
+2025-01-29 06:37:00,884 - __main__ - INFO - === Starting proxy server ===
+2025-01-29 06:37:00,884 - __main__ - INFO - Target URL: http://127.0.0.1:3000
+2025-01-29 06:37:01,252 - __main__ - INFO - Access proxy at: https://24x0pq7s6jr0.zrok.example.com:443
+2025-01-29 06:37:07,981 - zrok.proxy - INFO - Share 24x0pq7s6jr0 released
+```
+
+## Basic Usage
+
+```python
+from zrok.proxy import ProxyShare
+import zrok
+
+# Load the environment
+root = zrok.environment.root.Load()
+
+# Create a temporary proxy share (will be cleaned up on exit)
+proxy = ProxyShare.create(root=root, target="http://my-target-service")
+
+# Access the proxy's endpoints and token
+print(f"Access proxy at: {proxy.endpoints}")
+proxy.run()
+```
+
+## Creating a Reserved Proxy Share
+
+To create a share token that persists and can be reused, run the example `proxy.py --unique-name my-persistent-proxy`. If the unique name already exists it will be reused. Here's how it works:
+
+```python
+proxy = ProxyShare.create(
+    root=root,
+    target="http://127.0.0.1:3000",
+    unique_name="my-persistent-proxy"
+)
+```

sdk/python/sdk/zrok/zrok/README.md

@@ -1,47 +0,0 @@
-# Zrok Python SDK
-
-## Proxy Facility
-
-The SDK includes a proxy facility that makes it easy to create and manage proxy shares. This is particularly useful when you need to:
-
-1. Create an HTTP proxy with zrok
-2. Optionally reserve the proxy with a unique name for persistence
-3. Automatically handle cleanup of non-reserved shares
-
-### Basic Usage
-
-```python
-from zrok.proxy import ProxyShare
-import zrok
-
-# Load the environment
-root = zrok.environment.root.Load()
-
-# Create a temporary proxy share (will be cleaned up on exit)
-proxy = ProxyShare.create(root=root, target="http://my-target-service")
-
-# Access the proxy's endpoints and token
-print(f"Access proxy at: {proxy.endpoints}")
-print(f"Share token: {proxy.token}")
-```
-
-### Creating a Reserved Proxy Share
-
-To create a proxy share that persists and can be reused:
-
-```python
-# Create/retrieve a reserved proxy share with a unique name
-proxy = ProxyShare.create(
-    root=root,
-    target="http://my-target-service",
-    unique_name="my-persistent-proxy"
-)
-```
-
-When a `unique_name` is provided:
-
-1. If the zrok environment already has a share with that name, it will be reused
-2. If no share exists, a new reserved share will be created
-3. The share will be automatically cleaned up on exit if no `unique_name` is provided
-
-When a `unique_name` is not provided, the randomly generated share will be cleaned up on exit.