refactor: add HTTP/2 sync support, reorganize modules, and migrate docstrings to Google style

Author: cnzakii

.github/workflows/license-check.yaml

@@ -1,12 +1,7 @@
 name: License Template Check
 
-on:
-  pull_request:
-    types:
-      - opened
-      - synchronize
-      - reopened
-  push:
+on: [push, pull_request]
+
 
 
 jobs:

.github/workflows/publish.yml

@@ -1,31 +1,37 @@
-name: Publish
+name: Publish to PyPI
+
 on:
   release:
+    types: [released]
     branches: [main]
-    types: [created]
 
 
 jobs:
   build:
-    name: Build
+    name: Build Python Package
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
       with:
         persist-credentials: false
-    - name: Set up Python 3.12
+
+    - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.12"
+        python-version-file: ".python-version"
+
     - name: Set up uv
       uses: astral-sh/setup-uv@v6
       with:
         version: "0.7.4"
         enable-cache: true
-    - name: Sync build environment
+
+    - name: Sync build dependencies
       run: "uv sync --only-group build"
+
     - name: Build distribution
       run: "uv run hatch build"
+
     - name: Upload distribution artifacts
       uses: actions/upload-artifact@v4
       with:
@@ -34,19 +40,22 @@ jobs:
 
   publish-to-pypi:
     name: Publish to PyPI
-    needs:
-        - build
+    needs: build
     runs-on: ubuntu-latest
+
     environment:
       name: pypi
       url: https://pypi.org/project/apache-dubbo/
+
     permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      id-token: write  # Required for Trusted Publishing
+
     steps:
       - name: Download distribution artifacts
         uses: actions/download-artifact@v4
         with:
           name: python-package-distributions
           path: dist/
-      - name: Publish to PyPI
+
+      - name: Upload to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yaml

@@ -1,35 +1,37 @@
 name: Lint and Test
+
 on:
-  pull_request:
-    types:
-      - opened
-      - synchronize
-      - reopened
   push:
+  pull_request:
 
 
 jobs:
   lint:
-    name: Lint code
+    name: Lint Code
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
+
+      - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version-file: ".python-version"
+
       - name: Set up uv
         uses: astral-sh/setup-uv@v6
         with:
           version: "0.7.4"
           enable-cache: true
+
       - name: Sync development environment
-        run: "uv sync --group dev"
-      - name: Run Lint
+        run: "uv sync"
+
+      - name: Run Linter
         run: "scripts/lint.sh"
 
+
   tests:
-    name: "Tests (Python ${{ matrix.python-version }} on ${{ matrix.os }})"
+    name: Test on ${{ matrix.os }} / Python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -38,16 +40,20 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
+
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "${{ matrix.python-version }}"
+
       - name: Set up uv
         uses: astral-sh/setup-uv@v6
         with:
           version: "0.7.4"
           enable-cache: true
-      - name: Sync environment
-        run: "uv sync --all-extras --group dev"
-      - name: Run tests
+
+      - name: Sync environment with all extras
+        run: " uv sync --all-extras"
+
+      - name: Run Tests with Coverage
         run: "uv run pytest --cov=src/dubbo --cov-report=term-missing"

docs/CONTRIBUTING.md

@@ -39,8 +39,20 @@ To report a bug or request a feature, use the [GitHub Issue templates](https://g
 
 Our Python code follows the [PEP 8 style guide](https://peps.python.org/pep-0008/) with these adjustments:
 
-1. **Maximum Line Length:** Up to 120 characters.
-2. **Docstrings and Comments:** Use reStructuredText format.
+1. **Maximum Line Length:** Limit lines to 120 characters.
+2. **Docstrings and Comments:** Use Google-style docstrings for all public functions and methods.
+   - Example:
+     ```python
+     def example_method(param1: str, param2: int) -> None:
+         """Example method that does something.
+
+         Args:
+             param1 (str): Description of the first parameter.
+             param2 (int): Description of the second parameter.
+         """
+         # This is an inline comment explaining a specific line
+         print(param1, param2)
+     ```
 3. **Type Hints:** All public functions and methods must include type annotations consistent with [PEP 484](https://peps.python.org/pep-0484/).
 4. **Imports:** Grouped in the order: standard library, third-party, local imports, each separated by a blank line.
 5. **Indentation:** 4 spaces; no tabs.

pyproject.toml

@@ -59,6 +59,7 @@ dependencies = [
     "anyio>=4.9.0",
     "h2>=4.1.0",
     "psutil>=6.0.0",
+    "typing-extensions>=4.13.2; python_version < '3.10'",
 ]
 
 
@@ -72,12 +73,6 @@ Issues = "https://github.com/apache/dubbo/issues"
 zookeeper = [
     "kazoo>=2.10.0",
 ]
-logging-color = [
-    "colorlog>=6.9.0",
-]
-loguru = [
-    "loguru>=0.7.3",
-]
 
 
 [dependency-groups]
@@ -91,6 +86,7 @@ dev = [
     "mypy>=1.15.0",
     "pytest>=8.3.5",
     "pytest-cov>=6.1.1",
+    "pytest-mock>=3.14.1",
 ]
 
 
@@ -130,7 +126,6 @@ replacement = "[$1](https://github.com/apache/dubbo-python/blob/main/$2)"
 # ------------- Ruff settings -------------
 # Top-level
 [tool.ruff]
-target-version = "py39"
 line-length = 120
 extend-exclude = ["**/*_pb2.py"]
 

src/dubbo/bootstrap.py

@@ -0,0 +1,33 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dubbo.common.classes import SingletonBase
+
+
+class Dubbo(SingletonBase):
+    """
+    The main entry point for the Dubbo framework.
+    """
+
+    pass
+
+
+class AsyncDubbo(SingletonBase):
+    """
+    The main entry point for the Dubbo framework.
+    """
+
+    pass

src/dubbo/client.py

@@ -0,0 +1,23 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+class Client:
+    """
+    The main entry point for the Dubbo client.
+    """
+
+    pass

src/dubbo/cluster/loadbalance/__init__.py

@@ -14,6 +14,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from ._base import LoadBalance
+from .base import LoadBalance
 
 __all__ = ["LoadBalance"]

src/dubbo/cluster/loadbalance/_base.py renamed to src/dubbo/cluster/loadbalance/base.py

@@ -24,37 +24,36 @@
 
 
 def get_weight(invoker: Invoker, invocation: Invocation) -> int:
-    """
-    Get the weight of the invoker with warmup capability.
-
-    This method calculates weight based on URL parameters and warming up time.
-    New services need warmup time to be fully functional, during this period
-    their weight is gradually increased.
-
-    :param invoker: The service invoker.
-    :type invoker: Invoker
-    :param invocation: The service invocation context
-    :type invocation: Invocation
-    :return: Calculated weight value (minimum 0)
-    :rtype: int
+    """Get the weight of the invoker with warmup capability.
+
+    Calculates weight based on URL parameters and warmup time. New services
+    need warmup time to be fully functional, during which their weight is
+    gradually increased from 1 to the configured value.
+
+    Args:
+        invoker: The service invoker containing URL configuration.
+        invocation: The service invocation context with method information.
+
+    Returns:
+        Calculated weight value, minimum 0.
     """
     url = invoker.get_url()
     # TODO: Multiple registry scenario, load balance among multiple registries.
     is_multiple = False
 
     # Determine weight based on URL parameters
     if is_multiple:
-        weight = url.get_param_int(constants.WEIGHT_KEY, constants.DEFAULT_WEIGHT)
+        weight = url.get_param_int(constants.WEIGHT_KEY, constants.DEFAULT_WEIGHT_VALUE)
     else:
-        weight = url.get_method_param_int(invocation.method_name, constants.WEIGHT_KEY, constants.DEFAULT_WEIGHT)
+        weight = url.get_method_param_int(invocation.method_name, constants.WEIGHT_KEY, constants.DEFAULT_WEIGHT_VALUE)
 
         # Apply warmup adjustment for positive weights only
         if weight > 0:
             timestamp = url.get_param_int(constants.TIMESTAMP_KEY, 0)
             if timestamp > 0:
                 # Calculate service uptime in milliseconds
                 uptime = max(int(time.time() * 1000) - timestamp, 1)
-                warmup = url.get_param_int(constants.WARMUP_KEY, constants.DEFAULT_WARMUP)
+                warmup = url.get_param_int(constants.WARMUP_KEY, constants.DEFAULT_WARMUP_VALUE)
 
                 # Adjust weight during warmup period
                 if 0 < uptime < warmup:
@@ -67,22 +66,22 @@ def get_weight(invoker: Invoker, invocation: Invocation) -> int:
 
 
 class LoadBalance(abc.ABC):
-    """
-    The load balance interface.
+    """Base class for load balancing strategies.
 
+    Defines the interface for selecting an invoker from a list of available
+    invokers based on the load balancing algorithm implementation.
     """
 
     @abc.abstractmethod
     def select(self, invokers: list[Invoker], url: URL, invocation: Invocation) -> Optional[Invoker]:
-        """
-        Select an invoker from the list.
-        :param invokers: The invokers.
-        :type invokers: List[Invoker]
-        :param url: The URL.
-        :type url: URL
-        :param invocation: The invocation.
-        :type invocation: Invocation
-        :return: The selected invoker. If no invoker is selected, return None.
-        :rtype: Optional[Invoker]
+        """Select an invoker from the available invokers list.
+
+        Args:
+            invokers: List of available service invokers.
+            url: The request URL with configuration parameters.
+            invocation: The service invocation context.
+
+        Returns:
+            The selected invoker, or None if no suitable invoker is found.
         """
         raise NotImplementedError()