refactor(v2): promote SDK implementation to package root

Finalize the 2.0 package layout, move 1.x APIs under legacy_1x, and align tests, packaging, CI, examples, and documentation with the new import paths.

Author: zhansheng.lzs

.github/workflows/unit_test.yml

@@ -9,7 +9,7 @@ on:
       - 'main'
 
 jobs:
-  test:
+  current:
     if: ${{ !(github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, 'docs:')) }}
 
     runs-on: ${{ matrix.os }}
@@ -18,7 +18,6 @@ jobs:
         os: [ ubuntu-latest ]
         python-version: [ '3.9', '3.12', '3.13', '3.14' ]
 
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -55,10 +54,55 @@ jobs:
         run: |
           python -m pip list --format=columns
 
-      - name: Run tests with coverage
+      - name: Run current tests with coverage
         run: |
-          coverage run -m pytest tests/unit
+          coverage run -m pytest tests --ignore=tests/legacy_1x
 
       - name: Generate coverage report
         run: |
           coverage report -m
+
+  legacy:
+    if: ${{ !(github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, 'docs:')) }}
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ ubuntu-latest ]
+        python-version: [ '3.9', '3.12', '3.13', '3.14' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Update setuptools
+        run: |
+          pip install --upgrade pip
+          pip install setuptools==68.2.2 wheel==0.41.2
+
+      - name: Set PYTHONPATH
+        run: |
+          echo "PYTHONPATH=$PYTHONPATH:${{ github.workspace }}/src" >> $GITHUB_ENV
+
+      - name: Install dependencies
+        run: |
+          export PIP_DEFAULT_TIMEOUT=300
+          pip install -r requirements.txt
+          pip install -r requirements-test.txt
+
+      - name: Run archived legacy tests
+        run: |
+          python -m pytest tests/legacy_1x

.gitignore

@@ -144,5 +144,5 @@ cython_debug/
 # Local design/analysis docs — kept out of the public repo
 /md/
 
-# Local PyPI investigation tooling; the CI guard lives in tests/unit/.
+# Local PyPI investigation tooling; the CI guard lives in tests/legacy_1x/unit/.
 /scripts/

.pre-commit-config.yaml

@@ -3,36 +3,36 @@ repos:
     rev: v4.3.0
     hooks:
       - id: check-ast
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: sort-simple-yaml
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: check-yaml
         exclude: |
           (?x)^(
               meta.yaml
-              | tests/legacy/
+              | tests/legacy_1x/legacy/
           )$
       - id: check-xml
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: check-toml
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: check-docstring-first
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: check-json
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: fix-encoding-pragma
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: detect-private-key
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
       - id: trailing-whitespace
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
   - repo: https://github.com/asottile/add-trailing-comma
     rev: v3.1.0
     hooks:
       - id: add-trailing-comma
         # examples/01_atomic_capabilities/audio is ported verbatim from the sibling repo's
         # samples/ tree, whose hooks exempt samples/.
-        exclude: ^(tests/legacy|examples/01_atomic_capabilities/audio)/
+        exclude: ^(tests/legacy_1x/legacy|examples/01_atomic_capabilities/audio)/
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.7.0
     hooks:
@@ -45,7 +45,7 @@ repos:
           pb2\.py$
           | grpc\.py$
           | ^docs
-          | ^tests/legacy/
+          | ^tests/legacy_1x/legacy/
           | ^examples/01_atomic_capabilities/audio/
           | \.html$
           | \.pyi$
@@ -67,13 +67,13 @@ repos:
     hooks:
       - id: black
         args: [ --line-length=79 ]
-        exclude: ^(tests/legacy|examples/01_atomic_capabilities/audio)/
+        exclude: ^(tests/legacy_1x/legacy|examples/01_atomic_capabilities/audio)/
   - repo: https://github.com/PyCQA/flake8
     rev: 6.1.0
     hooks:
       - id: flake8
         args: [ "--extend-ignore=E203"]
-        exclude: ^(tests/legacy|examples/01_atomic_capabilities/audio)/
+        exclude: ^(tests/legacy_1x/legacy|examples/01_atomic_capabilities/audio)/
   - repo: https://github.com/pylint-dev/pylint
     rev: v3.0.2
     hooks:
@@ -122,6 +122,7 @@ repos:
           --disable=C0114,  # Disable missing module docstring for quick dev
           --disable=C0115,  # Disable missing class docstring for quick dev
           --disable=C0116,  # Disable missing function or method docstring for quick dev
+          --disable=E0603,  # Absolute self-imports and lazy exports in reinforcement
         ]
       # Tests get their own entry (pylint 3.0.2 discovers rcfiles from the
       # invocation CWD, not per linted-file directory, so a tests/pylintrc
@@ -132,7 +133,7 @@ repos:
       - id: pylint
         name: pylint (tests)
         files: ^tests/
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/
         args: [
           --disable=W0511,
           --disable=W0718,
@@ -190,19 +191,19 @@ repos:
     hooks:
       - id: eslint
         files: \.(js|jsx)$
-        exclude: '(.*js_third_party.*|^tests/legacy/)'
+        exclude: '(.*js_third_party.*|^tests/legacy_1x/legacy/)'
         args: [ '--fix' ]
   - repo: https://github.com/thibaudcolas/pre-commit-stylelint
     rev: v14.4.0
     hooks:
       - id: stylelint
         files: \.(css)$
-        exclude: '(.*css_third_party.*|^tests/legacy/)'
+        exclude: '(.*css_third_party.*|^tests/legacy_1x/legacy/)'
         args: [ '--fix' ]
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: 'v3.0.0'
     hooks:
       - id: prettier
         additional_dependencies: [ 'prettier@3.0.0' ]
         files: \.(tsx?)$
-        exclude: ^tests/legacy/
+        exclude: ^tests/legacy_1x/legacy/

MANIFEST.in

@@ -1,4 +1,4 @@
-include dashscope/v2/tokenizers/qwen.tiktoken
+include dashscope/tokenizers/qwen.tiktoken
 include dashscope/py.typed
 include dashscope/__init__.pyi
 include NOTICE

README.md

@@ -194,7 +194,7 @@ By default each frame is incremental. Pass `incremental_output=False` to receive
 Failures raise a typed `DashScopeError` by default (both non-2xx HTTP statuses and HTTP-200-with-a-business-error land here):
 
 ```python
-from dashscope.v2 import errors
+from dashscope import errors
 
 try:
     client.chat.completions.create(model="qwen-plus", messages=["hi"])
@@ -447,6 +447,32 @@ The 1.x module-level API is unchanged and still supported — you can adopt 2.0
 | `dashscope.set_region(region, workspace_id)` | `dashscope.Client(region=..., workspace=...)` |
 | OpenAI-compatible via `dashscope.aigc.chat_completion.Completions` | `dashscope.Client(protocol="openai")` |
 
+### Package layout and compatibility
+
+The 2.0 implementation is directly under `dashscope`; the former
+`dashscope.v2` namespace has been removed. Existing root 1.x exports remain
+available. Old deep modules such as `dashscope.aigc` and `dashscope.client`
+have moved under `dashscope.legacy_1x`. The 2.0 Agentic RL workflow lives in
+`dashscope.finetune`; its 1.x job-management surface is under
+`dashscope.legacy_1x.finetune`.
+
+`dashscope.save_api_key` now comes from `dashscope._config`. It accepts an
+optional key-file path, expands `~`, creates missing parent directories, and
+writes UTF-8. Logs from the current client use the independent
+`dashscope._logging` logger hierarchy and do not reconfigure the shared
+`dashscope` root logger.
+
+### Development tests
+
+```bash
+python -m pytest tests --ignore=tests/legacy_1x -q  # current
+python -m pytest tests/legacy_1x -q                 # archived compatibility
+python -m pytest tests -q                           # everything
+```
+
+For current coverage, run `coverage run -m pytest tests
+--ignore=tests/legacy_1x`, then `coverage report -m`.
+
 ## License
 
 This project is licensed under the Apache License (Version 2.0).

README_zh.md

@@ -194,7 +194,7 @@ for text in stream.text_stream:            # 内容增量
 失败默认抛出类型化的 `DashScopeError`（非 2xx 的 HTTP 状态码，以及 HTTP 200 但业务报错，都会归入这里）：
 
 ```python
-from dashscope.v2 import errors
+from dashscope import errors
 
 try:
     client.chat.completions.create(model="qwen-plus", messages=["hi"])
@@ -447,6 +447,29 @@ examples/
 | `dashscope.set_region(region, workspace_id)` | `dashscope.Client(region=..., workspace=...)` |
 | OpenAI 兼容通过 `dashscope.aigc.chat_completion.Completions` | `dashscope.Client(protocol="openai")` |
 
+### 包布局与兼容策略
+
+2.0 实现直接位于 `dashscope` 根包，原 `dashscope.v2` 命名空间已移除。
+包根已有的 1.x 导出继续可用；`dashscope.aigc`、`dashscope.client` 等旧
+deep import 已移至 `dashscope.legacy_1x` 下。2.0 Agentic RL 工作流位于
+`dashscope.finetune`，1.x 任务管理接口位于 `dashscope.legacy_1x.finetune`。
+
+`dashscope.save_api_key` 现在来自 `dashscope._config`，仍接受可选的 key
+文件路径，并会展开 `~`、创建缺失的父目录、按 UTF-8 写入。当前客户端使用
+独立的 `dashscope._logging` logger 层级，不会重新配置共享的 `dashscope`
+根 logger。
+
+### 开发测试
+
+```bash
+python -m pytest tests --ignore=tests/legacy_1x -q  # 当前实现
+python -m pytest tests/legacy_1x -q                 # 归档兼容套件
+python -m pytest tests -q                           # 全量
+```
+
+当前实现的 coverage 使用 `coverage run -m pytest tests
+--ignore=tests/legacy_1x`，随后执行 `coverage report -m`。
+
 ## 许可证
 
 本项目采用 Apache License (Version 2.0) 许可证。

dashscope/__init__.py

@@ -41,7 +41,6 @@
 from dashscope.legacy_1x.api_entities.http_request import (
     close_shared_sync_session,
 )
-from dashscope.legacy_1x.common.api_key import save_api_key
 from dashscope.legacy_1x.common.env import (
     MAAS_REGIONS,
     api_key,
@@ -51,8 +50,8 @@
     base_websocket_api_url,
     validate_workspace_id,
 )
-from dashscope.finetune.deployments import Deployments
-from dashscope.finetune.finetunes import FineTunes
+from dashscope.legacy_1x.finetune.deployments import Deployments
+from dashscope.legacy_1x.finetune.finetunes import FineTunes
 from dashscope.legacy_1x.embeddings.batch_text_embedding import (
     BatchTextEmbedding,
 )
@@ -78,8 +77,13 @@
     list_tokenizers,
 )
 
-# dashscope 2.0 public surface (implementation lives in dashscope/v2/).
-from dashscope.v2 import AsyncClient, Client, WsConnection, chat, settings
+# dashscope 2.0 public surface.
+from dashscope import errors
+from dashscope._config import Config, Settings, save_api_key, settings
+from dashscope._quickstart import chat
+from dashscope.client import AsyncClient, Client
+from dashscope.errors import DashScopeError, ErrorCode
+from dashscope.transport.ws_connection import WsConnection, WsTask
 
 # cn-beijing defaults to the legacy dashscope.aliyuncs.com endpoints;
 # its MaaS URLs are only reachable via an explicit set_region() call.
@@ -229,8 +233,14 @@ def __dir__():
     # dashscope 2.0
     "AsyncClient",
     "Client",
+    "Config",
+    "DashScopeError",
+    "ErrorCode",
+    "Settings",
     "WsConnection",
+    "WsTask",
     "chat",
+    "errors",
     "set_region",
 ]
 

dashscope/__init__.pyi

@@ -14,11 +14,18 @@ from typing import (
 # ---------------------------------------------------------------------------
 # dashscope 2.0
 # ---------------------------------------------------------------------------
-from dashscope.v2 import AsyncClient as AsyncClient
-from dashscope.v2 import Client as Client
-from dashscope.v2 import WsConnection as WsConnection
-from dashscope.v2 import chat as chat
-from dashscope.v2 import settings as settings
+from dashscope import errors as errors
+from dashscope._config import Config as Config
+from dashscope._config import Settings as Settings
+from dashscope._config import save_api_key as save_api_key
+from dashscope._config import settings as settings
+from dashscope._quickstart import chat as chat
+from dashscope.client import AsyncClient as AsyncClient
+from dashscope.client import Client as Client
+from dashscope.errors import DashScopeError as DashScopeError
+from dashscope.errors import ErrorCode as ErrorCode
+from dashscope.transport.ws_connection import WsConnection as WsConnection
+from dashscope.transport.ws_connection import WsTask as WsTask
 
 # ---------------------------------------------------------------------------
 # Config
@@ -29,7 +36,9 @@ base_compatible_api_url: str
 base_http_api_url: str
 base_websocket_api_url: str
 
-def save_api_key(api_key: str, file_path: Optional[str] = ...) -> None: ...
+def save_api_key(
+    api_key: str, api_key_file_path: Optional[str] = ...
+) -> None: ...
 def close_shared_aio_session() -> None: ...
 def close_shared_sync_session() -> None: ...
 def set_region(region: str, workspace_id: Optional[str] = ...) -> None: ...

dashscope/v2/_config.py dashscope/_config.pydashscope/v2/_config.py renamed to dashscope/_config.py

@@ -321,7 +321,7 @@ def clear(self) -> None:
             self._explicit.clear()
         if had_log_level:
             # pylint: disable=import-outside-toplevel
-            from dashscope.v2._logging import reset_log_level
+            from dashscope._logging import reset_log_level
 
             reset_log_level()
 
@@ -496,7 +496,7 @@ def log_level(self) -> Optional[str]:
     @log_level.setter
     def log_level(self, value: str) -> None:
         # pylint: disable=import-outside-toplevel
-        from dashscope.v2._logging import set_log_level
+        from dashscope._logging import set_log_level
 
         set_log_level(value)
         with self._lock: