zabgrab.cli.reading

Options and helpers shared by commands that read a file’s merged data.

zabgrab export, zabgrab info and zabgrab plot select items, times and groups the same way.

Functions

check_readable(file, verb)	Refuse delimited files, which commands reading merged data can't read.
nothing_selected(file)	Suggest how to find what to select in a file, when nothing was.
read_dataset(app, file, *, verb, items, ...)	Read a file's merged data, limited to the selected items, times and groups.
selection_options(function)	Add the --item, --match, --from, --to and --group options.
time_range(app, from_, to)	Parse --from and --to, in the configured time zone.

zabgrab.cli.reading.selection_options(function)

Add the --item, --match, --from, --to and --group options.

Parameters:

function (callable) – The click command to add them to.

Returns:

callable – The command, taking items, match, from_, to and groups arguments.

Return type:

F

zabgrab.cli.reading.read_dataset(app, file, *, verb, items, match, from_, to, groups)

Read a file’s merged data, limited to the selected items, times and groups.

Parameters:

• app (AppContext) – For the config (the time zone --from/--to are in), clock and UI.

• file (Path) – A .mat or .h5 file written by zabgrab.

• verb ((str, str)) – What the command does, and its past participle, for messages (e.g. ("export", "exported")).

• items (Sequence[ItemSpec]) – The --item, --match, --from, --to and --group values. Items are kept if any --item or --match selects them.

• match (Sequence[str]) – The --item, --match, --from, --to and --group values. Items are kept if any --item or --match selects them.

• from – The --item, --match, --from, --to and --group values. Items are kept if any --item or --match selects them.

• to (str | None) – The --item, --match, --from, --to and --group values. Items are kept if any --item or --match selects them.

• groups (Sequence[str]) – The --item, --match, --from, --to and --group values. Items are kept if any --item or --match selects them.

• from_ (str | None)

Returns:

• Dataset – The merged, filtered data.

• tzinfo or None – The configured time zone (None for local time).

Raises:

• ZabgrabError – If file is a delimited file, or has no such groups.

• click.BadParameter – If --from or --to can’t be parsed.

Return type:

tuple[Dataset, tzinfo | None]

zabgrab.cli.reading.check_readable(file, verb)

Refuse delimited files, which commands reading merged data can’t read.

Parameters:

• file (Path) – The file.

• verb ((str, str)) – What the command does, and its past participle, for the message.

Raises:

ZabgrabError – If file is a delimited file.

Return type:

None

zabgrab.cli.reading.time_range(app, from_, to)

Parse --from and --to, in the configured time zone.

Parameters:

• app (AppContext) – For the config (the time zone) and the clock.

• from (str or None) – The options’ values, if given.

• to (str or None) – The options’ values, if given.

• from_ (str | None)

Returns:

• start, end (datetime or None) – The times, if given.

• tz (tzinfo or None) – The configured time zone (None for local time).

Raises:

click.BadParameter – If a time can’t be parsed.

Return type:

tuple[datetime | None, datetime | None, tzinfo | None]

zabgrab.cli.reading.nothing_selected(file)

Suggest how to find what to select in a file, when nothing was.

Parameters:

file (Path) – The file.

Returns:

str – The hint.

Return type:

str