3Di命令行客户端

3Di命令行客户端允许

• 从命令行定义和运行3Di场景。
• 将不同的场景组合成一个“套件”，将批量运行。
• 管理命令，例如列出当前运行的模拟。

入口点

3Di命令行客户端有不同的入口点。主要的一个是

$ 3Di_cmd --help

Usage: 3Di_cmd [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.

  --help                          Show this message and exit.

Commands:
  api        Interact with with the 3Di API
  live       Get real time updates of running simulations
  scenarios  Manage your local scenarios

上面的输出显示了三个子命令 api、live 和 scenarios。这些都是主要客户端的命令。每次您安装插件，此列表都可以添加。您甚至可以自己编写插件来添加此列表！如何做到这一点，请参阅插件部分。

您也可以直接调用子命令，例如。

$ api --help
Usage: api [OPTIONS] COMMAND [ARGS]...

Options:
  --endpoint [localhost|staging|production]
                                  [default: production]
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.

  --help                          Show this message and exit.

Commands:
  models         List available threedimodels
  organisations  List available organisations
  results        Download results of a simulation
  run-scenario   Run a scenario
  settings       Set default settings
  simulations    List simulations

依赖关系

python >= 3.10

安装

pip install --user threedi-cmd

插件

3Di命令客户端拥有自己的插件生态系统。上述描述的命令是客户端的核心，可以通过安装3Di命令客户端包到相同环境中进行扩展。

示例：您有一个虚拟环境 /home/you/.virtualenvs/3di/bin/python，您可以使用pip安装3Di命令客户端。

pip install threedi-cmd

如果您想添加统计命令，则需要安装threedi-cmd-statistics包。

pip install threedi-cmd-statistics

现在再次运行3Di_cmd api。注意添加到命令概览中的statistics和customers命令；它们是通过您刚刚安装的插件添加的。

Usage: 3Di_cmd api [OPTIONS] COMMAND [ARGS]...

  Interact with with the 3Di API

Options:
  --endpoint [localhost|staging|production]
                                  [default: production]
  --help                          Show this message and exit.

Commands:
  customers      List 3Di customers
  models         List available threedimodels
  organisations  List available organisations
  results        Download results of a simulation
  run-scenario   Run a scenario
  settings       Set default settings
  simulations    List simulations
  statistics     3Di API statistics, like session counts etc

可用插件

• https://github.com/nens/threedi-cmd-statistics/

编写您自己的插件

首先要知道，插件发现机制是基于命名约定的。所有插件包都必须以threedi_cmd_开头，否则主程序将无法发现包并添加命令到客户端。

插件包本身的命令必须是typer应用程序。

threedi-cmd包提供了两个对象，用于定义和注册插件应用程序。

@dataclass
class AppMeta:
    app: typer.Typer
    name: str
    help: str
    add_to: Optional[str] = ""


@dataclass
class AppRegistry:
    apps: Dict[str, AppMeta]

假设您有一个名为threedi-cmd-queue的插件包，该包实现了一个名为queue_app的单个应用程序。您需要以下内容，以便threedi-cmd客户端能够拾取命令。

AppMeta

"""threedi_cmd_queue/app_definitions.py"""

# these classes are shiped with the threedi-cmd package
from threedi_cmd.plugins.models import AppMeta, AppRegistry
# import your won app
from threedi_cmd_queue.commands.apps import queue_app


queues_meta = AppMeta(
    app=queue_app,
    name="queues",
    help="3Di API queues",
    add_to="api"
)

# fill the registry; we use the name "queues" for the registry as well 
registry = AppRegistry(
    apps={queues_meta.name : queues_meta}
)

最后，确保注册表通过您的顶级 __init__.py可用。以我们的示例为例，该方法位于threedi-cmd-queue/threedi_cmd_queue/__init__.py。

"""Top-level package for threedi_cmd_queue."""

from threedi_cmd_queue.app_definitions import registry

就是这样。将您的包发布到pypi，以便可以使用pip安装。

历史

0.0.27 (2024-09-05)

• 等待模拟模板任务完成

0.0.26 (2024-08-16)

• 锁定threedi-schema在0.217和0.221之间

0.0.25 (2024-08-15)

• 更新github action python版本到3.10

0.0.24 (2024-08-15)

• 将constanntlateral、filelateral、localrainconstant、localraintimeseries和raintimeserieslizard添加到yaml转换器中。

0.0.23 (2024-04-12)

• 将threedi-schema依赖项添加到setup.py中

0.0.22 (2024-04-12)

• 添加了threedi-schema作为依赖项。

0.0.21 (2024-04-11)

• 添加了对自动概化上传的支持。

• 重构websocket设置。

• 支持Lizard结果后处理

0.0.20 (2022-10-10)

• 在Simulation资源上使用threedimodel_id而不是threedimodel。

0.0.19 (2022-10-10)

• 从模拟模板创建请求中弹出threedimodel。

0.0.18 (2022-10-10)

• 升级场景运行器以使用模拟模板。

0.0.17 (2022-08-10)

• 使弹跳箭头（依赖项）成为可能。

• 增加泄漏/雨/源/汇文件上传'processed'事件的超时时间。

0.0.16 (2022-02-08)

• 替换PyPi令牌

0.0.15 (2022-02-08)

• 错误修正：不要在threedi-api-client OpenAPI模型上设置`None`值。

0.0.14 (2021-08-11)

• 错误修正：地下水初始水位场景处理中的错误。

• 文件结构控制场景支持

0.0.13 (2021-08-03)

• 从openapi_client升级到threed_api_client

0.0.12 (2021-08-02)

• 添加了对概化场景的支持

0.0.11 (2021-06-15)

• 更改导入路径

0.0.10 (2021-06-15)

• 删除未使用的导入

0.0.9 (2021-05-05)

• 将通用设置重命名为物理设置

0.0.8 (2021-04-28)

• 使用上游包中的auth刷新方法。

0.0.7 (2021-04-14)

• 添加设置到场景测试框架

0.0.6 (2021-03-24)

• 添加泄漏并升级threedi-openapi-client

0.0.5 (2021-02-05)

• 指定箭头版本，因为较新版本与YAML中的'days'指令（arrow用于jinja2-time）不兼容。

• 按端点缓存配置。这包括一个场景文件夹选项，用于提供自定义场景文件夹位置（按端点）。

0.0.4 (2021-02-04)

• 使用api settings命令修复保存'organisation_uuid'和'result_folder'。

• 作为引入插件系统的typer应用程序的第一个官方候选版本。

0.0.3 (2020-12-21)

• 如果配置文件尚未可用，则修复设置上下文。

0.0.1b (2020-12-18)

• 第一个（beta）pypi版本。