squirrel.selection

class Selection(database, persistent=None)

Bases: object

Database backed file selection (base class for Squirrel).

Parameters:

• database (Database or str) – Database instance or file path to database.
• persistent (str) – If given a name, create a persistent selection.

A selection in this context represents the list of files available to the application. Instead of using Selection directly, user applications should usually use its subclass Squirrel which adds content indices to the selection and provides high level data querying.

By default, a temporary table in the database is created to hold the names of the files in the selection. This table is only visible inside the application which created it. If a name is given to persistent, a named selection is created, which is visible also in other applications using the same database.

Besides the filename references, desired content kind masks and file format indications are stored in the selection’s database table to make the user choice regarding these options persistent on a per-file basis. Book-keeping on whether files are unknown, known or if modification checks are forced is handled in the selection’s file-state table.

Paths of files can be added to the selection using the add() method and removed with remove(). undig_grouped() can be used to iterate over all content known to the selection.

is_new()

Is this a new selection?

Always True for non-persistent selections. Only False for a persistent selection which already existed in the database when the it was initialized.

get_database()

Get the database to which this selection belongs.

Returns:Database object

add(paths, kind_mask=255, format='detect', show_progress=True)

Add files to the selection.

Parameters:

• paths (iterator yielding str objects) – Paths to files to be added to the selection.
• kind_mask (int (bit mask)) – Content kinds to be added to the selection.
• format (str) – File format identifier or 'detect' to enable auto-detection (available: 'datacube', 'mseed', 'pyrocko_events', 'pyrocko_stations', 'sac', 'stationxml', 'tdms_idas', 'virtual', 'yaml').

remove(paths)

Remove files from the selection.

Parameters:paths (list of str) – Paths to files to be removed from the selection.

iter_paths(raw=False)

Iterate over all file paths currently belonging to the selection.

Yields:File paths.

get_paths(raw=False)

Get all file paths currently belonging to the selection.

Returns:List of file paths.

undig_grouped(skip_unchanged=False)

Get inventory of cached content for all files in the selection.

Parameters:skip_unchanged (bool) – If True only inventory of modified files is yielded (flag_modified() must be called beforehand).

This generator yields tuples ((format, path), nuts) where path is the path to the file, format is the format assignation or 'detect' and nuts is a list of Nut objects representing the contents of the file.

flag_modified(check=True)

Mark files which have been modified.

Parameters:check (bool) – If True query modification times of known files on disk. If False, only flag unknown files.

Assumes file state is 0 for newly added files, 1 for files added again to the selection (forces check), or 2 for all others (no checking is done for those).

Sets file state to 0 for unknown or modified files, 2 for known and not modified files.