dashscope 1.27.4__tar.gz → 1.27.6__tar.gz

{dashscope-1.27.4 → dashscope-1.27.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dashscope
-Version: 1.27.4
+Version: 1.27.6
 Summary: dashscope client sdk library
 Home-page: https://dashscope.aliyun.com/
 Author: Alibaba Cloud
@@ -12,11 +12,13 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.8.0
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: LICENSE.certifi
@@ -28,35 +30,35 @@ Requires-Dist: cryptography
 Requires-Dist: certifi
 Requires-Dist: typer>=0.9.0
 Requires-Dist: rich>=13.0.0
-Requires-Dist: httpx>=0.25.0
+Requires-Dist: httpx>=0.27.0
 Requires-Dist: httpx-sse>=0.4.0
 Requires-Dist: typing_extensions>=4.0
 Provides-Extra: tokenizer
 Requires-Dist: tiktoken; extra == "tokenizer"
 Provides-Extra: acli
 Requires-Dist: prompt-toolkit>=3.0; extra == "acli"
-Requires-Dist: textual>=0.50; extra == "acli"
+Requires-Dist: textual<9,>=0.50; extra == "acli"
 Requires-Dist: PyYAML>=6.0; extra == "acli"
 Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "acli"
 Provides-Extra: acli-anthropic
-Requires-Dist: anthropic>=0.40; extra == "acli-anthropic"
+Requires-Dist: anthropic<2,>=0.40; extra == "acli-anthropic"
 Provides-Extra: acli-openai
-Requires-Dist: openai>=1.30; extra == "acli-openai"
+Requires-Dist: openai<4,>=1.30; extra == "acli-openai"
 Provides-Extra: acli-voice
 Requires-Dist: sounddevice>=0.4; extra == "acli-voice"
 Requires-Dist: numpy>=1.20; extra == "acli-voice"
 Provides-Extra: acli-camera
-Requires-Dist: opencv-python>=4.5; extra == "acli-camera"
+Requires-Dist: opencv-python-headless>=4.5; extra == "acli-camera"
 Provides-Extra: acli-all
 Requires-Dist: prompt-toolkit>=3.0; extra == "acli-all"
-Requires-Dist: textual>=0.50; extra == "acli-all"
+Requires-Dist: textual<9,>=0.50; extra == "acli-all"
 Requires-Dist: PyYAML>=6.0; extra == "acli-all"
 Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "acli-all"
-Requires-Dist: anthropic>=0.40; extra == "acli-all"
-Requires-Dist: openai>=1.30; extra == "acli-all"
+Requires-Dist: anthropic<2,>=0.40; extra == "acli-all"
+Requires-Dist: openai<4,>=1.30; extra == "acli-all"
 Requires-Dist: sounddevice>=0.4; extra == "acli-all"
 Requires-Dist: numpy>=1.20; extra == "acli-all"
-Requires-Dist: opencv-python>=4.5; extra == "acli-all"
+Requires-Dist: opencv-python-headless>=4.5; extra == "acli-all"
 Provides-Extra: rl
 Requires-Dist: pydantic>=2.0; extra == "rl"
 Requires-Dist: tenacity; extra == "rl"
@@ -132,7 +134,7 @@ else:
 
 ## API Key Authentication
 
-The SDK uses API key for authentication. Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key.
+The SDK uses API key for authentication. To obtain an API Key, see [How to get an API Key](https://help.aliyun.com/en/model-studio/get-api-key). Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key.
 
 ### Using the API Key
 
@@ -169,12 +171,94 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
 
 ```
 
+## Region and Endpoint Configuration
+
+By default the SDK sends requests to the China (Beijing) public endpoint `dashscope.aliyuncs.com`. If your Model Studio (Bailian) workspace lives in another region, switch the endpoint before making calls.
+
+### Using `set_region`
+
+`dashscope.set_region(region, workspace_id)` points the HTTP, WebSocket and OpenAI-compatible base URLs at the given region in a single call. `workspace_id` is required and is used as the endpoint subdomain.
+
+```python
+import dashscope
+
+# Switch to the Singapore region for workspace "ws-xxx123"
+dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
+
+# All subsequent calls use:
+#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
+print(dashscope.base_http_api_url)
+```
+
+Supported regions:
+
+| Region | Location |
+|--------|----------|
+| `cn-beijing` | China (Beijing) |
+| `cn-hongkong` | China (Hong Kong) |
+| `ap-southeast-1` | Singapore |
+| `ap-northeast-1` | Japan (Tokyo) |
+| `eu-central-1` | Germany (Frankfurt) |
+| `us-east-1` | US (Virginia) |
+
+> **API keys are region-specific.** Each region issues its own API keys (`sk-` prefix) in its Model Studio console, and keys cannot be mixed across regions — using a key from another region fails with `401`. Switch `api_key` together with the region.
+
+Region-specific notes:
+
+- WebSocket endpoints (`wss://.../api-ws/v1/inference`) are only served in `cn-beijing` and `ap-southeast-1`. `set_region` still sets `base_websocket_api_url` for every region, but WebSocket-based realtime APIs (realtime speech recognition/synthesis, multimodal dialog, etc.) are not available in the other regions.
+- `eu-central-1` / `ap-northeast-1`: the deployment scope (Global, or EU / Japan) is chosen when the workspace is created in the console, not per API call.
+- `us-east-1`: model names with the `-us` suffix (e.g. `qwen-plus-us`) restrict inference to the US; names without the suffix default to global inference.
+- Batch inference, model fine-tuning and application development are currently only available in `cn-beijing` and `ap-southeast-1`.
+
+> `set_region` updates process-wide globals, so it is not concurrency-safe when a single process talks to multiple regions at the same time. Call it once at startup, or re-call it before each switch.
+
+### Using environment variables
+
+You can also select the region without code:
+
+```shell
+export DASHSCOPE_API_REGION='ap-southeast-1'   # default: cn-beijing
+export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # used to resolve the endpoint subdomain
+```
+
+When a MaaS region is set via `DASHSCOPE_API_REGION`, the SDK builds the regional endpoints and substitutes `DASHSCOPE_WORKSPACE_ID` into them. You can also override each base URL directly:
+
+| Environment variable | Overrides |
+|----------------------|-----------|
+| `DASHSCOPE_HTTP_BASE_URL` | HTTP endpoint (`dashscope.base_http_api_url`) |
+| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket endpoint (`dashscope.base_websocket_api_url`) |
+| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible endpoint (`dashscope.base_compatible_api_url`) |
+
+`set_region` always builds workspace-exclusive endpoints. Some regions also offer shared domains without a workspace subdomain — `dashscope.aliyuncs.com` (Beijing), `dashscope-intl.aliyuncs.com` (Singapore) and `dashscope-us.aliyuncs.com` (US Virginia); use the override variables above to point at them.
+
+### OpenAI-compatible chat completions
+
+The SDK exposes an OpenAI-compatible chat completions entry that talks to `dashscope.base_compatible_api_url` (request path `chat/completions`) — no extra `openai` package required. It follows the region configured above.
+
+```python
+import dashscope
+from dashscope.aigc.chat_completion import Completions
+
+dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
+
+response = Completions.create(
+    model="qwen-max",
+    messages=[{"role": "user", "content": "Hello"}],
+    api_key="YOUR-DASHSCOPE-API-KEY",
+    stream=False,  # set True to get a generator of ChatCompletionChunk
+)
+print(response)
+```
+
+A complete runnable example is available in [`samples/set_region_example.py`](samples/set_region_example.py).
+
 ## AI Assistant: DashScope SDK Expert
 
 The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built on the bundled Agentic CLI (`dashscope/acli`) framework. For DashScope SDK/CLI users it is the recommended way to get development consultation and AI coding help — answering SDK/API questions, generating runnable examples, showing CLI usage, and diagnosing errors, right in your terminal.
 
 - Run `dashscope` with no arguments to start the assistant. On first run it offers to install the SDK Expert knowledge pack (per-domain quick-reference skills: text, multimodal, speech, retrieval, fine-tuning, agent, cli), so guidance comes from the SDK's public interfaces — parameters, outputs, error codes — without reading the source
 - Ask it instead of reading docs — e.g. `dashscope "how do I stream Generation output"` or `dashscope "CLI command to cancel a fine-tuning job"`. Type `/help` inside the assistant to list available commands (`/setup`, `/skill`, `/stats`, ...); classic SDK subcommands still work, and unrecognized commands are routed to the assistant
+- Full walkthrough: [DashScope SDK Expert guide](https://help.aliyun.com/en/model-studio/dashscope-sdk-expert)
 
 ## Supported Models
 

{dashscope-1.27.4 → dashscope-1.27.6}/README.md

@@ -52,7 +52,7 @@ else:
 
 ## API Key Authentication
 
-The SDK uses API key for authentication. Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key.
+The SDK uses API key for authentication. To obtain an API Key, see [How to get an API Key](https://help.aliyun.com/en/model-studio/get-api-key). Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key.
 
 ### Using the API Key
 
@@ -89,12 +89,94 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
 
 ```
 
+## Region and Endpoint Configuration
+
+By default the SDK sends requests to the China (Beijing) public endpoint `dashscope.aliyuncs.com`. If your Model Studio (Bailian) workspace lives in another region, switch the endpoint before making calls.
+
+### Using `set_region`
+
+`dashscope.set_region(region, workspace_id)` points the HTTP, WebSocket and OpenAI-compatible base URLs at the given region in a single call. `workspace_id` is required and is used as the endpoint subdomain.
+
+```python
+import dashscope
+
+# Switch to the Singapore region for workspace "ws-xxx123"
+dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
+
+# All subsequent calls use:
+#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
+print(dashscope.base_http_api_url)
+```
+
+Supported regions:
+
+| Region | Location |
+|--------|----------|
+| `cn-beijing` | China (Beijing) |
+| `cn-hongkong` | China (Hong Kong) |
+| `ap-southeast-1` | Singapore |
+| `ap-northeast-1` | Japan (Tokyo) |
+| `eu-central-1` | Germany (Frankfurt) |
+| `us-east-1` | US (Virginia) |
+
+> **API keys are region-specific.** Each region issues its own API keys (`sk-` prefix) in its Model Studio console, and keys cannot be mixed across regions — using a key from another region fails with `401`. Switch `api_key` together with the region.
+
+Region-specific notes:
+
+- WebSocket endpoints (`wss://.../api-ws/v1/inference`) are only served in `cn-beijing` and `ap-southeast-1`. `set_region` still sets `base_websocket_api_url` for every region, but WebSocket-based realtime APIs (realtime speech recognition/synthesis, multimodal dialog, etc.) are not available in the other regions.
+- `eu-central-1` / `ap-northeast-1`: the deployment scope (Global, or EU / Japan) is chosen when the workspace is created in the console, not per API call.
+- `us-east-1`: model names with the `-us` suffix (e.g. `qwen-plus-us`) restrict inference to the US; names without the suffix default to global inference.
+- Batch inference, model fine-tuning and application development are currently only available in `cn-beijing` and `ap-southeast-1`.
+
+> `set_region` updates process-wide globals, so it is not concurrency-safe when a single process talks to multiple regions at the same time. Call it once at startup, or re-call it before each switch.
+
+### Using environment variables
+
+You can also select the region without code:
+
+```shell
+export DASHSCOPE_API_REGION='ap-southeast-1'   # default: cn-beijing
+export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # used to resolve the endpoint subdomain
+```
+
+When a MaaS region is set via `DASHSCOPE_API_REGION`, the SDK builds the regional endpoints and substitutes `DASHSCOPE_WORKSPACE_ID` into them. You can also override each base URL directly:
+
+| Environment variable | Overrides |
+|----------------------|-----------|
+| `DASHSCOPE_HTTP_BASE_URL` | HTTP endpoint (`dashscope.base_http_api_url`) |
+| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket endpoint (`dashscope.base_websocket_api_url`) |
+| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible endpoint (`dashscope.base_compatible_api_url`) |
+
+`set_region` always builds workspace-exclusive endpoints. Some regions also offer shared domains without a workspace subdomain — `dashscope.aliyuncs.com` (Beijing), `dashscope-intl.aliyuncs.com` (Singapore) and `dashscope-us.aliyuncs.com` (US Virginia); use the override variables above to point at them.
+
+### OpenAI-compatible chat completions
+
+The SDK exposes an OpenAI-compatible chat completions entry that talks to `dashscope.base_compatible_api_url` (request path `chat/completions`) — no extra `openai` package required. It follows the region configured above.
+
+```python
+import dashscope
+from dashscope.aigc.chat_completion import Completions
+
+dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
+
+response = Completions.create(
+    model="qwen-max",
+    messages=[{"role": "user", "content": "Hello"}],
+    api_key="YOUR-DASHSCOPE-API-KEY",
+    stream=False,  # set True to get a generator of ChatCompletionChunk
+)
+print(response)
+```
+
+A complete runnable example is available in [`samples/set_region_example.py`](samples/set_region_example.py).
+
 ## AI Assistant: DashScope SDK Expert
 
 The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built on the bundled Agentic CLI (`dashscope/acli`) framework. For DashScope SDK/CLI users it is the recommended way to get development consultation and AI coding help — answering SDK/API questions, generating runnable examples, showing CLI usage, and diagnosing errors, right in your terminal.
 
 - Run `dashscope` with no arguments to start the assistant. On first run it offers to install the SDK Expert knowledge pack (per-domain quick-reference skills: text, multimodal, speech, retrieval, fine-tuning, agent, cli), so guidance comes from the SDK's public interfaces — parameters, outputs, error codes — without reading the source
 - Ask it instead of reading docs — e.g. `dashscope "how do I stream Generation output"` or `dashscope "CLI command to cancel a fine-tuning job"`. Type `/help` inside the assistant to list available commands (`/setup`, `/skill`, `/stats`, ...); classic SDK subcommands still work, and unrecognized commands are routed to the assistant
+- Full walkthrough: [DashScope SDK Expert guide](https://help.aliyun.com/en/model-studio/dashscope-sdk-expert)
 
 ## Supported Models
 

{dashscope-1.27.4 → dashscope-1.27.6}/dashscope/__init__.py

@@ -34,11 +34,13 @@ from dashscope.api_entities.aio_session import close_shared_aio_session
 from dashscope.api_entities.http_request import close_shared_sync_session
 from dashscope.common.api_key import save_api_key
 from dashscope.common.env import (
+    MAAS_REGIONS,
     api_key,
     api_key_file_path,
     base_compatible_api_url,
     base_http_api_url,
     base_websocket_api_url,
+    validate_workspace_id,
 )
 from dashscope.finetune.deployments import Deployments
 from dashscope.finetune.finetunes import FineTunes
@@ -81,6 +83,50 @@ from dashscope.tokenizers import (
     list_tokenizers,
 )
 
+
+# cn-beijing defaults to the legacy dashscope.aliyuncs.com endpoints;
+# its MaaS URLs are only reachable via an explicit set_region() call.
+_MAAS_REGIONS = {*MAAS_REGIONS, "cn-beijing"}
+
+
+def set_region(region: str, workspace_id: str = None):
+    """Switch to a specific MaaS region.
+
+    Updates base_http_api_url, base_compatible_api_url and
+    base_websocket_api_url to point to the MaaS endpoint for the
+    given region and workspace.
+
+    Args:
+        region (str): The MaaS region, e.g. "ap-southeast-1",
+            "us-east-1", "cn-hongkong", "cn-beijing", "eu-central-1",
+            "ap-northeast-1".
+        workspace_id (str): The workspace ID, used as the subdomain
+            of the MaaS endpoint.
+
+    Raises:
+        ValueError: If region is not supported, workspace_id is
+            empty, or workspace_id is not a valid hostname label.
+    """
+    if region not in _MAAS_REGIONS:
+        raise ValueError(
+            f"Unsupported region '{region}'. "
+            f"Supported regions: {sorted(_MAAS_REGIONS)}",
+        )
+
+    if not workspace_id:
+        raise ValueError("workspace_id is required")
+
+    validate_workspace_id(workspace_id)
+
+    global base_http_api_url, base_compatible_api_url
+    global base_websocket_api_url
+
+    host = f"{workspace_id}.{region}.maas.aliyuncs.com"
+    base_http_api_url = f"https://{host}/api/v1"
+    base_compatible_api_url = f"https://{host}/compatible-mode/v1"
+    base_websocket_api_url = f"wss://{host}/api-ws/v1/inference"
+
+
 __all__ = [
     "__version__",
     "base_compatible_api_url",
@@ -141,6 +187,7 @@ __all__ = [
     "MessageFile",
     "AssistantFile",
     "VideoSynthesis",
+    "set_region",
 ]
 
 logging.getLogger(__name__).addHandler(NullHandler())

{dashscope-1.27.4 → dashscope-1.27.6}/dashscope/__init__.pyi

@@ -23,6 +23,7 @@ base_websocket_api_url: str
 def save_api_key(api_key: str, 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: ...
 
 # ---------------------------------------------------------------------------
 # Response types

{dashscope-1.27.4 → dashscope-1.27.6}/dashscope/acli/__init__.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import uuid
 
-__version__ = "0.6.4"
+__version__ = "0.6.6"
 
 # Per-process identifier sent as x-dashscope-sdk-session-id so the
 # backend can group multi-turn requests from one CLI run.