docs: python & fix some rust (#930)

Author: abcxff

README.md

@@ -131,7 +131,7 @@ Seamlessly integrate ActorCore with your favorite frameworks, languages, and too
 ### Clients
 - <img src="docs/images/clients/javascript.svg" height="16" alt="JavaScript" />&nbsp;&nbsp;[JavaScript](/clients/javascript)
 - <img src="docs/images/clients/typescript.svg" height="16" alt="TypeScript" />&nbsp;&nbsp;[TypeScript](/clients/javascript)
-- <img src="docs/images/clients/python.svg" height="16" alt="Python" />&nbsp;&nbsp;[Python](https://github.com/rivet-gg/actor-core/issues/900) *(Available In April)*
+- <img src="docs/images/clients/python.svg" height="16" alt="Python" />&nbsp;&nbsp;[Python](/clients/python)
 - <img src="docs/images/clients/rust.svg" height="16" alt="Rust" />&nbsp;&nbsp;[Rust](/clients/rust)
 
 ### Integrations

clients/python/Cargo.toml

@@ -1,10 +1,16 @@
+# Python client code is generated by
+# this package, with the aid of pyo3
+# 
+# This package turns into the python
+# pypi actor-core-client package
 [package]
-name = "python_actor_core_client"
+name = "python-actor-core-client"
 version = "0.8.0"
 edition = "2021"
+publish = false
 
 [lib]
-name = "python_actor_core_client"
+name = "actor_core_client"
 crate-type = ["cdylib"]
 
 [dependencies]

clients/python/pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-name = "python_actor_core_client"
+name = "actor-core-client"
 version = "0.8.0"
 authors = [
   { name="Rivet Gaming, LLC", email="developer@rivet.gg" },

clients/python/src/lib.rs

@@ -6,7 +6,7 @@ mod simple;
 mod events;
 
 #[pymodule]
-fn python_actor_core_client(m: &Bound<'_, PyModule>) -> PyResult<()> {
+fn actor_core_client(m: &Bound<'_, PyModule>) -> PyResult<()> {
     simple::init_module(m)?;
     events::init_module(m)?;
 

clients/python/tests/test_e2e_async.py

@@ -1,6 +1,6 @@
 import asyncio
 import pytest
-from python_actor_core_client import AsyncClient as ActorClient
+from actor_core_client import AsyncClient as ActorClient
 from common import start_mock_server, get_free_port, logger
 
 @pytest.mark.asyncio

clients/python/tests/test_e2e_simple_async.py

@@ -1,6 +1,6 @@
 import asyncio
 import pytest
-from python_actor_core_client import AsyncSimpleClient as ActorClient
+from actor_core_client import AsyncSimpleClient as ActorClient
 from common import start_mock_server, logger
 
 async def do_oneoff_increment(client):

clients/python/tests/test_e2e_simple_sync.py

@@ -1,4 +1,4 @@
-from python_actor_core_client import SimpleClient as ActorClient
+from actor_core_client import SimpleClient as ActorClient
 from common import start_mock_server, logger
 
 

clients/python/tests/test_e2e_sync.py

@@ -1,4 +1,4 @@
-from python_actor_core_client import Client as ActorClient
+from actor_core_client import Client as ActorClient
 from common import start_mock_server, logger
 
 def test_e2e_sync():

docs/clients/python.mdx

@@ -0,0 +1,131 @@
+---
+title: Python
+icon: python
+---
+
+import MvpWarning from "/snippets/mvp-warning.mdx";
+import StepDefineActor from "/snippets/step-define-actor.mdx";
+import StepRunStudio from "/snippets/step-run-studio.mdx";
+import StepDeploy from "/snippets/step-deploy.mdx";
+import SetupNextSteps from "/snippets/setup-next-steps.mdx";
+
+The ActorCore Python client provides a way to connect to and interact with actors from Python applications.
+
+<MvpWarning />
+
+## Quickstart
+
+<Steps>
+  <Step title="Create a new Python project">
+    Create a new directory for your project:
+    
+    ```sh
+    mkdir my-app
+    cd my-app
+    ```
+
+    It's recommended to create a virtual environment:
+    ```sh
+    python -m venv venv
+    source venv/bin/activate  # On Windows use: venv\Scripts\activate
+    ```
+  </Step>
+
+  <Step title="Add dependencies">
+    Install the ActorCore client package:
+    
+    ```sh
+    pip install actor-core-client
+    ```
+  </Step>
+
+  <StepDefineActor />
+
+  <Step title="Create your client">
+    Create a new file `main.py`:
+
+    <CodeGroup>
+        ```python Async
+        import asyncio
+        from actor_core_client import AsyncClient
+
+        async def main():
+            # Replace with your endpoint URL after deployment
+            client = AsyncClient("http://localhost:6420")
+            
+            # Get or create an actor instance
+            counter = await client.get("counter")
+            
+            # Subscribe to events using callback
+            def on_new_count(msg):
+                print(f"Event: {msg}")
+                
+            counter.on_event("newCount", on_new_count)
+            
+            # Call an action
+            result = await counter.action("increment", 5)
+            print(f"Action result: {result}")
+            
+            # Wait to receive events
+            await asyncio.sleep(1)
+            
+            # Clean up
+            await counter.disconnect()
+
+        if __name__ == "__main__":
+            asyncio.run(main())
+        ```
+
+        ```python Sync
+        from actor_core_client import Client
+
+        # Replace with your endpoint URL after deployment
+        client = Client("http://localhost:6420")
+        
+        # Get or create an actor instance
+        counter = client.get("counter")
+        
+        # Subscribe to events using callback
+        def on_new_count(msg):
+            print(f"Event: {msg}")
+            
+            # Clean up once we receive our event
+            counter.disconnect()
+        
+        counter.on_event("newCount", on_new_count)
+        
+        # Call an action
+        result = counter.action("increment", 5)
+        print(f"Action result: {result}")
+
+        # Clean is handled on by on_new_count
+        ```
+    </CodeGroup>
+
+    In the code above, subscription is done with `on_event` callbacks, but you can also
+    subscribe directly with `receive()` calls, using the `SimpleClient` (and `AsyncSimpleClient`)
+    interfaces. See our [sample usage](https://github.com/rivet-gg/actor-core/tree/main/clients/python/tests/test_e2e_simple_async.py) for more details.
+  </Step>
+
+  <StepRunStudio />
+
+  <Step title="Run your client">
+    In a separate terminal, run your Python code:
+    
+    ```sh
+    python main.py
+    ```
+    
+    You should see output like:
+    ```
+    Event: 5
+    Action result: 5
+    ```
+
+    Run it again to see the state update.
+  </Step>
+
+  <StepDeploy />
+</Steps>
+
+<SetupNextSteps />

docs/concepts/interacting-with-actors.mdx

@@ -28,6 +28,13 @@ let client = Client::new(
     EncodingKind::Cbor,                   // Encoding (Json or Cbor)
 );
 ```
+
+```python Python (Callbacks)
+from actor_core_client import AsyncClient as ActorClient
+
+# Create a client with the connection address
+client = ActorClient("http://localhost:6420")
+```
 </CodeGroup>
 
 <Tip>See the setup guide for your platform for details on how to get the connection address.</Tip>
@@ -76,6 +83,17 @@ room.action("sendMessage", vec![json!("Alice"), json!("Hello everyone!")])
     .await
     .expect("Failed to send message");
 ```
+
+```python Python (Callbacks)
+# Connect to a chat room for the "general" channel
+room = await client.get("chatRoom", tags=[
+    ("name", "chat_room"),
+    ("channel", "general")
+])
+
+# Now you can call methods on the actor
+await room.action("sendMessage", ["Alice", "Hello everyone!"])
+```
 </CodeGroup>
 
 ### `create(opts)` - Explicitly Create New
@@ -125,6 +143,16 @@ doc.action("initializeDocument", vec![json!("My New Document")])
     .await
     .expect("Failed to initialize document");
 ```
+
+```python Python (Callbacks)
+# Create a new document actor
+doc = await client.get("myDocument", tags=[
+    ("name", "my_document"),
+    ("docId", "123")
+])
+
+await doc.action("initializeDocument", ["My New Document"])
+```
 </CodeGroup>
 
 ### `getWithId(id, opts)` - Connect by ID
@@ -148,7 +176,7 @@ let my_actor_id = "55425f42-82f8-451f-82c1-6227c83c9372";
 let options = GetWithIdOptions {
     params: None,
 };
-let doc = client.get_with_id("myDocument", my_actor_id, options)
+let doc = client.get_with_id(my_actor_id, options)
     .await
     .expect("Failed to connect to document");
 
@@ -157,6 +185,14 @@ doc.action("updateContent", vec![json!("Updated content")])
     .await
     .expect("Failed to update document");
 ```
+
+```python Python (Callbacks)
+# Connect to a specific actor by its ID
+my_actor_id = "55425f42-82f8-451f-82c1-6227c83c9372"
+doc = await client.get_with_id(my_actor_id)
+
+await doc.action("updateContent", ["Updated content"])
+```
 </CodeGroup>
 
 <Note>
@@ -208,6 +244,22 @@ game_room.action("updateSettings", vec![settings])
     .await
     .expect("Failed to update settings");
 ```
+
+```python Python (Callbacks)
+# Call an action
+result = await math_utils.action("multiplyByTwo", [5])
+print(result)  # 10
+
+# Call an action with multiple parameters
+await chat_room.action("sendMessage", ["Alice", "Hello everyone!"])
+
+# Call an action with an object parameter
+await game_room.action("updateSettings", [{
+    "maxPlayers": 10,
+    "timeLimit": 300,
+    "gameMode": "capture-the-flag"
+}])
+```
 </CodeGroup>
 
 <Note>
@@ -256,6 +308,24 @@ game_room.on_event("stateUpdate", move |args| {
     game_ui_clone.update(game_state);
 }).await;
 ```
+
+```python Python (Callbacks)
+# Listen for new chat messages
+def handle_message(message):
+    sender = message["sender"]
+    text = message["text"]
+    print(f"{sender}: {text}")
+    # Update UI with message data
+
+chat_room.on_event("newMessage", handle_message)
+
+# Listen for game state updates
+def handle_state_update(game_state):
+    # Update UI with new game state
+    update_game_ui(game_state)
+
+game_room.on_event("stateUpdate", handle_state_update)
+```
 </CodeGroup>
 
 ### `once(eventName, callback)` - One-time Listening
@@ -274,6 +344,15 @@ actor.once("requestApproved", () => {
 ```rust Rust
 // `once` is not implemented in Rust
 ```
+
+```python Python (Callbacks)
+# Listen for when a request is approved
+def handle_approval():
+    show_approval_notification()
+    unlock_features()
+
+actor.on_event("requestApproved", handle_approval)
+```
 </CodeGroup>
 
 ## Connection Options
@@ -318,6 +397,18 @@ let chat_room = client.get("chatRoom", options)
     .await
     .expect("Failed to connect to chat room");
 ```
+
+```python Python (Callbacks)
+chat_room = await client.get(
+    "chatRoom",
+    tags=[("channel", "super-secret")],
+    params={
+        "userId": "1234",
+        "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+        "displayName": "Alice"
+    }
+)
+```
 </CodeGroup>
 
 The actor can access these parameters in the `onBeforeConnect` or `createConnState` hook:
@@ -391,6 +482,19 @@ let client = Client::new(
 
 // Rust does not support accepting multiple transports
 ```
+
+```python Python (Callbacks)
+from actor_core_client import AsyncClient as ActorClient
+
+# Example with all client options
+client = ActorClient(
+    "https://actors.example.com",
+    "websocket"  # or "sse"
+    "cbor",      # or "json"
+)
+
+# Python does not support accepting multiple transports
+```
 </CodeGroup>
 
 ### `encoding`
@@ -490,6 +594,11 @@ actor.disconnect().await;
 // Or explicitly drop it with:
 drop(client);
 ```
+
+```python Python (Callbacks)
+# Disconnect from the actor
+await actor.disconnect()
+```
 </CodeGroup>
 
 ## Offline and Auto-Reconnection