zabgrab.services.output

Deciding where and how to save fetched data.

zabgrab.services.output.STRUCTURED

Formats that hold several fetches (as groups), so can be appended to.

Type:

tuple of Format

zabgrab.services.output.MAT_TEXT_BYTES

The measured size of a text entry in a .mat file (see benchmarks/mat_text.py).

Type:

int

zabgrab.services.output.MAT_TEXT_WRITE_SECONDS

The measured time to write a text entry to a .mat file.

Type:

float

zabgrab.services.output.FORMAT_FIX

How to choose the format without being asked.

Type:

str

Functions

auto_name(query, *, hosts, server)

Make the automatic file name (without extension) for a query's data.

choose_formats(configured, cli_format, file, ui)

Choose the output format(s).

existing_target(path, format, ui, options)

Decide how to save to a file, asking what to do if it exists.

guard_large_text(target, result, ui, *, ...)

Warn before writing a lot of text to a .mat file.

targets(outputs, query, ui, *, name, options)

Decide where to save the data.

text_entries(result)

Count a fetch's text values (each is a cell entry in a .mat file).

Classes

SaveOptions([format, overwrite, append, ...])

Command line options about saving.

Target(path, format[, append, ...])

A file to save data to.
class zabgrab.services.output.Target(path, format, append=False, large_text_accepted=False)[source]

Bases: object

A file to save data to.

Parameters:
path

The file.

Type:

Path

format

Its format.

Type:

Format

append

Add a group to the file (which may not exist yet), rather than replace it.

Type:

bool

large_text_accepted

The user accepted writing a lot of text to a .mat file, which is recorded in it so later appends don’t ask again.

Type:

bool

class zabgrab.services.output.SaveOptions(format=None, overwrite=False, append=False, group=None, in_place=False, allow_large_text=False, plot=False)[source]

Bases: object

Command line options about saving.

Parameters:
format

--format.

Type:

Format or None

overwrite

--overwrite.

Type:

bool

append

--append.

Type:

bool

group

--group: the name of the group to append.

Type:

str or None

in_place

--in-place: append without copying the file first.

Type:

bool

allow_large_text

--allow-large-text.

Type:

bool

plot

--plot: the data will be plotted, so without --output it’s neither saved nor asked about.

Type:

bool

check(outputs)[source]

Reject options that don’t make sense together.

Parameters:

outputs (sequence of str) – The --output values given (none if it wasn’t).

Raises:

ZabgrabError – If the options conflict.

Return type:

None

zabgrab.services.output.auto_name(query, *, hosts, server)[source]

Make the automatic file name (without extension) for a query’s data.

Parameters:

  • query (Query) – The query, whose output_pattern is filled in.

  • hosts (sequence of str) – The names of the hosts the data comes from.

  • server (str) – A short name for the server the data comes from.

Returns:

str – The name.

Return type:

str

zabgrab.services.output.targets(outputs, query, ui, *, name, options)[source]

Decide where to save the data.

Parameters:

  • outputs (sequence of str) – The --output values, each saved to: "" for an automatic name in output_dir, a directory for an automatic name there, or a file. With none, the user is asked (or, if the session isn’t interactive or the data is plotted, it isn’t saved).

  • query (Query) – The query, for its configured formats and output directory.

  • ui (UI) – For questions and messages.

  • name (str) – The automatic file name (see auto_name()).

  • options (SaveOptions) – The other command line options about saving.

Returns:

list of Target – The files to write (one per output and format, each path once); empty if the data isn’t to be saved.

Raises:
Return type:

list[Target]

zabgrab.services.output.choose_formats(configured, cli_format, file, ui, answers=None)[source]

Choose the output format(s).

Parameters:

  • configured (sequence of Format) – The formats from the template or [defaults].

  • cli_format (Format or None) – --format, which wins if given.

  • file (Path or None) – The output file, whose extension is used next.

  • ui (UI) – For asking, when nothing else decides.

  • answers (Answers, optional) – Where to record the answer, if asked.

Returns:

tuple of Format – The formats.

Raises:

InputRequired – If nothing decides and the session isn’t interactive.

Return type:

tuple[Format, …]

zabgrab.services.output.existing_target(path, format, ui, options)[source]

Decide how to save to a file, asking what to do if it exists.

Parameters:

  • path (Path) – The file.

  • format (Format) – Its format.

  • ui (UI) – For asking; non-interactive sessions save next to it instead.

  • options (SaveOptions) – --overwrite and --append decide without asking.

Returns:

Target – Where to save.

Raises:

Cancelled – If the user cancels.

Return type:

Target

zabgrab.services.output.text_entries(result)[source]

Count a fetch’s text values (each is a cell entry in a .mat file).

Parameters:

result (FetchResult) – The fetched data.

Returns:

int – The number of text values, including log sources.

Return type:

int

zabgrab.services.output.guard_large_text(target, result, ui, *, threshold, allow, existing_entries, accepted_before)[source]

Warn before writing a lot of text to a .mat file.

Text makes .mat files big and slow to load in MATLAB. Interactive users can continue, save as .h5 instead, skip the text items or cancel; others get a warning. Accepting (or allow) is remembered in the file, so later appends don’t ask again.

Parameters:

  • target (Target) – Where the data is to be saved.

  • result (FetchResult) – The data.

  • ui (UI) – For warnings and questions.

  • threshold (int) – How many text values (including those already in the file) to allow without warning; 0 never warns.

  • allow (bool) – --allow-large-text.

  • existing_entries (callable) – Counts the text values already in a file.

  • accepted_before (callable) – Whether a file records that large text was accepted before.

Returns:

tuple of Target and FetchResult – Where to save, and what (without the text items if they’re left out).

Raises:

Cancelled – If the user cancels.

Return type:

tuple[Target, FetchResult]