dashscope 2.0.3__tar.gz → 2.0.4__tar.gz

{dashscope-2.0.3 → dashscope-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dashscope
-Version: 2.0.3
+Version: 2.0.4
 Summary: dashscope client sdk library
 Home-page: https://dashscope.aliyun.com/
 Author: Alibaba Cloud
@@ -518,6 +518,26 @@ The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built
 - Install with the `acli` extra: `pip install "dashscope[acli]"`. Add `acli-voice` / `acli-camera` for voice and camera input, or `acli-all` for everything — see the [extras table](#installation).
 - Full walkthrough: [DashScope SDK Expert guide](https://help.aliyun.com/en/model-studio/dashscope-sdk-expert).
 
+## Command line
+
+`pip install -U dashscope` puts two independent commands on your `PATH`. `dashscope` serves the SDK-shaped **2.0** command tree; `dashscope1` serves the frozen **1.x** implementation:
+
+| Entry point | Implementation | Examples |
+|-------------|----------------|----------|
+| `dashscope` | 2.0, following the SDK resource tree | `chat create`, `apps completions create`, `multimodal chat create`, `rl jobs create`, `rl functions register`, `images jobs create`, `audio asr transcribe`, `agentstudio sessions events send` |
+| `dashscope1` | 1.x, using the 1.x SDK | `generation call`, `application call`, `image-synthesis create`, `multimodal-conversation call`, `fine-tunes call`, `agentic-rl run`, `auth login`, `oss upload` |
+
+The two CLI trees do not dispatch to or normalize arguments for each other. Running a 1.x-only command through `dashscope` exits with a usage error and points to `dashscope1`. Their module entry points are likewise independent:
+
+```bash
+python -m dashscope.cli apps completions create ...
+python -m dashscope.legacy_1x.cli generation call ...
+```
+
+Running `dashscope` with no arguments starts the [AI assistant](#ai-assistant-dashscope-sdk-expert) instead of the CLI.
+
+For the complete 2.0 CLI command map, output formats, exit codes, configuration precedence and CI recipes, see the CLI section in [`examples/README.md`](examples/README.md).
+
 ## Shell completion
 
 Run the command for your shell once, then restart the shell (or re-source your config):
@@ -534,6 +554,8 @@ Preview the script without installing:
 dashscope --show-completion bash
 ```
 
+Completion is installed through the 2.0 `dashscope` entry point.
+
 ## Logging
 
 Set the level via settings or the environment:
@@ -556,10 +578,11 @@ examples/
 ├── 02_advanced_engineering/  Mock debugging, semantic cache, circuit breaker + multi-region DR
 ├── 03_agent_recipes/         Tool-call loop, RAG, MCP server, AgentStudio
 ├── 04_real_world_scenarios/  End-to-end production harnesses (RAG, realtime meetings, customer service)
+├── 05_cli/                   Offline CLI output/error and subprocess CI harnesses
 └── legacy_1x/                1.x module-level API examples, for reference
 ```
 
-See [`examples/README.md`](examples/README.md). Several flagship cases run fully offline (mock transports) with no API key.
+See [`examples/README.md`](examples/README.md) for the full guide, including the complete CLI command map and shell/CI recipes. Several flagship cases and both CLI harnesses run fully offline with no API key.
 
 ## Migrating from 1.x
 
@@ -577,6 +600,8 @@ 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")` |
 
+The CLI follows the same split — see [Command line](#command-line) above.
+
 ### Package layout and compatibility
 
 The 2.0 implementation sits directly under `dashscope`; the former `dashscope.v2` namespace is gone. AgentStudio and FineTune/Agentic RL each have a single business core under `dashscope.applications`, with two thin public facades on top:

{dashscope-2.0.3 → dashscope-2.0.4}/README.md

@@ -437,6 +437,26 @@ The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built
 - Install with the `acli` extra: `pip install "dashscope[acli]"`. Add `acli-voice` / `acli-camera` for voice and camera input, or `acli-all` for everything — see the [extras table](#installation).
 - Full walkthrough: [DashScope SDK Expert guide](https://help.aliyun.com/en/model-studio/dashscope-sdk-expert).
 
+## Command line
+
+`pip install -U dashscope` puts two independent commands on your `PATH`. `dashscope` serves the SDK-shaped **2.0** command tree; `dashscope1` serves the frozen **1.x** implementation:
+
+| Entry point | Implementation | Examples |
+|-------------|----------------|----------|
+| `dashscope` | 2.0, following the SDK resource tree | `chat create`, `apps completions create`, `multimodal chat create`, `rl jobs create`, `rl functions register`, `images jobs create`, `audio asr transcribe`, `agentstudio sessions events send` |
+| `dashscope1` | 1.x, using the 1.x SDK | `generation call`, `application call`, `image-synthesis create`, `multimodal-conversation call`, `fine-tunes call`, `agentic-rl run`, `auth login`, `oss upload` |
+
+The two CLI trees do not dispatch to or normalize arguments for each other. Running a 1.x-only command through `dashscope` exits with a usage error and points to `dashscope1`. Their module entry points are likewise independent:
+
+```bash
+python -m dashscope.cli apps completions create ...
+python -m dashscope.legacy_1x.cli generation call ...
+```
+
+Running `dashscope` with no arguments starts the [AI assistant](#ai-assistant-dashscope-sdk-expert) instead of the CLI.
+
+For the complete 2.0 CLI command map, output formats, exit codes, configuration precedence and CI recipes, see the CLI section in [`examples/README.md`](examples/README.md).
+
 ## Shell completion
 
 Run the command for your shell once, then restart the shell (or re-source your config):
@@ -453,6 +473,8 @@ Preview the script without installing:
 dashscope --show-completion bash
 ```
 
+Completion is installed through the 2.0 `dashscope` entry point.
+
 ## Logging
 
 Set the level via settings or the environment:
@@ -475,10 +497,11 @@ examples/
 ├── 02_advanced_engineering/  Mock debugging, semantic cache, circuit breaker + multi-region DR
 ├── 03_agent_recipes/         Tool-call loop, RAG, MCP server, AgentStudio
 ├── 04_real_world_scenarios/  End-to-end production harnesses (RAG, realtime meetings, customer service)
+├── 05_cli/                   Offline CLI output/error and subprocess CI harnesses
 └── legacy_1x/                1.x module-level API examples, for reference
 ```
 
-See [`examples/README.md`](examples/README.md). Several flagship cases run fully offline (mock transports) with no API key.
+See [`examples/README.md`](examples/README.md) for the full guide, including the complete CLI command map and shell/CI recipes. Several flagship cases and both CLI harnesses run fully offline with no API key.
 
 ## Migrating from 1.x
 
@@ -496,6 +519,8 @@ 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")` |
 
+The CLI follows the same split — see [Command line](#command-line) above.
+
 ### Package layout and compatibility
 
 The 2.0 implementation sits directly under `dashscope`; the former `dashscope.v2` namespace is gone. AgentStudio and FineTune/Agentic RL each have a single business core under `dashscope.applications`, with two thin public facades on top:

{dashscope-2.0.3 → dashscope-2.0.4}/dashscope/__init__.py

@@ -166,7 +166,6 @@ _LEGACY_LAZY_MODULES = frozenset(
         "applications",
         "assistants",
         "audio",
-        "cli",
         "common",
         "embeddings",
         "files",

{dashscope-2.0.3 → dashscope-2.0.4}/dashscope/_shared/_sdk_ident.py

@@ -26,7 +26,7 @@ it is the other half of the request identity, and it must agree with
 (``dashscope/<version>; python/...; platform/...; processor/...``) and is
 deliberately not shared with the 2.0 transport's own
 ``dashscope.transport.http.default_user_agent()``
-(``dashscope-v2-python/<version>``). Those are two distinct backend
+(``dashscope-sdk-python/<version>``). Those are two distinct backend
 contracts, not two spellings of one value, so they must not be merged.
 
 Only the stdlib is imported at module level; ``dashscope.version`` is

dashscope-2.0.4/dashscope/acli/expert.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""Shared DashScope SDK Expert adapter for both console entry points."""
+
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+import dashscope
+
+err_console = Console(stderr=True)
+
+_MD_MARKER = "<!-- managed-by: dashscope-expert -->"
+_PY_MARKER = "# managed-by: dashscope-expert"
+_EXPERT_EXAMPLE = "dashscope-sdk-expert"
+
+
+def _cleanup_legacy_expert_sync():
+    """Remove files the deleted expert bundling synced into ~/.acli.
+
+    Only files carrying the managed marker are deleted — without it the file
+    is user-owned and left untouched. Needed so stale global copies don't
+    shadow the workspace ./.acli/ configs installed via example download.
+    """
+    try:
+        from dashscope.acli.config import CONFIG_DIR
+    except ImportError:
+        return
+    md_targets = []
+    for subdir in ("skills", "references"):
+        target_dir = CONFIG_DIR / subdir
+        if target_dir.is_dir():
+            md_targets.extend(target_dir.glob("*.md"))
+    for path in md_targets:
+        try:
+            if _MD_MARKER in path.read_text(encoding="utf-8"):
+                path.unlink()
+        except OSError:
+            pass
+    build = CONFIG_DIR / "build_sdk_index.py"
+    try:
+        if build.is_file() and _PY_MARKER in build.read_text(encoding="utf-8"):
+            build.unlink()
+    except OSError:
+        pass
+
+
+def _maybe_offer_example_download():
+    """First interactive run without ./.acli: offer the SDK-expert example.
+
+    Accepting merges the example into ./.acli/ via the same code path as
+    `example download` (copied from the packaged install dir when present);
+    declining writes a marker into ./.acli/ so we never ask again here.
+    """
+    if not sys.stdin.isatty() or (Path.cwd() / ".acli").is_dir():
+        return
+    try:
+        from dashscope.acli.cli.examples import _handle_example_command
+        from dashscope.acli.cli.handlers_key import _GUIDE_DOC, _doc_locale
+    except ImportError:
+        return
+    err_console.print(
+        "[cyan]First run:[/cyan] download the dashscope-sdk-expert "
+        "example config into ./.acli/\n"
+        "(SDK Q&A expert persona + skill templates + SDK knowledge "
+        "index; pure config, editable anytime).",
+    )
+    err_console.print(
+        f"[dim]Guide: {_GUIDE_DOC.format(_doc_locale())}[/dim]",
+    )
+    try:
+        answer = input("Download the example config? [Y/n] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        err_console.print()
+        return
+    if answer in ("n", "no"):
+        try:
+            marker = Path.cwd() / ".acli" / ".dashscope-example-declined"
+            marker.parent.mkdir(parents=True, exist_ok=True)
+            marker.write_text("declined\n", encoding="utf-8")
+        except OSError:
+            pass
+        err_console.print(
+            "[dim]Skipped. To customize later, run: "
+            "python -m dashscope.acli example download "
+            "dashscope-sdk-expert[/dim]",
+        )
+        return
+    _handle_example_command(["download", _EXPERT_EXAMPLE])
+
+
+def _route_to_expert(command, tui=None):
+    """Run the vendored acli agent (bare ``dashscope`` or ``dashscope expert``).
+
+    ``command`` is a one-shot prompt, or None for the interactive REPL.
+    """
+    try:
+        from dashscope.acli.cli.handlers_key import _GUIDE_DOC, _doc_locale
+        from dashscope.acli.ui.embedded import run
+    except ImportError as exception:
+        err_console.print(
+            "[yellow]Tip:[/yellow] Install dashscope[acli] to enable "
+            "the agent "
+            f"({exception}).",
+        )
+        return
+
+    if command is None and not sys.stdin.isatty():
+        # The interactive REPL needs a real terminal; prompt_toolkit crashes
+        # on non-tty stdin (e.g. kqueue rejects /dev/null with EINVAL).
+        # Treat piped text as a one-shot prompt instead.
+        try:
+            piped = sys.stdin.read().strip()
+        except OSError:
+            piped = ""
+        if not piped:
+            err_console.print(
+                "[red]Error:[/red] Interactive mode requires a terminal. "
+                'Pass a prompt instead, e.g. dashscope expert "your question".',
+            )
+            sys.exit(2)
+        command = piped
+
+    _cleanup_legacy_expert_sync()
+    if command is None:
+        _maybe_offer_example_download()
+
+    try:
+        run(
+            app_name="DashScope SDK Expert",
+            prompt_symbol="dashscope> ",
+            api_key=dashscope.api_key or None,
+            command=command,
+            tui=tui,
+            module="expert",
+            guide_url=_GUIDE_DOC.format(_doc_locale()),
+        )
+    except SystemExit:
+        pass
+    except Exception as exception:  # pylint: disable=broad-except
+        err_console.print(
+            f"[yellow]Tip:[/yellow] Agent failed to start ({exception}).",
+        )

dashscope-2.0.4/dashscope/cli/__init__.py

@@ -0,0 +1,13 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""The dashscope CLI (v2).
+
+Deliberately empty. ``import dashscope.cli`` runs for shell completion and
+``--help``, so it must not pull in the router, Typer, or the SDK.
+
+There is no ``main`` re-export here on purpose: :mod:`dashscope.cli.main`
+is a submodule, and binding the same name on the package would make
+``from dashscope.cli import main`` resolve to a function or a module
+depending on import order. The console script names the module directly
+(``dashscope.cli.main:main``).
+"""

dashscope-2.0.4/dashscope/cli/__main__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""``python -m dashscope.cli``."""
+
+from dashscope.cli.main import main
+
+if __name__ == "__main__":
+    main()

dashscope-2.0.4/dashscope/cli/app.py

@@ -0,0 +1,213 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""The root Typer app: global options, ``version``, and the command groups.
+
+Global options follow click's convention and precede the subcommand::
+
+    dashscope -k sk-xxx --output json chat create -m qwen-plus --prompt hi
+
+The 1.x command tree is installed separately as ``dashscope1`` and is never
+imported or executed by this app.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+
+from dashscope.cli.context import CliContext, GlobalOptions
+from dashscope.cli.errors import ErrorHandlingGroup, usage_error
+from dashscope.cli.output import OUTPUT_FORMATS
+
+# `\[` is Rich markup escaping: unescaped, Rich reads the bracketed run as a
+# style tag and drops it from the rendered help. The string is raw so the
+# backslash survives to Rich -- which also means it cannot open with `"""\`,
+# since a raw string keeps that backslash too.
+_HELP = r"""Manage DashScope resources from the command line.
+
+Global options come before the command: `dashscope -k sk-xxx --output json
+ft list`. Errors go to stderr as `Error \[category]: message` and the exit
+code says which kind: 0 ok, 1 server/rate-limit/network, 2 bad command
+line, 3 auth, 4 not found.
+"""
+
+
+def _epilog() -> str:
+    return (
+        "CLI 1.x commands such as `generation create` and `application create` "
+        "have moved to `dashscope1`. A bare `dashscope` opens the bundled "
+        "`expert` agent interactively."
+    )
+
+
+def build_app() -> typer.Typer:
+    """Assemble the v2 CLI. Called once per process by ``main()``."""
+    app = typer.Typer(
+        name="dashscope",
+        cls=ErrorHandlingGroup,
+        help=_HELP,
+        epilog=_epilog(),
+        add_completion=True,
+        no_args_is_help=True,
+        rich_markup_mode="rich",
+        context_settings={"help_option_names": ["-h", "--help"]},
+    )
+
+    @app.callback()
+    def root(  # pylint: disable=too-many-arguments,too-many-locals
+        ctx: typer.Context,
+        api_key: Optional[str] = typer.Option(
+            None,
+            "-k",
+            "--api-key",
+            help="DashScope API key. Overrides the environment and config file.",
+        ),
+        protocol: Optional[str] = typer.Option(
+            None,
+            "--protocol",
+            help="Wire protocol: native, openai or anthropic.",
+        ),
+        base_url: Optional[str] = typer.Option(
+            None,
+            "--base-url",
+            help="Override the service base URL.",
+        ),
+        workspace: Optional[str] = typer.Option(
+            None,
+            "--workspace",
+            help="DashScope workspace (business space) id.",
+        ),
+        region: Optional[str] = typer.Option(
+            None,
+            "--region",
+            help="Service region, e.g. cn-beijing or ap-southeast-1.",
+        ),
+        timeout: Optional[float] = typer.Option(
+            None,
+            "--timeout",
+            help="Per-request timeout in seconds.",
+        ),
+        output: Optional[str] = typer.Option(
+            None,
+            "-o",
+            "--output",
+            help="Output format. Machine formats keep stdout parseable.",
+        ),
+        config_override: Optional[List[str]] = typer.Option(
+            None,
+            "-c",
+            metavar="KEY=VALUE",
+            help=(
+                "Override one config key for this invocation; repeatable. "
+                "SDK keys (api_key, protocol, timeout, ...) are passed to "
+                "the client, CLI keys (output, default_model) set defaults."
+            ),
+        ),
+        no_color: bool = typer.Option(
+            False,
+            "--no-color",
+            help="Disable colored output. Also honours $NO_COLOR.",
+        ),
+        verbose: bool = typer.Option(
+            False,
+            "-v",
+            "--verbose",
+            help="Show request metadata and tracebacks on failure.",
+        ),
+    ) -> None:
+        """Configure global options."""
+        if output is not None and output not in OUTPUT_FORMATS:
+            raise usage_error(
+                f"invalid --output {output!r}, expected one of "
+                f"{', '.join(OUTPUT_FORMATS)}",
+            )
+        ctx.obj = CliContext(
+            GlobalOptions(
+                api_key=api_key,
+                protocol=protocol,
+                base_url=base_url,
+                workspace=workspace,
+                region=region,
+                timeout=timeout,
+                output=output,
+                overrides=tuple(config_override or ()),
+                no_color=no_color,
+                verbose=verbose,
+            ),
+        )
+        # Resolve the -c overrides now rather than on first SDK use, so a
+        # misspelled key fails on every command -- including ones like
+        # `version` that never touch the service. This reads no files and
+        # builds no client.
+        ctx.obj.sdk_overrides()
+
+    @app.command()
+    def version(ctx: typer.Context) -> None:
+        """Print the installed dashscope version."""
+        # Imported here rather than at module scope: this command is the
+        # cheapest thing the CLI does and should stay that way.
+        from dashscope.version import (
+            __version__,
+        )  # pylint: disable=import-outside-toplevel
+
+        renderer = ctx.obj.renderer
+        if renderer.table_mode:
+            renderer.echo(__version__)
+        else:
+            renderer.print_object({"version": __version__})
+
+    # Command modules are thin by contract (no SDK import at module
+    # scope), so mounting them all here costs nothing; the expensive part
+    # is the client, which stays lazy behind ``ctx.obj.client``.
+    from dashscope.cli.commands import (
+        agentstudio as agentstudio_command,
+        apps as apps_command,
+        audio as audio_command,
+        auth as auth_command,
+        chat as chat_command,
+        config as config_command,
+        decision as decision_command,
+        deployments as deployments_command,
+        embeddings as embeddings_command,
+        files as files_command,
+        ft as ft_command,
+        images as images_command,
+        models as models_command,
+        multimodal as multimodal_command,
+        oss as oss_command,
+        rerank as rerank_command,
+        rl as rl_command,
+        tingwu as tingwu_command,
+        tokenization as tokenization_command,
+        videos as videos_command,
+    )
+
+    app.add_typer(auth_command.build_app(), name="auth")
+    app.add_typer(chat_command.build_app(), name="chat")
+    app.add_typer(ft_command.build_app(), name="ft")
+    # Hidden alias, following the 1.x tree's convention: the long name stays
+    # usable but out of the way. Built twice so the two registrations do not
+    # share one Typer instance.
+    app.add_typer(ft_command.build_app(), name="fine-tunes", hidden=True)
+    app.add_typer(files_command.build_app(), name="files")
+    app.add_typer(models_command.build_app(), name="models")
+    app.add_typer(oss_command.build_app(), name="oss")
+    app.add_typer(images_command.build_app(), name="images")
+    app.add_typer(videos_command.build_app(), name="videos")
+    app.add_typer(embeddings_command.build_app(), name="embeddings")
+    app.add_typer(multimodal_command.build_app(), name="multimodal")
+    app.add_typer(rerank_command.build_app(), name="rerank")
+    app.add_typer(tokenization_command.build_app(), name="tokenization")
+    app.add_typer(apps_command.build_app(), name="apps")
+    app.add_typer(deployments_command.build_app(), name="deployments")
+    app.add_typer(rl_command.build_app(), name="rl")
+    # Hidden alias of ``rl``, mirroring the ``fine-tunes`` alias of ``ft``.
+    app.add_typer(rl_command.build_app(), name="agentic-rl", hidden=True)
+    app.add_typer(audio_command.build_app(), name="audio")
+    app.add_typer(tingwu_command.build_app(), name="tingwu")
+    app.add_typer(decision_command.build_app(), name="decision")
+    app.add_typer(agentstudio_command.build_app(), name="agentstudio")
+    app.add_typer(config_command.build_app(), name="config")
+
+    return app

dashscope-2.0.4/dashscope/cli/commands/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""Command groups for the dashscope CLI.
+
+Every module here follows the same shape, which is the pattern the rest
+of the command tree is meant to copy: declare options with typer, take
+``ctx: typer.Context`` as the first parameter, make exactly one SDK call
+through ``ctx.obj.client``, and hand the result to ``ctx.obj.renderer``.
+
+The rule that keeps ``--help`` fast is structural: **no module in this
+package may import ``dashscope`` at module scope.** Importing the SDK
+pulls in pydantic, httpx and the 1.x resource tree; a user reading
+``dashscope chat create --help`` should not wait for any of it. Reach the
+SDK only through ``ctx.obj.client``, which is built on first use.
+"""