Metadata-Version: 2.4
Name: tango-takeoff
Version: 3.0.0
Summary: A script that starts and stops Tango Device Server(s)
Author-email: MAX IV KITS Software <kits-sw@maxiv.lu.se>
License-Expression: GPL-3.0-or-later
Project-URL: Repository, https://gitlab.com/maxiv/tools/tango-takeoff
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytango
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Dynamic: license-file

# tango-takeoff

A tool that can find, start and stop Tango Device Servers. It's like Astor for the command line.

In general, the tool is explaining itself. Run it and look at the output.

## Installation

`tango-takeoff` is on [PyPI](https://pypi.org/project/tango-takeoff/) and [conda-forge](https://github.com/conda-forge/tango-takeoff-feedstock).
Install it with your preferred package manager: `pip`, `uv`, `conda` or `pixi`.

As it's intended to be used as a script, we recommend installing it globally.
With `uv`, do:

    uv tool install tango-takeoff

And with `pixi`:

    pixi global install tango-takeoff


## Usage

The tool depends on the `TANGO_HOST` environment variable.

**Help**

    > takeoff --help
    usage: takeoff [-h] {find,up,down,restart} ...

    Start (up), stop (down) or restart (restart) Tango Device Servers

    positional arguments:
      {find,up,start,down,stop,restart}
        find                Finds servers based on terms and shows the 'dry run' version of what will be used in 'up' and 'down'
        up (start)          Bring servers up based on terms
        down (stop)         Bring servers down based on terms
        restart             Restart servers based on terms

    options:
      -h, --help      show this help message and exit

**Find**

    > takeoff find --help
    usage: takeoff find [-h] [--json] [--default-host DEFAULT_HOST] [-v] servers [servers ...]

    positional arguments:
      servers               A name or search term of a server, use * for wildcard in the end of the name. Use the format [host,]<server-name>

      options:
        -h, --help            show this help message and exit
        --json                Output structured as JSON (default: False)
        --default-host DEFAULT_HOST
                              Default host for Tango device servers (default: None)
        -v, --verbose         Set the trace level. Can be used in count way: -vv or --verbose --verbose (default: None)

**Up / Start**

    > takeoff up --help
    usage: takeoff up [-h] [--json] [--default-host DEFAULT_HOST] [-v] [-t RUNNING_TIMEOUT] [-s STARTER_TIMEOUT] [-d] servers [servers ...]

    positional arguments:
      servers               A name or search term of a server, use * for wildcard in the end of the name. Use the format [host,]<server-name>[,<level>]

    options:
      -h, --help            show this help message and exit
      --json                Output structured as JSON (default: False)
      --default-host DEFAULT_HOST
                            Default host for Tango device servers (default: None)
      -v, --verbose         Set the trace level. Can be used in count way: -vv or --verbose --verbose (default: None)
      -t RUNNING_TIMEOUT, --timeout RUNNING_TIMEOUT
                            Time to wait for a server to be running (in seconds) (default: 60)
      -s STARTER_TIMEOUT, --starter-timeout STARTER_TIMEOUT
                            Time to wait for starter if it's not running (in seconds) (default: 10)
      -d, --dry-run         outputs the servers with the details that will take effect by the command (default: False)

**Down / Stop**

    > takeoff down --help
    usage: takeoff down [-h] [--json] [--default-host DEFAULT_HOST] [-v] [-f] [-k KILL_TIMEOUT] [-s STARTER_TIMEOUT] [-d] servers [servers ...]

    positional arguments:
      servers               A name or search term of a server, use * for wildcard in the end of the name. Use the format [host,]<server-name>

    options:
      -h, --help            show this help message and exit
      --json                Output structured as JSON (default: False)
      --default-host DEFAULT_HOST
                            Default host for Tango device servers (default: None)
      -v, --verbose         Set the trace level. Can be used in count way: -vv or --verbose --verbose (default: None)
      -f, --force           Force kill servers (default: False)
      -k KILL_TIMEOUT, --kill-timeout KILL_TIMEOUT
                            Time before force killing (in seconds) (default: 30)
      -s STARTER_TIMEOUT, --starter-timeout STARTER_TIMEOUT
                            Time to wait for starter if it's not running (in seconds) (default: 10)
      -d, --dry-run         outputs the servers with the details that will take effect by the command (default: False)

**Restart**

    > takeoff restart --help
    usage: takeoff restart [-h] [--json] [--default-host DEFAULT_HOST] [-v] [-f] [-k KILL_TIMEOUT] [-t RUNNING_TIMEOUT] [-s STARTER_TIMEOUT] [-d] [-w WAIT_AFTER_STOP] servers [servers ...]

    positional arguments:
      servers               A name or search term of a server, use * for wildcard in the end of the name. Use the format [host,]<server-name>

    options:
      -h, --help            show this help message and exit
      --json                Output structured as JSON (default: False)
      --default-host DEFAULT_HOST
                            Default host for Tango device servers (default: None)
      -v, --verbose         Set the trace level. Can be used in count way: -vv or --verbose --verbose (default: None)
      -f, --force           Force kill servers (default: False)
      -k KILL_TIMEOUT, --kill-timeout KILL_TIMEOUT
                            Time before force killing (in seconds) (default: 30)
      -t RUNNING_TIMEOUT, --timeout RUNNING_TIMEOUT
                            Time to wait for a server to be running (in seconds) (default: 60)
      -s STARTER_TIMEOUT, --starter-timeout STARTER_TIMEOUT
                            Time to wait for starter if it's not running (in seconds) (default: 10)
      -d, --dry-run         outputs the servers with the details that will take effect by the command (default: False)
      -w WAIT_AFTER_STOP, --wait-after-stop WAIT_AFTER_STOP
                            Time to wait between stop / start (in seconds) (default: 1)

## Testing

To test locally, you can use [pixi](https://pixi.sh).

Required setup:

1. You can use our own mariadb if you already have an instance running.
If not, run `pixi run mariadb`. It will start a mariadb docker image with the Tango schema already configured.
It can be stopped with `pixi run stop-mariadb`. Data will be saved locally under `.data`.
1. Start a Tango `Databaseds` by running `pixi run db`. Same as before. You could use your own instance if you prefer.
Press CTRL-C to stop it.
1. export `TANGO_HOST` to point to your tango database (`127.0.0.1:10000` if you used the previous steps).
1. Start `Starter` by running `pixi run starter`. This will automatically create the required Tango devices and install
some servers for testing purpose:

    - `TangoTest`
    - `UniversalTest`
    - [SlowToStart](./tests/data/servers/SlowToStart): a dummy server that takes 7 seconds to start
    - [SlowToStop](./tests/data/servers/SlowToStop): a dummy server that takes 7 seconds to stop
    - [FailToStart](./tests/data/servers/FailToStart): a dummy server that can't start (raises an exception in `init_device`)

Once you have `Starter` running, you can run the tests using `pixi run pytest -v`.

You can also manually test different scenarios by running `pixi run takeoff` and passing any argument you want. Or run `pixi shell` and then `takeoff` directly.

For convenience, you have 2 tasks predefined:

- `pixi run up` to start all the servers
- `pixi run down` to stop all the servers
