# The 3Di command line client
The 3Di command line client allows for
- Defining and running 3Di scenarios from the command line.
- Assembling different scenarios as a "suite" that will be run in batch.
- Management commands, for instance to list currently running simulations.
## Entry points
There are different entry points for the 3Di command line client. The main one being
```shell script
$ 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
```
The output above shows the three sub-commands `api`, `live` and `scenarios`. Those are all commands from
the main client. Whenever you install plugins this list can be appended. You can even append this list yourself
by writing your own plugin! How to go about doing that, explains the plugins section.
You can invoke the sub-commands also directly, e.g.
```shell script
$ 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
```
## Dependencies
`python >= 3.8`
## Installation
```
pip install --user threedi-cmd
```
## Plugins
The 3Di command client has it's own plugin ecosystem. The commands described above are the client core that can
be extended by installing 3Di command client packages into the same environment.
An example: You have a virtual environment `/home/you/.virtualenvs/3di/bin/python` and you install the 3Di command client
using pip
```shell script
pip install threedi-cmd
```
If you want to add the statistics commands, you'll install the threedi-cmd-statistics package
```shell script
pip install threedi-cmd-statistics
```
Now run `3Di_cmd api` again. Notice the `statistics` and `customers` commands that has been added to the commands
overview; they have added through the plugin you just installed.
```shell script
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
```
### Available plugins
- https://github.com/nens/threedi-cmd-statistics/
### Writing your own plugin
The first thing to know is that the plugin discovering mechanism is [based on a naming convention](https://packaging.python.org/guides/creating-and-discovering-plugins/).
All plugin packages must start with **threedi_cmd_**, otherwise the main programme will not be able to discover the
package and add the commands to the client.
The commands of the plugin package itself must be [typer](https://typer.tiangolo.com/) apps.
The threedi-cmd packages ships with two objects that are used to define and register the plugin apps.
```python
@dataclass
class AppMeta:
app: typer.Typer
name: str
help: str
add_to: Optional[str] = ""
@dataclass
class AppRegistry:
apps: Dict[str, AppMeta]
```
So let's say you have an plugin package that is called `threedi-cmd-queue` that implements a single app called `queue_app`.
You would need to the following for the threedi-cmd client to pick the command up.
#### AppMeta
```python
"""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}
)
```
Lastly, make sure the registry is available through your **top level** `__init__.py`. Following our example the
method would reside in `threedi-cmd-queue/threedi_cmd_queue/__init__.py`
```python
"""Top-level package for threedi_cmd_queue."""
from threedi_cmd_queue.app_definitions import registry
````
That's it. Publish your package to [pypi](https://pypi.org/) so that is pip installable.
# History
0.0.23 (2024-04-12)
-------------------
- Add threedi-schema dependency to setup.py
0.0.22 (2024-04-12)
-------------------
- Added threedi-schema as a dependency.
0.0.21 (2024-04-11)
-------------------
- Added support for automatic schematisation upload.
- Refactored websocket settings.
- Support Lizard results postprocessing
0.0.20 (2022-10-10)
-------------------
- Use threedimodel_id instead of threedimodel on Simulation resource.
0.0.19 (2022-10-10)
-------------------
- Pop threedimodel from simulation template create request.
0.0.18 (2022-10-10)
-------------------
- Upgraded scenario runner to use simulation templates.
0.0.17 (2022-08-10)
-------------------
- Made bumping arrow (dependency) possible.
- Increase timeout for leakge/rain/sources_sinks file upload 'processed' event.
0.0.16 (2022-02-08)
-------------------
- Replaced PyPi token
0.0.15 (2022-02-08)
-------------------
- Bugfix: Don't set `None`` values on threedi-api-client OpenAPI models.
0.0.14 (2021-08-11)
-------------------
- Bugfix in groundwater initial waterlevel scenario handling.
- File structure control scenario support
0.0.13 (2021-08-03)
-------------------
- Upgraded from `openapi_client` to `threed_api_client`
0.0.12 (2021-08-02)
-------------------
- Added support for schematisations scenarios
0.0.11 (2021-06-15)
-------------------
- Changed import paths
0.0.10 (2021-06-15)
-------------------
- Removed unused imports
0.0.9 (2021-05-05)
------------------
- Renamed general settings to physical settings
0.0.8 (2021-04-28)
------------------
- Use auth refresh method from upstream package.
0.0.7 (2021-04-14)
------------------
- Added settings to scenario-test-framework
0.0.6 (2021-03-24)
------------------
- Added leakage and bumped threedi-openapi-client
0.0.5 (2021-02-05)
------------------
- Specify arrow version, as newer versions don't work well with 'days' directive in
YAML (arrow is used in jinja2-time).
- Caches the config per endpoint. This includes a scenario folder option to supply
a custom scenario folder location (per endpoint).
0.0.4 (2021-02-04)
------------------
- Fixed saving 'organisation_uuid' and 'result_folder' with the `api settings`
command.
- First official release candidate as a typer app that introduces a plugin system.
0.0.3 (2020-12-21)
- Fixed settings context if config file is not yet available.
## 0.0.1b (2020-12-18)
- First (beta) pypi release.
Raw data
{
"_id": null,
"home_page": "https://github.com/nens/threedi-cmd",
"name": "threedi-cmd",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "3Di, client, command line, scenario",
"author": "Jelle Prins",
"author_email": "info@nelen-schuurmans.nl",
"download_url": "https://files.pythonhosted.org/packages/81/b1/211467553c026595e6229d62e5d40950fcbb030a3ea83c5f62b519430f28/threedi_cmd-0.0.23.tar.gz",
"platform": null,
"description": "# The 3Di command line client\n\nThe 3Di command line client allows for \n\n - Defining and running 3Di scenarios from the command line. \n - Assembling different scenarios as a \"suite\" that will be run in batch. \n - Management commands, for instance to list currently running simulations. \n\n## Entry points\n\nThere are different entry points for the 3Di command line client. The main one being\n\n```shell script\n$ 3Di_cmd --help\n\nUsage: 3Di_cmd [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --install-completion [bash|zsh|fish|powershell|pwsh]\n Install completion for the specified shell.\n --show-completion [bash|zsh|fish|powershell|pwsh]\n Show completion for the specified shell, to\n copy it or customize the installation.\n\n --help Show this message and exit.\n\nCommands:\n api Interact with with the 3Di API\n live Get real time updates of running simulations\n scenarios Manage your local scenarios\n\n```\nThe output above shows the three sub-commands `api`, `live` and `scenarios`. Those are all commands from \nthe main client. Whenever you install plugins this list can be appended. You can even append this list yourself \nby writing your own plugin! How to go about doing that, explains the plugins section. \n\n\nYou can invoke the sub-commands also directly, e.g. \n\n```shell script\n$ api --help\nUsage: api [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --endpoint [localhost|staging|production]\n [default: production]\n --install-completion [bash|zsh|fish|powershell|pwsh]\n Install completion for the specified shell.\n --show-completion [bash|zsh|fish|powershell|pwsh]\n Show completion for the specified shell, to\n copy it or customize the installation.\n\n --help Show this message and exit.\n\nCommands:\n models List available threedimodels\n organisations List available organisations\n results Download results of a simulation\n run-scenario Run a scenario\n settings Set default settings\n simulations List simulations\n ```\n\n\n## Dependencies\n\n`python >= 3.8`\n\n\n## Installation\n\n\n```\npip install --user threedi-cmd\n```\n\n## Plugins\n\nThe 3Di command client has it's own plugin ecosystem. The commands described above are the client core that can \nbe extended by installing 3Di command client packages into the same environment. \n\nAn example: You have a virtual environment `/home/you/.virtualenvs/3di/bin/python` and you install the 3Di command client\nusing pip\n\n```shell script\npip install threedi-cmd\n``` \n\n\nIf you want to add the statistics commands, you'll install the threedi-cmd-statistics package \n\n```shell script\npip install threedi-cmd-statistics\n``` \n\nNow run `3Di_cmd api` again. Notice the `statistics` and `customers` commands that has been added to the commands \noverview; they have added through the plugin you just installed.\n\n```shell script\nUsage: 3Di_cmd api [OPTIONS] COMMAND [ARGS]...\n\n Interact with with the 3Di API\n\nOptions:\n --endpoint [localhost|staging|production]\n [default: production]\n --help Show this message and exit.\n\nCommands:\n customers List 3Di customers\n models List available threedimodels\n organisations List available organisations\n results Download results of a simulation\n run-scenario Run a scenario\n settings Set default settings\n simulations List simulations\n statistics 3Di API statistics, like session counts etc\n```\n\n\n### Available plugins\n\n - https://github.com/nens/threedi-cmd-statistics/\n\n\n### Writing your own plugin \n\nThe first thing to know is that the plugin discovering mechanism is [based on a naming convention](https://packaging.python.org/guides/creating-and-discovering-plugins/).\nAll plugin packages must start with **threedi_cmd_**, otherwise the main programme will not be able to discover the \npackage and add the commands to the client.\n\n\nThe commands of the plugin package itself must be [typer](https://typer.tiangolo.com/) apps. \n\nThe threedi-cmd packages ships with two objects that are used to define and register the plugin apps. \n\n```python\n@dataclass\nclass AppMeta:\n app: typer.Typer\n name: str\n help: str\n add_to: Optional[str] = \"\"\n\n\n@dataclass\nclass AppRegistry:\n apps: Dict[str, AppMeta]\n ```\n\nSo let's say you have an plugin package that is called `threedi-cmd-queue` that implements a single app called `queue_app`. \nYou would need to the following for the threedi-cmd client to pick the command up.\n\n#### AppMeta\n\n```python\n\"\"\"threedi_cmd_queue/app_definitions.py\"\"\"\n\n# these classes are shiped with the threedi-cmd package\nfrom threedi_cmd.plugins.models import AppMeta, AppRegistry\n# import your won app\nfrom threedi_cmd_queue.commands.apps import queue_app\n\n\nqueues_meta = AppMeta(\n app=queue_app,\n name=\"queues\",\n help=\"3Di API queues\",\n add_to=\"api\"\n)\n\n# fill the registry; we use the name \"queues\" for the registry as well \nregistry = AppRegistry(\n apps={queues_meta.name : queues_meta}\n)\n\n```\n\nLastly, make sure the registry is available through your **top level** `__init__.py`. Following our example the \nmethod would reside in `threedi-cmd-queue/threedi_cmd_queue/__init__.py`\n\n```python\n\"\"\"Top-level package for threedi_cmd_queue.\"\"\"\n\nfrom threedi_cmd_queue.app_definitions import registry\n\n````\n\n\nThat's it. Publish your package to [pypi](https://pypi.org/) so that is pip installable. \n\n\n# History\n\n0.0.23 (2024-04-12)\n-------------------\n\n- Add threedi-schema dependency to setup.py\n\n\n0.0.22 (2024-04-12)\n-------------------\n\n- Added threedi-schema as a dependency.\n\n\n0.0.21 (2024-04-11)\n-------------------\n\n- Added support for automatic schematisation upload.\n\n- Refactored websocket settings.\n\n- Support Lizard results postprocessing\n\n\n0.0.20 (2022-10-10)\n-------------------\n\n- Use threedimodel_id instead of threedimodel on Simulation resource.\n\n\n0.0.19 (2022-10-10)\n-------------------\n\n- Pop threedimodel from simulation template create request.\n\n\n0.0.18 (2022-10-10)\n-------------------\n\n- Upgraded scenario runner to use simulation templates.\n\n\n0.0.17 (2022-08-10)\n-------------------\n\n- Made bumping arrow (dependency) possible.\n\n- Increase timeout for leakge/rain/sources_sinks file upload 'processed' event.\n\n\n0.0.16 (2022-02-08)\n-------------------\n\n- Replaced PyPi token\n\n\n0.0.15 (2022-02-08)\n-------------------\n\n- Bugfix: Don't set `None`` values on threedi-api-client OpenAPI models.\n\n\n0.0.14 (2021-08-11)\n-------------------\n\n- Bugfix in groundwater initial waterlevel scenario handling.\n\n- File structure control scenario support\n\n\n0.0.13 (2021-08-03)\n-------------------\n\n- Upgraded from `openapi_client` to `threed_api_client`\n\n\n0.0.12 (2021-08-02)\n-------------------\n\n- Added support for schematisations scenarios\n\n\n0.0.11 (2021-06-15)\n-------------------\n\n- Changed import paths\n\n\n0.0.10 (2021-06-15)\n-------------------\n\n- Removed unused imports\n\n\n0.0.9 (2021-05-05)\n------------------\n\n- Renamed general settings to physical settings\n\n\n0.0.8 (2021-04-28)\n------------------\n\n- Use auth refresh method from upstream package.\n\n\n0.0.7 (2021-04-14)\n------------------\n\n- Added settings to scenario-test-framework\n\n\n0.0.6 (2021-03-24)\n------------------\n\n- Added leakage and bumped threedi-openapi-client\n\n\n0.0.5 (2021-02-05)\n------------------\n\n- Specify arrow version, as newer versions don't work well with 'days' directive in\n YAML (arrow is used in jinja2-time).\n\n- Caches the config per endpoint. This includes a scenario folder option to supply\n a custom scenario folder location (per endpoint).\n\n\n0.0.4 (2021-02-04)\n------------------\n\n- Fixed saving 'organisation_uuid' and 'result_folder' with the `api settings`\n command.\n\n- First official release candidate as a typer app that introduces a plugin system.\n\n\n\n0.0.3 (2020-12-21)\n\n- Fixed settings context if config file is not yet available.\n\n\n## 0.0.1b (2020-12-18)\n\n- First (beta) pypi release.\n\n\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Python 3Di command line client",
"version": "0.0.23",
"project_urls": {
"Homepage": "https://github.com/nens/threedi-cmd"
},
"split_keywords": [
"3di",
" client",
" command line",
" scenario"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e60f59c1b016ad3710ca4c255786a5ef8c2059384b4180f05dbb9a369847867",
"md5": "7773dc916aa8f851e31de62a1b197363",
"sha256": "dbc9c94114266d41c46901b8e3b5c9f9fb0a0430ec9fb1f6b13efd1b9c699a75"
},
"downloads": -1,
"filename": "threedi_cmd-0.0.23-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7773dc916aa8f851e31de62a1b197363",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 55800,
"upload_time": "2024-04-12T13:25:21",
"upload_time_iso_8601": "2024-04-12T13:25:21.494247Z",
"url": "https://files.pythonhosted.org/packages/0e/60/f59c1b016ad3710ca4c255786a5ef8c2059384b4180f05dbb9a369847867/threedi_cmd-0.0.23-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "81b1211467553c026595e6229d62e5d40950fcbb030a3ea83c5f62b519430f28",
"md5": "e8f4cdb00e48b040214b6022e3d99581",
"sha256": "e5ad78a57d123b9926f032a23624ac2dee2ab0f3af913223f8bc2d0e3151e68c"
},
"downloads": -1,
"filename": "threedi_cmd-0.0.23.tar.gz",
"has_sig": false,
"md5_digest": "e8f4cdb00e48b040214b6022e3d99581",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 45827,
"upload_time": "2024-04-12T13:25:22",
"upload_time_iso_8601": "2024-04-12T13:25:22.746621Z",
"url": "https://files.pythonhosted.org/packages/81/b1/211467553c026595e6229d62e5d40950fcbb030a3ea83c5f62b519430f28/threedi_cmd-0.0.23.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 13:25:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nens",
"github_project": "threedi-cmd",
"github_not_found": true,
"lcname": "threedi-cmd"
}
JSON
