rotifer.db.sql.sqlite3.BaseSQLite3Cursor

class rotifer.db.sql.sqlite3.BaseSQLite3Cursor(path, replace=False, *args, **kwargs)

Bases: BaseCursor

Shared connection and query helpers for SQLite3 cursors.

This class is not meant to be used directly: it is a parent class that opens the database file and provides the temporary query table used by subclasses to submit batches of accessions. Failed lookups are still tracked through the inherited missing registry.

Parameters:

pathstr

Path to a SQLite3 database file. The file is created on first write if it does not exist.

replacebool, default False

If True, delete any existing file at path before opening the connection.

See also

rotifer.db.sql.sqlite3.GeneNeighborhoodCursor

gene neighborhood cursor

rotifer.db.sql.sqlite3.IPGCursor

identical protein group cursor

cleanup()

Remove this cursor’s rows from the temporary query table.

content_id()

Identify the data this database holds.

Answers only for a table loaded in full, and then with the identity of the file it came from, so that a cursor reading that file directly reports the same value and either can stand in for the other. A table never recorded, because its load was interrupted or predates this bookkeeping, yields None and nothing is skipped on its account.

Returns:

str or None

<path>:<size>:<mtime>, or None.

See also

rotifer.db.core.BaseCursor.content_id

what the value means

record_source

how the value gets written

create_sources()

Create this database’s load registry, if it is missing.

A row is written only by a load that ran to completion, which is what lets content_id() tell a database holding a whole copy of a file from one a failed load left partly filled.

forget_source(version=None, table=None)

Withdraw the record of a load.

A row in the registry is the claim that this table holds a whole copy of a file. Whatever removes the rows has to remove the claim too, or the table goes on being taken for a copy of something it no longer has.

Parameters:

versionstr, optional

Version whose record to drop. Defaults to source_version; pass an empty string to drop the records of every version of this table.

tablestr, optional

Table the record is about. Defaults to this cursor’s.

Returns:

bool

Whether anything could be removed.

has_table(name)

Find whether a table exists in the database.

Parameters:

namestr

Table name.

Returns:

bool

record_source(datafile, rows, version=None, table=None, checksum='')

Record that a table was loaded, whole, from a file.

Call this only where a load is known to have finished: the presence of a row is the claim of completeness.

Parameters:

datafilestr

Path of the file the rows came from. Recorded in full and with symbolic links resolved, so that the same file reached by two names is recorded as one file.

rowsint

Number of rows in the table afterwards.

versionstr, optional

Version label. Defaults to source_version.

tablestr, optional

Table loaded. Defaults to this cursor’s table.

checksumstr, optional

Checksum of the file, when one was computed. Recorded for verification; routine comparisons use the cheap identity below, which costs a stat() rather than a full read.

Returns:

bool

Whether the record was written.

recorded_source(table)

Identity of the file one table was loaded from.

Parameters:

tablestr

Name of the table.

Returns:

str or None

<path>:<size>:<mtime>, or None when the table has no record, which is what an interrupted load leaves.

stored(data, column='block_id', table='features')

Find which rows of the input data are already stored.

Parameters:

datastr, list, pandas.Series or pandas.DataFrame

Input data to scan for entries in the database.

columnstr or list of str

Column(s) to use while searching. Ignored when data is not a dataframe.

tablestr, default ‘features’

Name of the table to search for matches.

Returns:

pandas.Series of bool

True for rows whose value is already present in table.

submit(accessions)

Register query accessions in a temporary table.

Subclasses join this table against features (or another stored table) to restrict SQL queries to the requested accessions.

Parameters:

accessionsiterable

Any values supported by SQLite3, such as strings, integers or floats.

table_name(role=None)

Name the table filling one role in this cursor’s queries.

Parameters:

rolestr, optional

Which of the cursor’s tables. May be omitted only when there is one.

Returns:

str

property schema

The SQL statement used to create the database’s first table.

Returns:

str

property source_version

Version label distinguishing loads into the same table.

Databases holding several versions at once override this. The default is a single unversioned body of data.

Returns:

str

property sources_table

Name of this database’s load registry.

Returns:

str

tables = {'features': 'features'}

Tables these cursors read, keyed by the role each plays. A cursor joining several has no single table to be named after.