docs: add python sdk manual (#3056)
diff --git a/content/en/overview/mannual/_index.md b/content/en/overview/mannual/_index.md
index 2d55af4e..d660f05 100755
--- a/content/en/overview/mannual/_index.md
+++ b/content/en/overview/mannual/_index.md
@@ -76,6 +76,16 @@
</div>
</div>
</div>
+ <div class="col-sm col-md-6 mb-4">
+ <div class="h-100 card shadow">
+ <div class="card-body">
+ <h4 class="card-title">
+ <a href='{{< relref "./python-sdk" >}}'>Python SDK</a>
+ </h4>
+ <p>Dubbo Python SDK Manual</p>
+ </div>
+ </div>
+ </div>
</div>
<hr>
</div>
diff --git a/content/en/overview/mannual/python-sdk/_index.md b/content/en/overview/mannual/python-sdk/_index.md
new file mode 100755
index 0000000..7e10745
--- /dev/null
+++ b/content/en/overview/mannual/python-sdk/_index.md
@@ -0,0 +1,9 @@
+---
+aliases:
+ - /en/docs3-v2/python-sdk/
+description: Python SDK Manual
+linkTitle: Python SDK
+title: Python SDK
+type: docs
+weight: 5
+---
diff --git a/content/en/overview/mannual/python-sdk/custom-serialization.md b/content/en/overview/mannual/python-sdk/custom-serialization.md
new file mode 100644
index 0000000..d00884e
--- /dev/null
+++ b/content/en/overview/mannual/python-sdk/custom-serialization.md
@@ -0,0 +1,183 @@
+---
+aliases:
+ - /en/docs3-v2/python-sdk/custom-serialization/
+description: Dubbo Python Custom Serialization
+linkTitle: Custom Serialization
+title: Custom Serialization
+type: docs
+weight: 2
+---
+
+See the full [example here](https://github.com/apache/dubbo-python/tree/main/samples/serialization)
+
+Python is a dynamic language, and its flexibility makes it challenging to design a universal serialization layer as seen in other languages. Therefore, we have removed the "serialization layer" and left it to the users to implement (since users know the formats of the data they will pass).
+
+Serialization typically consists of two parts: serialization and deserialization. We have defined the types for these functions, and custom serialization/deserialization functions must adhere to these "formats."
+
+
+
+First, for serialization functions, we specify:
+
+```python
+# A function that takes an argument of any type and returns data of type bytes
+SerializingFunction = Callable[[Any], bytes]
+```
+
+Next, for deserialization functions, we specify:
+
+```python
+# A function that takes an argument of type bytes and returns data of any type
+DeserializingFunction = Callable[[bytes], Any]
+```
+
+Below, I'll demonstrate how to use custom functions with `protobuf` and `json`.
+
+
+
+### protobuf
+
+1. For defining and compiling `protobuf` files, please refer to the [protobuf tutorial](https://protobuf.dev/getting-started/pythontutorial/) for detailed instructions.
+
+2. Set `xxx_serializer` and `xxx_deserializer` in the client and server.
+
+ client
+
+ ```python
+ class GreeterServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(
+ method_name="sayHello",
+ request_serializer=greeter_pb2.GreeterRequest.SerializeToString,
+ response_deserializer=greeter_pb2.GreeterReply.FromString,
+ )
+
+ def say_hello(self, request):
+ return self.unary(request)
+
+
+ if __name__ == "__main__":
+ reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.proto.Greeter"
+ )
+ dubbo_client = dubbo.Client(reference_config)
+
+ stub = GreeterServiceStub(dubbo_client)
+ result = stub.say_hello(greeter_pb2.GreeterRequest(name="hello"))
+ print(result.message)
+ ```
+
+ server
+
+ ```python
+ def say_hello(request):
+ print(f"Received request: {request}")
+ return greeter_pb2.GreeterReply(message=f"{request.name} Dubbo!")
+
+
+ if __name__ == "__main__":
+ # build a method handler
+ method_handler = RpcMethodHandler.unary(
+ say_hello,
+ request_deserializer=greeter_pb2.GreeterRequest.FromString,
+ response_serializer=greeter_pb2.GreeterReply.SerializeToString,
+ )
+ # build a service handler
+ service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.proto.Greeter",
+ method_handlers={"sayHello": method_handler},
+ )
+
+ service_config = ServiceConfig(service_handler)
+
+ # start the server
+ server = dubbo.Server(service_config).start()
+
+ input("Press Enter to stop the server...\n")
+ ```
+
+
+
+### Json
+
+`protobuf` does not fully illustrate how to implement custom serialization and deserialization because its built-in functions perfectly meet the requirements. Instead, I'll demonstrate how to create custom serialization and deserialization functions using `orjson`:
+
+1. Install `orjson`:
+
+ ```shell
+ pip install orjson
+ ```
+
+2. Define serialization and deserialization functions:
+
+ client
+
+ ```python
+ def request_serializer(data: Dict) -> bytes:
+ return orjson.dumps(data)
+
+
+ def response_deserializer(data: bytes) -> Dict:
+ return orjson.loads(data)
+
+
+ class GreeterServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(
+ method_name="unary",
+ request_serializer=request_serializer,
+ response_deserializer=response_deserializer,
+ )
+
+ def say_hello(self, request):
+ return self.unary(request)
+
+
+ if __name__ == "__main__":
+ reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.serialization.json"
+ )
+ dubbo_client = dubbo.Client(reference_config)
+
+ stub = GreeterServiceStub(dubbo_client)
+ result = stub.say_hello({"name": "world"})
+ print(result)
+ ```
+
+ server
+
+ ```python
+ def request_deserializer(data: bytes) -> Dict:
+ return orjson.loads(data)
+
+
+ def response_serializer(data: Dict) -> bytes:
+ return orjson.dumps(data)
+
+
+ def handle_unary(request):
+ print(f"Received request: {request}")
+ return {"message": f"Hello, {request['name']}"}
+
+
+ if __name__ == "__main__":
+ # build a method handler
+ method_handler = RpcMethodHandler.unary(
+ handle_unary,
+ request_deserializer=request_deserializer,
+ response_serializer=response_serializer,
+ )
+ # build a service handler
+ service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.HelloWorld",
+ method_handlers={"unary": method_handler},
+ )
+
+ service_config = ServiceConfig(service_handler)
+
+ # start the server
+ server = dubbo.Server(service_config).start()
+
+ input("Press Enter to stop the server...\n")
+ ```
+
+
\ No newline at end of file
diff --git a/content/en/overview/mannual/python-sdk/quick-start.md b/content/en/overview/mannual/python-sdk/quick-start.md
new file mode 100644
index 0000000..fc019d7
--- /dev/null
+++ b/content/en/overview/mannual/python-sdk/quick-start.md
@@ -0,0 +1,229 @@
+---
+aliases:
+ - /en/docs3-v2/python-sdk/quick-start/
+ - /en/overview/quickstart/python/
+description: Dubbo-python Quick Start
+linkTitle: Quick Start
+title: Quick Start
+type: docs
+weight: 1
+---
+
+This guide will help you get started with Dubbo in Python with a simple working example. See the full [example here](https://github.com/apache/dubbo-python/tree/main/samples/helloworld).
+
+## 1. Prerequisites
+
+- Python 3.11 or higher
+- Compatible `pip` version
+
+## 2. Install Dubbo-Python
+
+```bash
+git clone https://github.com/apache/dubbo-python.git
+cd dubbo-python && pip install .
+```
+
+## 3. Build a Dubbo Service
+
+### Building the Dubbo Server
+
+```python
+import dubbo
+from dubbo.configs import ServiceConfig
+from dubbo.proxy.handlers import RpcMethodHandler, RpcServiceHandler
+
+class UnaryServiceServicer:
+ def say_hello(self, message: bytes) -> bytes:
+ print(f"Received message from client: {message}")
+ return b"Hello from server"
+
+def build_service_handler():
+ # build a method handler
+ method_handler = RpcMethodHandler.unary(
+ method=UnaryServiceServicer().say_hello, method_name="unary"
+ )
+ # build a service handler
+ service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.HelloWorld",
+ method_handlers=[method_handler],
+ )
+ return service_handler
+
+if __name__ == "__main__":
+ # build service config
+ service_handler = build_service_handler()
+ service_config = ServiceConfig(
+ service_handler=service_handler, host="127.0.0.1", port=50051
+ )
+ # start the server
+ server = dubbo.Server(service_config).start()
+
+ input("Press Enter to stop the server...\n")
+```
+
+### Building the Dubbo Client
+
+```python
+import dubbo
+from dubbo.configs import ReferenceConfig
+
+class UnaryServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(method_name="unary")
+
+ def say_hello(self, message: bytes) -> bytes:
+ return self.unary(message)
+
+if __name__ == "__main__":
+ # Create a client
+ reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.HelloWorld"
+ )
+ dubbo_client = dubbo.Client(reference_config)
+ unary_service_stub = UnaryServiceStub(dubbo_client)
+
+ # Call the remote method
+ result = unary_service_stub.say_hello(b"Hello from client")
+ print(result)
+```
+
+## 4. Run the Dubbo Service
+
+Navigate to the Quick Start example directory:
+
+```bash
+cd samples/helloworld
+```
+
+Run the Server:
+
+```bash
+python server.py
+```
+
+Run the Client:
+
+```bash
+python client.py
+```
+
+## 5. Code Walkthrough
+
+### 5.1 Exposing the Service
+
+First, define the service methods you want to expose, as shown below:
+
+```python
+class UnaryServiceServicer:
+ def say_hello(self, message: bytes) -> bytes:
+ print(f"Received message from client: {message}")
+ return b"Hello from server"
+```
+
+Next, we use the `RpcMethodHandler` constructor methods (`unary`, `client_stream`, `server_stream`, `bi_stream`) to build the method and define its properties. Key parameters include:
+
+- `callable_method`: The method itself.
+- `method_name`: The exposed method name, defaulting to the method’s own name.
+- `request_deserializer`: The deserialization function for requests (or method parameters). By default, it returns raw `bytes`.
+- `response_serializer`: The serialization function for responses (or return values). If not set, the return value must be in `bytes`, `bytearray`, or `memoryview`.
+
+If the method’s parameters and return values are in `bytes`, we can get a minimal `RpcMethodHandler` as follows:
+
+```python
+method_handler = RpcMethodHandler.unary(
+ method=UnaryServiceServicer().say_hello, method_name="unary"
+ )
+```
+
+Next, we use `RpcServiceHandler` to build the service, with parameters including:
+
+- `service_name`: The name of the exposed service.
+- `method_handlers`: The set of methods for the service, as a `List[RpcMethodHandler]`.
+
+This results in the following `RpcServiceHandler`:
+
+```python
+service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.HelloWorld",
+ method_handlers=[method_handler],
+ )
+```
+
+Finally, we configure `ServiceConfig`, passing in the `RpcServiceHandler` as well as the `host` (address), `port`, `protocol`, and other details for the service. Passing this to `dubbo.Server` exposes the service, as shown below:
+
+```python
+service_config = ServiceConfig(
+ service_handler=service_handler, host="127.0.0.1", port=50051
+ )
+# start the server
+server = dubbo.Server(service_config).start()
+```
+
+### 5.2 Referencing the Service
+
+To reference the service on the Server, we first configure `ReferenceConfig` with the following parameters:
+
+- `protocol`: The protocol used by the Server, such as `tri` (Triple).
+- `service`: The name of the referenced service.
+- `host`: The service address.
+- `port`: The service port.
+
+Additionally, we can use `ReferenceConfig.from_url` to configure `ReferenceConfig` by parsing a URL string automatically. Once configured, we can create a `dubbo.Client`.
+
+Example:
+
+```python
+reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.HelloWorld"
+ )
+dubbo_client = dubbo.Client(reference_config)
+```
+
+Then, we can use the `unary`, `client_stream`, `server_stream`, and `bi_stream` methods of `dubbo.Client` to construct and call the service. Parameters for these methods are:
+
+- `method_name`: The name of the referenced method.
+- `request_serializer`: The serialization function for the request (or method parameters). If not set, ensure that the return value is `bytes`, `bytearray`, or `memoryview`.
+- `response_deserializer`: The deserialization function for the response (or return value). By default, it returns raw `bytes`.
+
+This lets us use the `RpcCallable` object returned by these methods to make the service call. Example:
+
+```python
+class UnaryServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(method_name="unary")
+
+ def say_hello(self, message: bytes) -> bytes:
+ return self.unary(message)
+```
+
+## 6 More examples
+
+{{< blocks/section color="white" height="auto">}}
+<div class="td-content list-page">
+ <div class="lead"></div><header class="article-meta">
+ </header><div class="row">
+ <div class="col-sm col-md-6 mb-4">
+ <div class="h-100 card shadow" href="#">
+ <div class="card-body">
+ <h4 class="card-title">
+ <a href='{{< relref "../../mannual/python-sdk/custom-serialization/" >}}'>Custom Serialization</a>
+ </h4>
+ <p>Dubbo-python Custom Serialization</p>
+ </div>
+ </div>
+ </div>
+ <div class="col-sm col-md-6 mb-4">
+ <div class="h-100 card shadow" href="#">
+ <div class="card-body">
+ <h4 class="card-title">
+ <a href='{{< relref "../../mannual/python-sdk/streaming/" >}}'>Streaming Communication Mode</a>
+ </h4>
+ <p>Implementing a Streaming Communication Model with Dubbo-Python</p>
+ </div>
+ </div>
+ </div>
+</div>
+<hr>
+</div>
+
+{{< /blocks/section >}}
diff --git a/content/en/overview/mannual/python-sdk/service-discovery.md b/content/en/overview/mannual/python-sdk/service-discovery.md
new file mode 100644
index 0000000..c36de65
--- /dev/null
+++ b/content/en/overview/mannual/python-sdk/service-discovery.md
@@ -0,0 +1,36 @@
+---
+aliases:
+ - /en/docs3-v2/python-sdk/service-discovery/
+description: Service Discovery
+linkTitle: Service Discovery
+title: Service Discovery
+type: docs
+weight: 4
+---
+
+See the full [example here](https://github.com/apache/dubbo-python/tree/main/samples/registry)
+
+Using service registration and discovery is very simple. In fact, it only requires two additional lines of code compared to point-to-point calls. Before using this feature, we need to install the relevant registry client. Currently, Dubbo-python only supports `Zookeeper`, so the following demonstration will use `Zookeeper`.
+
+Similar to before, we need to clone the Dubbo-python source code and install it. However, in this case, we also need to install the `Zookeeper` client. The commands are:
+
+```shell
+git clone https://github.com/apache/dubbo-python.git
+cd dubbo-python && pip install .[zookeeper]
+```
+
+After that, simply start `Zookeeper` and insert the following code into your existing example:
+
+```python
+# Configure the Zookeeper registry
+registry_config = RegistryConfig.from_url("zookeeper://127.0.0.1:2181")
+bootstrap = Dubbo(registry_config=registry_config)
+
+# Create the client
+client = bootstrap.create_client(reference_config)
+
+# Create and start the server
+bootstrap.create_server(service_config).start()
+```
+
+This enables service registration and discovery within your Dubbo-python project.
diff --git a/content/en/overview/mannual/python-sdk/streaming.md b/content/en/overview/mannual/python-sdk/streaming.md
new file mode 100644
index 0000000..280d2b0
--- /dev/null
+++ b/content/en/overview/mannual/python-sdk/streaming.md
@@ -0,0 +1,105 @@
+---
+aliases:
+ - /en/docs3-v2/python-sdk/streaming/
+description: Implement services in Dubbo Python using client streaming, server streaming, and bidirectional streaming models.
+linkTitle: Streaming Communication Model
+title: Streaming Communication Model
+type: docs
+weight: 3
+---
+
+See the full [example here](https://github.com/apache/dubbo-python/tree/main/samples/stream)
+
+Dubbo-Python supports streaming calls, including `ClientStream`, `ServerStream`, and `BidirectionalStream` modes.
+
+Streaming calls can be divided into write-streams and read-streams. For `ClientStream`, it’s multiple writes with a single read; for `ServerStream`, a single write with multiple reads; and `BidirectionalStream` allows multiple writes and reads.
+
+### Write-Stream
+
+Write operations in streaming calls can be divided into single write (`ServerStream`) and multiple writes (`ClientStream` and `BidirectionalStream`).
+
+#### Single Write
+
+Single write calls are similar to unary mode. For example:
+
+```python
+stub.server_stream(greeter_pb2.GreeterRequest(name="hello world from dubbo-python"))
+```
+
+#### Multiple Writes
+
+For multiple writes, users can write data using either an iterator or `writeStream` (only one of these options should be used).
+
+1. **Iterator-based Write**: Writing via iterator is similar to unary mode, with the main difference being the use of an iterator for multiple writes. For example:
+
+ ```python
+ # Use an iterator to send multiple requests
+ def request_generator():
+ for i in ["hello", "world", "from", "dubbo-python"]:
+ yield greeter_pb2.GreeterRequest(name=str(i))
+
+ # Call the remote method and return a read_stream
+ stream = stub.client_stream(request_generator())
+ ```
+
+2. **Using `writeStream`**: This method requires an empty argument, after which data is written incrementally using `write`, and `done_writing` is called to end the write-stream. For example:
+
+ ```python
+ stream = stub.bi_stream()
+ # Use the write method to send messages
+ stream.write(greeter_pb2.GreeterRequest(name="jock"))
+ stream.write(greeter_pb2.GreeterRequest(name="jane"))
+ stream.write(greeter_pb2.GreeterRequest(name="alice"))
+ stream.write(greeter_pb2.GreeterRequest(name="dave"))
+ # Call done_writing to notify the server that the client has finished writing
+ stream.done_writing()
+ ```
+
+### Read-Stream
+
+Read operations for streaming calls can be single read (`ClientStream`) or multiple reads (`ServerStream` and `BidirectionalStream`). A `ReadStream` is returned in all cases, and data can be read using the `read` method or an iterator. When using `read`, please note:
+
+1. The `read` method supports a `timeout` parameter (in seconds).
+2. The `read` method can return one of three values: the expected data, `None` (timeout exceeded), or `EOF` (end of the read-stream).
+
+#### Single Read
+
+A single call to the `read` method will retrieve the data, for example:
+
+```python
+result = stream.read()
+print(f"Received response: {result.message}")
+```
+
+#### Multiple Reads
+
+Multiple reads can be done by repeatedly calling `read`, with handling for `None` and `EOF` values. Since `ReadStream` implements `__iter__` and `__next__`, an iterator-based approach can also be used, which automatically handles these values but doesn’t support a timeout.
+
+1. **Using Iterator (Recommended)**:
+
+ ```python
+ def client_stream(self, request_iterator):
+ response = ""
+ for request in request_iterator:
+ print(f"Received request: {request.name}")
+ response += f"{request.name} "
+ return greeter_pb2.GreeterReply(message=response)
+ ```
+
+2. **Multiple Calls to `read` Method**:
+
+ ```python
+ # Use read method to receive messages
+ # If no message arrives within the specified time, returns None
+ # If the server has finished sending messages, returns EOF
+ while True:
+ i = stream.read(timeout=0.5)
+ if i is dubbo.classes.EOF:
+ break
+ elif i is None:
+ print("No message received")
+ continue
+ print(f"Received response: {i.message}")
+ ```
+
+
diff --git a/content/zh-cn/overview/mannual/_index.md b/content/zh-cn/overview/mannual/_index.md
index b2af438..a1688cf 100755
--- a/content/zh-cn/overview/mannual/_index.md
+++ b/content/zh-cn/overview/mannual/_index.md
@@ -76,6 +76,16 @@
</div>
</div>
</div>
+ <div class="col-sm col-md-6 mb-4">
+ <div class="h-100 card shadow">
+ <div class="card-body">
+ <h4 class="card-title">
+ <a href='{{< relref "./python-sdk" >}}'>Python SDK</a>
+ </h4>
+ <p>Dubbo Python SDK 手册</p>
+ </div>
+ </div>
+ </div>
</div>
<hr>
</div>
diff --git a/content/zh-cn/overview/mannual/python-sdk/_index.md b/content/zh-cn/overview/mannual/python-sdk/_index.md
index 92f4e29..ad1bf41 100755
--- a/content/zh-cn/overview/mannual/python-sdk/_index.md
+++ b/content/zh-cn/overview/mannual/python-sdk/_index.md
@@ -1,5 +1,9 @@
---
description: Dubbo Python SDK 使用手册
+aliases:
+ - /zh/docs3-v2/python-sdk/
+ - /zh-cn/docs3-v2/python-sdk/
+description: Python SDK 使用手册
linkTitle: Python SDK
title: Python SDK 手册
type: docs
diff --git a/content/zh-cn/overview/mannual/python-sdk/custom-serialization.md b/content/zh-cn/overview/mannual/python-sdk/custom-serialization.md
new file mode 100644
index 0000000..f824f12
--- /dev/null
+++ b/content/zh-cn/overview/mannual/python-sdk/custom-serialization.md
@@ -0,0 +1,185 @@
+---
+aliases:
+ - /zh/docs3-v2/python-sdk/custom-serialization/
+ - /zh-cn/docs3-v2/python-sdk/custom-serialization/
+description: Dubbo Python 自定义序列化
+linkTitle: 自定义序列化
+title: 自定义序列化
+type: docs
+weight: 2
+---
+
+在此查看完整[示例](https://github.com/apache/dubbo-python/tree/main/samples/serialization)。
+
+Python 是一种动态语言，其灵活性使得在其他语言中设计通用的序列化层具有挑战性。因此，我们移除了框架级别的序列化层，而是提供接口，允许用户根据需求自行实现（因为用户更了解他们要传输的数据格式）。
+
+序列化通常分为两个部分：序列化和反序列化。我们为这些函数定义了类型，自定义的序列化/反序列化函数必须遵循这些 "格式"。
+
+对于序列化函数，我们规定：
+
+```python
+# A function that takes any number of arguments and returns data of type bytes
+SerializingFunction = Callable[..., bytes]
+
+```
+
+对于反序列化函数，我们规定：
+
+```python
+# A function that takes an argument of type bytes and returns data of any type
+DeserializingFunction = Callable[[bytes], Any]
+
+```
+
+下面，我将演示如何使用 `protobuf` 和 `json` 进行序列化。
+
+## protobuf
+
+1. 有关定义和编译 `protobuf` 文件的详细说明，请参阅 [protobuf tutorial](https://protobuf.dev/getting-started/pythontutorial/)。
+
+2. 在Client的`unary`、`client_stream`、`server_stream` 和 `bi_stream` 方法中通过设置`request_serializer` 和 `response_deserializer` 设置对应的序列化和反序列化函数。
+
+ ```python
+ class GreeterServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(
+ method_name="sayHello",
+ request_serializer=greeter_pb2.GreeterRequest.SerializeToString,
+ response_deserializer=greeter_pb2.GreeterReply.FromString,
+ )
+
+ def say_hello(self, request):
+ return self.unary(request)
+
+ if __name__ == "__main__":
+ reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.data.Greeter"
+ )
+ dubbo_client = dubbo.Client(reference_config)
+
+ stub = GreeterServiceStub(dubbo_client)
+ result = stub.say_hello(greeter_pb2.GreeterRequest(name="Dubbo-python"))
+ print(f"Received reply: {result.message}")
+ ```
+
+3. 同理在Server中设置对应的序列化和反序列化函数。
+
+ ```python
+ class GreeterServiceServicer:
+ def say_hello(self, request):
+ print(f"Received request: {request}")
+ return greeter_pb2.GreeterReply(message=f"Hello, {request.name}")
+
+ def build_service_handler():
+ # build a method handler
+ method_handler = RpcMethodHandler.unary(
+ GreeterServiceServicer().say_hello,
+ method_name="sayHello",
+ request_deserializer=greeter_pb2.GreeterRequest.FromString,
+ response_serializer=greeter_pb2.GreeterReply.SerializeToString,
+ )
+ # build a service handler
+ service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.data.Greeter",
+ method_handlers=[method_handler],
+ )
+ return service_handler
+
+ if __name__ == "__main__":
+ # build a service handler
+ service_handler = build_service_handler()
+ service_config = ServiceConfig(
+ service_handler=service_handler, host="127.0.0.1", port=50051
+ )
+
+ # start the server
+ server = dubbo.Server(service_config).start()
+
+ input("Press Enter to stop the server...\n")
+ ```
+
+## Json
+
+我们已经使用 `protobuf` 实现了单参数的序列化和反序列化。现在，我将演示如何编写一个支持多参数的 Json 序列化和反序列化函数，从而实现多参数方法的远程调用。
+
+1. 安装`orjson`
+
+ ```bash
+ pip install orjson
+ ```
+
+2. 定义并设置Client的序列化和反序列化函数
+
+ ```python
+ def request_serializer(name: str, age: int) -> bytes:
+ return orjson.dumps({"name": name, "age": age})
+
+ def response_deserializer(data: bytes) -> str:
+ json_dict = orjson.loads(data)
+ return json_dict["message"]
+
+ class GreeterServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(
+ method_name="unary",
+ request_serializer=request_serializer,
+ response_deserializer=response_deserializer,
+ )
+
+ def say_hello(self, name: str, age: int):
+ return self.unary(name, age)
+
+ if __name__ == "__main__":
+ reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.serialization.json"
+ )
+ dubbo_client = dubbo.Client(reference_config)
+
+ stub = GreeterServiceStub(dubbo_client)
+ result = stub.say_hello("dubbo-python", 18)
+ print(result)
+ ```
+
+3. 定义并设置Server的序列化和反序列化函数
+
+ ```python
+ def request_deserializer(data: bytes) -> Tuple[str, int]:
+ json_dict = orjson.loads(data)
+ return json_dict["name"], json_dict["age"]
+
+ def response_serializer(message: str) -> bytes:
+ return orjson.dumps({"message": message})
+
+ class GreeterServiceServicer:
+ def say_hello(self, request):
+ name, age = request
+ print(f"Received request: {name}, {age}")
+ return f"Hello, {name}, you are {age} years old."
+
+ def build_service_handler():
+ # build a method handler
+ method_handler = RpcMethodHandler.unary(
+ GreeterServiceServicer().say_hello,
+ method_name="unary",
+ request_deserializer=request_deserializer,
+ response_serializer=response_serializer,
+ )
+ # build a service handler
+ service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.serialization.json",
+ method_handlers=[method_handler],
+ )
+ return service_handler
+
+ if __name__ == "__main__":
+ # build server config
+ service_handler = build_service_handler()
+ service_config = ServiceConfig(
+ service_handler=service_handler, host="127.0.0.1", port=50051
+ )
+
+ # start the server
+ server = dubbo.Server(service_config).start()
+
+ input("Press Enter to stop the server...\n")
+ ```
diff --git a/content/zh-cn/overview/mannual/python-sdk/quick-start.md b/content/zh-cn/overview/mannual/python-sdk/quick-start.md
index 92fc1a0..eb611d4 100644
--- a/content/zh-cn/overview/mannual/python-sdk/quick-start.md
+++ b/content/zh-cn/overview/mannual/python-sdk/quick-start.md
@@ -1,80 +1,231 @@
---
aliases:
- - /zh/overview/quickstart/nodejs/
- - /zh-cn/overview/quickstart/nodejs/
-description: 使用 Python 开发后端微服务
+ - /zh/docs3-v2/python-sdk/quick-start/
+ - /zh-cn/docs3-v2/python-sdk/quick-start/
+ - /zh/overview/quickstart/python/
+ - /zh-cn/overview/quickstart/python/
+description: Dubbo-python 快速开始
linkTitle: 快速开始
title: 快速开始
type: docs
weight: 1
---
-在开始之前，请确保您已经安装了 **`python 3.11+`**. Then, install Dubbo-Python in your project using the following steps:
+本指南将通过一个简单的工作示例帮助您开始使用 Python 中的 Dubbo，在此查看完整[示例](https://github.com/apache/dubbo-python/tree/main/samples/helloworld)。
-```shell
+## 1 前置条件
+
+- Python 3.11 或更高版本
+- 合适的`pip` 版本
+
+## 2 安装Dubbo-python
+
+```python
git clone https://github.com/apache/dubbo-python.git
cd dubbo-python && pip install .
```
-Get started with Dubbo-Python in just 5 minutes by following our [Quick Start Guide](https://github.com/apache/dubbo-python/tree/main/samples).
+## 3 构建Dubbo服务
-It's as simple as the following code snippet. With just a few lines of code, you can launch a fully functional point-to-point RPC service :
+构建Dubbo Server
-1. Build and start the Server
+```python
+import dubbo
+from dubbo.configs import ServiceConfig
+from dubbo.proxy.handlers import RpcMethodHandler, RpcServiceHandler
- ```python
- import dubbo
- from dubbo.configs import ServiceConfig
- from dubbo.proxy.handlers import RpcServiceHandler, RpcMethodHandler
+class UnaryServiceServicer:
+ def say_hello(self, message: bytes) -> bytes:
+ print(f"Received message from client: {message}")
+ return b"Hello from server"
+def build_service_handler():
+ # build a method handler
+ method_handler = RpcMethodHandler.unary(
+ method=UnaryServiceServicer().say_hello, method_name="unary"
+ )
+ # build a service handler
+ service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.HelloWorld",
+ method_handlers=[method_handler],
+ )
+ return service_handler
- def handle_unary(request):
- s = request.decode("utf-8")
- print(f"Received request: {s}")
- return (s + " world").encode("utf-8")
+if __name__ == "__main__":
+ # build service config
+ service_handler = build_service_handler()
+ service_config = ServiceConfig(
+ service_handler=service_handler, host="127.0.0.1", port=50051
+ )
+ # start the server
+ server = dubbo.Server(service_config).start()
+ input("Press Enter to stop the server...\n")
+```
- if __name__ == "__main__":
- # build a method handler
- method_handler = RpcMethodHandler.unary(handle_unary)
- # build a service handler
- service_handler = RpcServiceHandler(
- service_name="org.apache.dubbo.samples.HelloWorld",
- method_handlers={"unary": method_handler},
- )
+构建Dubbo Client
- service_config = ServiceConfig(service_handler)
+```python
+import dubbo
+from dubbo.configs import ReferenceConfig
- # start the server
- server = dubbo.Server(service_config).start()
+class UnaryServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(method_name="unary")
- input("Press Enter to stop the server...\n")
- ```
+ def say_hello(self, message: bytes) -> bytes:
+ return self.unary(message)
-2. Build and start the Client
+if __name__ == "__main__":
+ # Create a client
+ reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.HelloWorld"
+ )
+ dubbo_client = dubbo.Client(reference_config)
+ unary_service_stub = UnaryServiceStub(dubbo_client)
- ```python
- import dubbo
- from dubbo.configs import ReferenceConfig
+ # Call the remote method
+ result = unary_service_stub.say_hello(b"Hello from client")
+ print(result)
+```
+## 4 运行Dubbo 服务
- class UnaryServiceStub:
+切换到快速开始示例目录
- def __init__(self, client: dubbo.Client):
- self.unary = client.unary(method_name="unary")
+```bash
+cd samples/helloworld
+```
- def unary(self, request):
- return self.unary(request)
+运行Server
+```bash
+python server.py
+```
- if __name__ == "__main__":
- reference_config = ReferenceConfig.from_url(
- "tri://127.0.0.1:50051/org.apache.dubbo.samples.HelloWorld"
- )
- dubbo_client = dubbo.Client(reference_config)
+运行Client
- unary_service_stub = UnaryServiceStub(dubbo_client)
+```bash
+python client.py
+```
- result = unary_service_stub.unary("hello".encode("utf-8"))
- print(result.decode("utf-8"))
- ```
+## 5 源码解读
+
+### 5.1 暴露服务
+
+首先我们需要定义和编写需要暴露的服务方法，如下所示：
+
+```python
+class UnaryServiceServicer:
+ def say_hello(self, message: bytes) -> bytes:
+ print(f"Received message from client: {message}")
+ return b"Hello from server"
+```
+
+接下来，我们需要使用 `RpcMethodHandler` 的构建方法（`unary`、`client_stream`、`server_stream`、`bi_stream`）构建需要暴露的方法及其属性，其参数包括：
+
+- `callable_method`：方法本身
+- `method_name`：暴露的方法名，默认为自身方法名
+- `request_deserializer`：请求（或称方法参数）的反序列化函数（默认不反序列化，即直接返回 `bytes`）
+- `response_serializer`：响应（或称返回值）的序列化函数（如果不设置，需要确保返回值必须是 `bytes`、`bytearray` 或 `memoryview`）
+
+如果我们的方法参数和返回值均为 `bytes`，则可以得到一个最简的 `RpcMethodHandler`，如下所示：
+
+```python
+method_handler = RpcMethodHandler.unary(
+ method=UnaryServiceServicer().say_hello, method_name="unary"
+ )
+```
+
+接下来，我们需要使用 `RpcServiceHandler` 构建需要暴露的服务，其参数包括：
+
+- `service_name`：暴露的服务名
+- `method_handlers`：该服务对应的方法集合 - `List[RpcMethodHandler]`
+
+因此，我们可以得到以下 `RpcServiceHandler`：
+
+```python
+service_handler = RpcServiceHandler(
+ service_name="org.apache.dubbo.samples.HelloWorld",
+ method_handlers=[method_handler],
+ )
+```
+
+最后，我们需要配置 `ServiceConfig`，传入之前的 `RpcServiceHandler` 以及需要暴露的地址（`host`）、端口（`port`）、所使用的协议（`protocol`）等信息。然后将其传入 `dubbo.Server`，就能成功暴露一个服务。如下所示：
+
+```python
+service_config = ServiceConfig(
+ service_handler=service_handler, host="127.0.0.1", port=50051
+ )
+# start the server
+server = dubbo.Server(service_config).start()
+```
+
+### 5.2 引用服务
+
+要引用对应 Server 的服务，我们首先需要配置 `ReferenceConfig`，其参数如下：
+
+- `protocol`：Server 使用的通信协议，例如 `tri`（Triple）等。
+- `service`：引用的服务名。
+- `host`：服务地址。
+- `port`：服务端口。
+
+此外，我们还可以通过 `ReferenceConfig.from_url` 自动解析 URL 字符串来配置 `ReferenceConfig`。之后，我们就能创建一个 `dubbo.Client` 了。
+
+如下所示：
+
+```python
+reference_config = ReferenceConfig.from_url(
+ "tri://127.0.0.1:50051/org.apache.dubbo.samples.HelloWorld"
+ )
+dubbo_client = dubbo.Client(reference_config)
+```
+
+接下来，我们可以使用 `dubbo.Client` 的 `unary`、`client_stream`、`server_stream` 和 `bi_stream` 方法构建并调用服务。这些方法的参数如下：
+
+- `method_name`：引用的方法名。
+- `request_serializer`：请求（或称方法参数）的序列化函数（如果不设置，需要确保返回值是 `bytes`、`bytearray` 或 `memoryview`）。
+- `response_deserializer`：响应（或称返回值）的反序列化函数（默认不反序列化，即直接返回 `bytes`）。
+
+此时，我们就能利用上述方法返回的 `RpcCallable` 对象完成服务的调用。如下所示：
+
+```python
+class UnaryServiceStub:
+ def __init__(self, client: dubbo.Client):
+ self.unary = client.unary(method_name="unary")
+
+ def say_hello(self, message: bytes) -> bytes:
+ return self.unary(message)
+```
+
+## 6 更多示例
+
+{{< blocks/section color="white" height="auto">}}
+<div class="td-content list-page">
+ <div class="lead"></div><header class="article-meta">
+ </header><div class="row">
+ <div class="col-sm col-md-6 mb-4">
+ <div class="h-100 card shadow" href="#">
+ <div class="card-body">
+ <h4 class="card-title">
+ <a href='{{< relref "../../mannual/python-sdk/custom-serialization/" >}}'>自定义序列化</a>
+ </h4>
+ <p>Dubbo-python 自定义序列化</p>
+ </div>
+ </div>
+ </div>
+ <div class="col-sm col-md-6 mb-4">
+ <div class="h-100 card shadow" href="#">
+ <div class="card-body">
+ <h4 class="card-title">
+ <a href='{{< relref "../../mannual/python-sdk/streaming/" >}}'>Streaming 通信模式</a>
+ </h4>
+ <p>Dubbo-python 实现 Streaming 通信模型</p>
+ </div>
+ </div>
+ </div>
+</div>
+<hr>
+</div>
+
+{{< /blocks/section >}}
diff --git a/content/zh-cn/overview/mannual/python-sdk/service-discovery.md b/content/zh-cn/overview/mannual/python-sdk/service-discovery.md
new file mode 100644
index 0000000..bf6c4c1
--- /dev/null
+++ b/content/zh-cn/overview/mannual/python-sdk/service-discovery.md
@@ -0,0 +1,33 @@
+---
+aliases:
+ - /zh/docs3-v2/python-sdk/service-discovery/
+ - /zh-cn/docs3-v2/python-sdk/service-discovery/
+description: 服务发现
+linkTitle: 服务发现
+title: 服务发现
+type: docs
+weight: 4
+---
+
+在此查看完整[示例](https://github.com/apache/dubbo-python/tree/main/samples/registry)。
+
+使用服务注册和发现非常简单。事实上，与点对点调用相比，它只需要增加两行代码。在使用该功能之前，我们需要安装相关的注册客户端。目前，Dubbo-python 只支持 Zookeeper，因此下面的演示将使用 Zookeeper。与之前类似，我们需要克隆 Dubbo-python 源代码并安装它。不过，在这种情况下，我们还需要安装 Zookeeper 客户端。命令如下：
+
+```bash
+git clone https://github.com/apache/dubbo-python.git
+cd dubbo-python && pip install .[zookeeper]
+```
+
+而后，只需启动 `Zookeeper` 并在现有示例中插入以下代码即可：
+
+```python
+# Configure the Zookeeper registry
+registry_config = RegistryConfig.from_url("zookeeper://127.0.0.1:2181")
+bootstrap = Dubbo(registry_config=registry_config)
+
+# Create the client
+client = bootstrap.create_client(reference_config)
+
+# Create and start the server
+bootstrap.create_server(service_config).start()
+```
\ No newline at end of file
diff --git a/content/zh-cn/overview/mannual/python-sdk/streaming.md b/content/zh-cn/overview/mannual/python-sdk/streaming.md
new file mode 100644
index 0000000..a831ad7a
--- /dev/null
+++ b/content/zh-cn/overview/mannual/python-sdk/streaming.md
@@ -0,0 +1,107 @@
+---
+aliases:
+ - /zh/docs3-v2/python-sdk/streaming/
+ - /zh-cn/docs3-v2/python-sdk/streaming/
+description: 在 Dubbo Python 使用 Client streaming、Server streaming、Bidirectional streaming 模型的服务。
+linkTitle: Streaming 通信模型
+title: Streaming 通信模型
+type: docs
+weight: 3
+---
+
+在此查看完整[示例](https://github.com/apache/dubbo-python/tree/main/samples/stream)。
+
+Dubbo-Python 支持流式调用，包括 `ClientStream`、`ServerStream` 和 `BidirectionalStream` 三种模式。
+
+在流式调用中，操作可以分为写入流和读取流两部分。对于 `ClientStream`，是多次写入、单次读取；对于 `ServerStream`，是单次写入、多次读取；而 `BidirectionalStream` 支持多次写入和多次读取。
+
+### 写入流
+
+流式调用的写入操作分为单次写入（`ServerStream`）和多次写入（`ClientStream` 和 `BidirectionalStream`）。
+
+### 单次写入
+
+单次写入流的调用方式与 unary 模式类似。例如：
+
+```python
+stub.server_stream(greeter_pb2.GreeterRequest(name="hello world from dubbo-python"))
+
+```
+
+### 多次写入
+
+对于多次写入流，用户可以通过迭代器或 `writeStream` 方式写入数据（两者只能选其一）。
+
+1. **迭代器写入**：写入方式类似于 unary 模式，唯一的区别是传入的是迭代器。例如：
+
+ ```python
+ # Use an iterator to send multiple requests
+ def request_generator():
+ for i in ["hello", "world", "from", "dubbo-python"]:
+ yield greeter_pb2.GreeterRequest(name=str(i))
+
+ # Call the remote method and return a read_stream
+ stream = stub.client_stream(request_generator())
+ ```
+
+2. **使用 `writeStream` 写入**：此方法不传入参数，使用空参调用，然后通过 `write` 方法逐条写入数据，写入完成后调用 `done_writing` 方法结束流。例如：
+
+ ```python
+ stream = stub.bi_stream()
+ # Use the write method to send messages
+ stream.write(greeter_pb2.GreeterRequest(name="jock"))
+ stream.write(greeter_pb2.GreeterRequest(name="jane"))
+ stream.write(greeter_pb2.GreeterRequest(name="alice"))
+ stream.write(greeter_pb2.GreeterRequest(name="dave"))
+ # Call done_writing to notify the server that the client has finished writing
+ stream.done_writing()
+ ```
+
+### 读取流
+
+流式调用的读取操作分为单次读取（`ClientStream`）和多次读取（`ServerStream` 和 `BidirectionalStream`）。在流式调用中，无论是哪种模式，返回的都是一个 `ReadStream`。我们可以使用 `read` 方法或迭代器读取数据，针对 `read` 方法，需要注意以下几点：
+
+1. `read` 方法支持 `timeout` 参数，用于设置阻塞等待时间（单位：秒）。
+2. `read` 方法的返回结果可能为三种：所需信息（正常情况）、`None`（等待超时）、`EOF`（读取流结束）。
+
+### 单次读取
+
+调用 `read` 方法一次即可读取数据，例如：
+
+```python
+result = stream.read()
+print(f"Received response: {result.message}")
+
+```
+
+### 多次读取
+
+可以通过多次调用 `read` 方法读取数据，但需要处理 `None` 和 `EOF` 等非期望值。因为 `ReadStream` 实现了 `__iter__` 和 `__next__` 等迭代方法，我们可以通过迭代调用进行多次读取，此方法无需处理非期望值，但不支持设置阻塞超时参数。
+
+1. **迭代调用**（推荐）：
+
+ ```python
+ def client_stream(self, request_iterator):
+ response = ""
+ for request in request_iterator:
+ print(f"Received request: {request.name}")
+ response += f"{request.name} "
+ return greeter_pb2.GreeterReply(message=response)
+
+ ```
+
+2. **多次调用 `read` 方法**：
+
+ ```python
+ # Use read method to receive messages
+ # If no message arrives within the specified time, returns None
+ # If the server has finished sending messages, returns EOF
+ while True:
+ i = stream.read(timeout=0.5)
+ if i is dubbo.classes.EOF:
+ break
+ elif i is None:
+ print("No message received")
+ continue
+ print(f"Received response: {i.message}")
+ ```
\ No newline at end of file
