refactor(v2): Refactor configuration and session management modules

- Migrate save_api_key function from common module to v2._config module
- Update comments to reflect the relocation of key-file authentication implementation
- Move SDK session ID implementation to shared module dashscope._shared
- Modify v2 package re-export strategy, no longer importing save_api_key from 1.x
- Adjust incremental output parameter check logic in chat completion module
- Update related tests to verify new module structure and functionality migration

Author: luk384090-cloud

dashscope/common/_sdk_session.py

@@ -1,43 +1,11 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) Alibaba, Inc. and its affiliates.
-"""Single process-wide SDK session id.
+"""Compatibility re-export; the implementation moved to ``dashscope._shared``.
 
-The ``x-dashscope-sdk-session-id`` header lets server-side access logs
-group every request one SDK session makes. A process can emit requests
-through both stacks at once -- the 1.x API classes and the 2.0 transport
--- and the 2.0 client even delegates some calls (rl, agentstudio)
-straight into 1.x. If each stack minted its own id, one logical session
-would split across several ids and the grouping breaks.
-
-This leaf module is the one source of truth both import. It depends only
-on the stdlib so it can be pulled in from anywhere without dragging
-``dashscope/__init__`` (and its v2 surface) into a cycle.
-
-The embedded ``acli`` deliberately keeps its own id: it is a one-way
-sync copy of the agenticCLI repo (design doc §3.2), so wiring it to this
-module would be silently reverted by the next sync and cannot be
-upstreamed as written.
+The session id state lives only in ``dashscope._shared._sdk_session`` so a
+process keeps exactly one id. Import from there in new code.
 """
 
-from __future__ import annotations
-
-import threading
-import uuid
-
-_session_id = None
-_lock = threading.Lock()
-
-
-def sdk_session_id() -> str:
-    """Return this process's session id, generating it on first use.
+from dashscope._shared._sdk_session import sdk_session_id
 
-    Double-checked locking: concurrent callers must not each mint their
-    own id and break the one-id-per-process invariant log grouping
-    relies on.
-    """
-    global _session_id  # pylint: disable=global-statement
-    if _session_id is None:
-        with _lock:
-            if _session_id is None:
-                _session_id = uuid.uuid4().hex
-    return _session_id
+__all__ = ["sdk_session_id"]

dashscope/common/utils.py

@@ -15,15 +15,15 @@
 import aiohttp
 import requests
 
+from dashscope._shared._sdk_session import sdk_session_id
 from dashscope.api_entities.dashscope_response import DashScopeAPIResponse
-from dashscope.common._sdk_session import sdk_session_id
 from dashscope.common.api_key import get_default_api_key
 from dashscope.common.constants import SSE_CONTENT_TYPE
 from dashscope.common.logging import logger
 from dashscope.version import __version__
 
 # Shared with the 2.0 transport so one process reports one
-# x-dashscope-sdk-session-id across both stacks (see _sdk_session;
+# x-dashscope-sdk-session-id across both stacks (see _shared._sdk_session;
 # acli deliberately keeps its own, it is a one-way sync copy).
 _SDK_SESSION_ID = sdk_session_id()
 

dashscope/v2/__init__.py

@@ -7,16 +7,15 @@
 """
 
 from dashscope.v2 import errors
-from dashscope.v2._config import Config, Settings, settings
+from dashscope.v2._config import Config, Settings, save_api_key, settings
 from dashscope.v2._quickstart import chat
 from dashscope.v2.client import AsyncClient, Client
 from dashscope.v2.errors import DashScopeError, ErrorCode
 from dashscope.v2.transport.ws_connection import WsConnection, WsTask
 
-# Offline helpers delegated to the 1.x implementation, re-exported so the
-# 2.0 namespace is self-contained (same objects the package root already
-# exposes): the local tiktoken wrapper and the key-file writer.
-from dashscope.common.api_key import save_api_key  # noqa: E402
+# Offline helper still delegated to the 1.x implementation, re-exported so
+# the 2.0 namespace is self-contained (same objects the package root
+# already exposes): the local tiktoken wrapper.
 from dashscope.tokenizers import (  # noqa: E402
     get_tokenizer,
     list_tokenizers,

dashscope/v2/_config.py

@@ -136,8 +136,8 @@
 _LOG_ENV = "DASHSCOPE_LOG"
 _CONFIG_PATH_ENV = "DASHSCOPE_CONFIG"
 _DEFAULT_CONFIG_PATH = "~/.dashscope/config.toml"
-# 1.x key-file auth (dashscope.save_api_key): env-specified path first,
-# then the default file -- the lowest api_key tier.
+# Key-file auth (save_api_key, below): env-specified path first, then the
+# default file -- the lowest api_key tier.
 _API_KEY_FILE_PATH_ENV = "DASHSCOPE_API_KEY_FILE_PATH"
 _DEFAULT_API_KEY_FILE_PATH = "~/.dashscope/api_key"
 
@@ -542,6 +542,26 @@ def _api_key_from_file() -> Optional[str]:
         return None
 
 
+def save_api_key(
+    api_key: str, api_key_file_path: Optional[str] = None
+) -> None:
+    """Store an api key in the key file ``_api_key_from_file`` reads back.
+
+    Without an explicit path this writes ``~/.dashscope/api_key``, the same
+    fixed location the 1.x ``dashscope.save_api_key`` uses, so a key stored
+    through either stack is picked up by both. As in 1.x,
+    ``DASHSCOPE_API_KEY_FILE_PATH`` redirects only the read, not the write.
+    """
+    target = (
+        _DEFAULT_API_KEY_FILE_PATH
+        if api_key_file_path is None
+        else api_key_file_path
+    )
+    path = Path(target).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(api_key, encoding="utf-8")
+
+
 def _pick(
     explicit: Any,
     settings_value: Any,

dashscope/v2/resources/chat/completions.py

@@ -14,13 +14,15 @@
 
 from typing_extensions import Literal
 
-from dashscope.utils.param_utils import ParamUtil
 from dashscope.v2.errors import response_error
 from dashscope.v2.protocols.base import ChatRequest
 from dashscope.v2.resources._oss import (
     OSS_RESOLVE_HEADERS,
     upload_message_media,
 )
+from dashscope.v2.resources.chat._params import (
+    should_modify_incremental_output,
+)
 from dashscope.v2.types.common import Usage, with_headers
 from dashscope.v2.types.completions import (
     ChatCompletion,
@@ -114,7 +116,7 @@ def _build_request(
     merge_incremental = False
     if stream and incremental_output is not None:
         if client.protocol.name == "native":
-            server_side = not ParamUtil.should_modify_incremental_output(model)
+            server_side = not should_modify_incremental_output(model)
             if incremental_output is False and not server_side:
                 merge_incremental = True
                 # 1.x also forces the wire incremental while merging

dashscope/v2/transport/_ident.py

@@ -20,8 +20,8 @@
 # One process-wide session id shared with the 1.x API classes, so a
 # single SDK session is not split across ids when the 2.0 client
 # delegates calls (rl, agentstudio) into 1.x. (acli keeps its own: it is
-# a one-way sync copy, see common/_sdk_session.)
-from dashscope.common._sdk_session import sdk_session_id
+# a one-way sync copy, see _shared/_sdk_session.)
+from dashscope._shared._sdk_session import sdk_session_id
 
 SDK_CLIENT_HEADER = "x-dashscope-sdk-client"
 SDK_SESSION_ID_HEADER = "x-dashscope-sdk-session-id"

tests/unit/test_sdk_headers.py

@@ -59,6 +59,20 @@ def test_python_sdk_client_header():
         assert headers[SESSION_HEADER] == _SDK_SESSION_ID
 
 
+def test_session_id_has_one_source_across_stacks():
+    # A process using the 1.x classes and the 2.0 client at once must
+    # report one id, or server-side log grouping splits a single logical
+    # session. The legacy deep path re-exports the neutral leaf rather
+    # than holding its own copy of the state.
+    from dashscope._shared._sdk_session import sdk_session_id as leaf
+    from dashscope.common._sdk_session import sdk_session_id as via_1x
+    from dashscope.v2.transport._ident import sdk_session_id as via_v2
+
+    assert via_1x is leaf
+    assert via_v2 is leaf
+    assert leaf() == _SDK_SESSION_ID
+
+
 def test_acli_client_header():
     # pylint: disable=protected-access
     print("\n=== acli: x-dashscope-sdk-client ===")

tests/v2/test_config.py

@@ -462,6 +462,38 @@ def test_save_api_key_roundtrip(clean_env, tmp_path, monkeypatch):
     assert cfg.api_key == "sk-saved"
 
 
+def test_save_api_key_writes_the_default_path(
+    clean_env,
+    tmp_path,
+    monkeypatch,
+):
+    from dashscope.v2 import _config
+
+    default = tmp_path / "home" / ".dashscope" / "api_key"
+    monkeypatch.setattr(_config, "_DEFAULT_API_KEY_FILE_PATH", str(default))
+    # The env var outranks the default path when reading; drop it so this
+    # exercises the write-default / read-default pair.
+    monkeypatch.delenv("DASHSCOPE_API_KEY_FILE_PATH", raising=False)
+
+    _config.save_api_key("sk-default")
+
+    assert default.read_text(encoding="utf-8") == "sk-default"
+    cfg = resolve_config(config_path="/nonexistent/config.toml")
+    assert cfg.api_key == "sk-default"
+
+
+def test_save_api_key_accepts_a_bare_filename(
+    clean_env, tmp_path, monkeypatch
+):
+    from dashscope.v2 import save_api_key
+
+    # 1.x does os.makedirs(os.path.dirname(path)), which raises when the
+    # path has no directory component; the v2 writer resolves against cwd.
+    monkeypatch.chdir(tmp_path)
+    save_api_key("sk-bare", "api_key")
+    assert (tmp_path / "api_key").read_text(encoding="utf-8") == "sk-bare"
+
+
 def test_invalid_protocol(clean_env):
     with pytest.raises(ValueError, match="invalid protocol"):
         resolve_config(protocol="grpc", config_path="/nonexistent/config.toml")

tests/v2/test_package_root.py

@@ -50,21 +50,31 @@ def test_legacy_exports_untouched():
     assert hasattr(dashscope, "save_api_key")
 
 
-def test_v2_namespace_reexports_1x_offline_helpers():
-    # The 2.0 namespace delegates the offline helpers to 1.x instead of
-    # re-implementing them (same objects the package root exposes).
+def test_v2_namespace_reexports_1x_tokenizers():
+    # The local tiktoken wrapper is still delegated to 1.x rather than
+    # re-implemented (same objects the package root exposes).
     from dashscope import v2
-    from dashscope.common.api_key import save_api_key as save_1x
     from dashscope.tokenizers import get_tokenizer as get_1x
     from dashscope.tokenizers import list_tokenizers as list_1x
 
-    assert v2.save_api_key is save_1x
     assert v2.get_tokenizer is get_1x
     assert v2.list_tokenizers is list_1x
-    for name in ("get_tokenizer", "list_tokenizers", "save_api_key"):
+    for name in ("get_tokenizer", "list_tokenizers"):
         assert name in v2.__all__
 
 
+def test_v2_owns_save_api_key():
+    # The key-file writer is v2-native, so reaching for it does not pull in
+    # the 1.x package root; the package root keeps its own 1.x writer.
+    from dashscope import v2
+    from dashscope.common.api_key import save_api_key as save_1x
+
+    assert v2.save_api_key.__module__ == "dashscope.v2._config"
+    assert v2.save_api_key is not save_1x
+    assert dashscope.save_api_key is save_1x
+    assert "save_api_key" in v2.__all__
+
+
 def test_v2_get_tokenizer_encodes_locally():
     from dashscope import v2
     from dashscope.common.error import UnsupportedModel

tests/v2/test_transport.py

@@ -430,7 +430,7 @@ async def test_async_sdk_identification_headers(no_sleep):
 
 
 def test_sdk_session_id_cached_per_process():
-    from dashscope.common import _sdk_session
+    from dashscope._shared import _sdk_session
     from dashscope.v2.transport import _ident
 
     original = _sdk_session._session_id