Command Line Interface

happi

The happi command-line interface, used to view and manipulate device databases

happi [OPTIONS] COMMAND [ARGS]...

Options

--path <path>

Provide the path to happi configuration file. Will default to the file stored in the HAPPI_CFG environment variable.

-v, --verbose

Show the debug logging stream.

-V, --version

Show the version and exit.

add

Add new entries or copy existing entries.

happi add [OPTIONS]

Options

--clone <clone>

Copy the fields from an existing container. Provide the name of the item to clone.

audit

Audit the current happi database.

Runs checks on the devices matching the provided SEARCH_CRITERIA. Checks are simple functions that raise exceptions on failure, whether naturally or via assert calls. These functions take a single happi.SearchResult as an positional argument and returns None if successful.

To import additional checks, provide a file with your check function and a list named checks containing the desired functions.

happi audit [OPTIONS] [SEARCH_CRITERIA]...

Options

-f, --file <ext_file>

File to import additional checks from.

-l, --list

List the available validation checks

-c, --check <check_choices>

Name of the check to include. Can also provide a substring

-d, --details <details>

Show the details of the specified audit function(s)

--glob, --regex

Use glob style (default) or regex style search terms. Regex requires backslashes to be escaped (eg. at\d.\d)

-n, --names

Only display names of failed entries

-j, --json

output results in json format

Arguments

SEARCH_CRITERIA

Optional argument(s)

benchmark

Compare happi device startup times.

This will generate a table that shows you how long each device took to instantiate.

Repeats for at least the (-d, –duration) arg (default = 0 seconds) and for at least the number of the (-i, –iterations) arg (default = 1 iteration), showing stats and averages.

By default we time only the duration of __init__, but you can also (wait_connected) to see the full time until the device is fully ready to go, presuming the device has a wait_for_connection method.

Search terms are standard as in the same search terms as the search cli function. A blank search term means to load all the devices.

happi benchmark [OPTIONS] [SEARCH_CRITERIA]...

Options

-d, --duration <duration>

Specify how long in seconds to spend per device.

-i, --iterations <iterations>

Specify the number of times to instantiate each device.

-w, --wait-connected

Wait for the devices to be connected.

-t, --tracebacks

Show tracebacks from failing device loads.

-s, --sort-key <sort_key>

Sort the output table. Valid options are name, avg_time, iterations, tot_time, max_time, import_time

--glob, --regex

Use glob style (default) or regex style search terms. Regex requires backslashes to be escaped (eg. at\d.\d)

Arguments

SEARCH_CRITERIA

Optional argument(s)

container-registry

Print container registry

happi container-registry [OPTIONS]

copy

Copy the item NAME.

Simply wraps happi add --clone

happi copy [OPTIONS] NAME

Arguments

NAME

Required argument

delete

Delete an existing entry. Only accepts exact names

happi delete [OPTIONS] NAME

Arguments

NAME

Required argument

edit

Change an existing entry.

Applies EDITS of the form: field=value to the item of name NAME.

happi edit [OPTIONS] NAME [EDITS]...

Arguments

NAME

Required argument

EDITS

Optional argument(s)

load

happi load [OPTIONS] [SEARCH_CRITERIA]...

Options

--glob, --regex

use glob style (default) or regex style search terms. Regex requires backslashes to be escaped (eg. at\d.\d)

Arguments

SEARCH_CRITERIA

Optional argument(s)

profile

Per-function startup speed diagnostic.

This will go through the happi loading process and show information about the execution time of all the functions called during the process.

Contains options for picking which devices to check and which part of the loading process to profile. You can choose to profile the happi database loading (-d, –database), the class imports (-i, –import), the object instantiation (-o, –object), or all of the above (-a, –all).

By default this will use whichever profiler you have installed, but this can also be overriden with the (-p, –profiler) option. The priority order is, first, the pcdsutils line_profiler wrapper (–profiler pcdsutils), and second, the built-in cProfile module (–profiler cprofile). More options may be added later.

Search terms are standard as in the same search terms as the search cli function. A blank search term means to load all the devices.

happi profile [OPTIONS] [SEARCH_CRITERIA]...

Options

-d, --database

Profile the database loading.

-i, --import

Profile the module importing.

-o, --object

Profile the object instantiation.

-a, --all

Shortcut for enabling all profile stages.

-p, --profiler <profiler>

Select which profiler to use.

--glob, --regex

Use glob style (default) or regex style search terms. Regex requires backslashes to be escaped (eg. at\d.\d)

Arguments

SEARCH_CRITERIA

Optional argument(s)

repair

Repair the database.

Repairs all entries matching SEARCH_CRITERIA, repairs entire database otherwise.

Entries that don’t get any fields changed will not get saved (i.e. their last-edit times will not change).

happi repair [OPTIONS] [SEARCH_CRITERIA]...

Options

--fix-optional, --ignore-optional

Also prompt for user input on optional information

--glob, --regex

Use glob (default) or regex style search terms. Only relevant if search_criteria are provided.

Arguments

SEARCH_CRITERIA

Optional argument(s)

transfer

Change the container of an item.

Transfers item (NAME) to a new container (TARGET)

happi transfer [OPTIONS] NAME TARGET

Arguments

NAME

Required argument

TARGET

Required argument

update

Update happi db with JSON_DATA payload.

To use, either use command substitution:

$ happi update $(cat my.json)

Or pipe the JSON payload with - as an argument:

$ cat my.json | happi update -

JSON payloads should be a list of items (dictionaries), with at least the “_id” and “type” keys. eg:

[{
“_id”: “my_device”,
<…>
“type”: “mydevicelibrary.MyDevice”
}]

Or a valid happi json database. eg:

{
“my_device”: {
“_id”: “my_device”,
<…>
“type”: “mydevicelibrary.MyDevice”
}
}
happi update [OPTIONS] [JSON_DATA]...

Arguments

JSON_DATA

Optional argument(s)