GeoEco.Datasets.SQLite.SQLiteDatabase

class GeoEco.Datasets.SQLite.SQLiteDatabase(path, timeout=5.0, isolation_level=None, detect_types=3, decompressedFileToReturn=None, displayName=None, parentCollection=None, queryableAttributes=None, queryableAttributeValues=None, lazyPropertyValues=None, cacheDirectory=None)

Bases: FileDatasetCollection, Database

A FileDatasetCollection and Database representing a SQLite database.

Parameters:

path (str) –
Database to open. This can either be ‘:memory:’, indicating that a new in-memory database should be opened, or a file.

If it is a file and and there is no parent collection, this is the full path to the file. It will be opened as stand-alone collection.

If there is a parent collection, this path is relative to it. For example, if the parent collection is a DirectoryTree, this path is relative to a leaf directory of the DirectoryTree. Often, the leaf directory will be the one containing the file, in which case the path provided here will simply be the name of the file.

If the path points to compressed file, it will be decompressed automatically. If a cache directory is provided, it will be checked first for an existing decompressed file. If none is found the file will be decompressed there.

If the compressed file is an archive (e.g. .zip or .tar), you must also specify a decompressed file to return.

Minimum length꞉ 1.
timeout (float, optional) – When a database is accessed by multiple connections, and one of the processes modifies the database, the SQLite database is locked until that transaction is committed. This parameter specifies how long the connection should wait for the lock to go away until raising an exception. Minimum value꞉ 0.0.
isolation_level (str, optional) –
SQLite isolation level to use, either None for autocommit mode (the default), or 'DEFERRED', 'IMMEDIATE', or 'EXCLUSIVE'. If you specify one of these, a transaction will be started for you automatically according to SQLite’s rules. Performing many updates or inserts in a transaction rather than with autocommit mode can result in higher performance. However, when you are done, you must explicitly commit the transaction by calling commit() on Connection. To rollback the transaction, call rollback().

Warning

Neither SQLiteDatabase nor SQLiteTable will ever commit a transaction for you. If you open a connection with an isolation_level other than None, and you do not explicitly commit the transaction, it will be implicitly rolled back by Python when the connection is closed, and your changes will be lost.

Allowed values꞉ 'DEFERRED', 'IMMEDIATE', 'EXCLUSIVE'. Case sensitive.
detect_types (int, optional) –
Controls whether SQLite will detect and convert custom types other than the natively-supported types TEXT, INTEGER, FLOAT, BLOB and NULL.

By default, this is set to sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES, which enables type detection and conversion. The underlying Python sqlite3 module automatically supports conversion of the “date” datatype to datetime.date and “timestamp” data type to datetime.datetime. You can enable detection and conversion of additional types by registering adapters and convertors with sqlite3 prior to connecting to the database. See the sqlite3 documentation for more information.

Set this to 0 to disable type detection and conversion.
decompressedFileToReturn (str, optional) –
glob() expression that identifies the extracted file to open when the path points to an archive (e.g. a .zip or .tar file).

This expression must select exactly one of the extracted files. Be sure to leave it as None when the path does not point to an archive. Minimum length꞉ 1.
displayName (str, optional) – Informal name of this database to be displayed to the user. If you do not provide a name, a suitable name will be created automatically. Minimum length꞉ 1.
parentCollection (DatasetCollection, optional) – Parent DatasetCollection that this object is part of (if any).
queryableAttributes (tuple of QueryableAttribute, optional) – Queryable attributes defined for this object.
queryableAttributeValues (dict mapping str to object, optional) – Values of the queryable attributes, expressed as a dictionary mapping the case-insensitive names of queryable attributes to their values.
lazyPropertyValues (dict mapping str to object, optional) – Lazy properties to set when this object is constructed, expressed as a dictionary mapping the names of lazy properties to their values.
cacheDirectory (str, optional) –
Directory to cache a copy of the downloaded or decompressed file.

If provided, this directory will be checked for the file prior to download or decompression. If the file is found, the download and decompression will be skipped. Thus, when performing repetitive processing with remote or compressed datasets, you can speed up processing considerably by providing a cache directory.

Minimum length꞉ 1.

Returns:

SQLiteDatabase instance.

Return type:

SQLiteDatabase

Properties

property CacheDirectory

(str or None) Directory for caching local copies of remote datasets. Minimum length꞉ 1. If a cache directory is not provided, then after a remote dataset is downloaded it will be kept either only in memory or in a temporary directory on disk, depending on the type of data it is. The temporary directory will be automatically deleted when Close() is called.

If a cache directory is provided, remote datasets will be stored in it when they are downloaded. Before a download is attempted, the cache directory will be checked first for the relevant dataset, and if it is found, the download will be skipped, speeding up execution.

The datasets are organized in the cache directory in an undocumented format that is specific to the collection. Once a dataset is stored in the cache directory, it is never changed or deleted. If the original remote datasets are changed, these changes will not be detected and the cache will not be updated. If the disk fills up, cached datasets will not be automatically deleted to mitigate the problem.

If you determine that the cached datasets are obsolete or the disk is too full, delete the entire cache directory. You may also be able to delete a portion of it, if you can reverse engineer how datasets are stored within it, but the organizational structure is not documented.

property Connection: (Connection) sqlite3.Connection object that SQLiteDatabase is using to interact with the database. Read only.

property DecompressedFileToReturn: (str or None) glob() expression that identifies the extracted file to open when the path points to an archive (e.g. a .zip or .tar file). Read only. Minimum length꞉ 1. This expression must select exactly one of the extracted files. Be sure to leave it as None when the path does not point to an archive.

property DisplayName: (str) Informal name of this object, suitable to be displayed to the user. Read only. Minimum length꞉ 1.

property ParentCollection: (DatasetCollection or None) Parent DatasetCollection that this object is part of (if any). Read only.

property Path

(str) Path to the file to open. Read only. Minimum length꞉ 1. If there is no parent collection, this is the full path to the file. It will be opened as stand-alone collection.

If there is a parent collection, this path is relative to it. For example, if the parent collection is a DirectoryTree, this path is relative to a leaf directory of the DirectoryTree. Often, the leaf directory will be the one containing the file, in which case the path provided here will simply be the name of the file.

If the path points to compressed file, it will be decompressed automatically. If a cache directory is provided, it will be checked first for an existing decompressed file. If none is found the file will be decompressed there.

If the compressed file is an archive (e.g. .zip or .tar), you must also specify a decompressed file to return.

Methods

`Close`	Closes any open files or connections associated with this object and releases any other resources allocated to access it.
`CreateTable`	Creates a table.
`CreateTableFromTemplate`	Creates a table and adds to it the fields present another table (the template).
`DeleteLazyPropertyValue`	Deletes the lazy property with the specified name.
`DeleteTable`	Deletes a table.
`GetAllQueryableAttributes`	Returns a list of all queryable attributes.
`GetLazyPropertyValue`	Returns the value of the lazy property with the specified name.
`GetNewestDataset`	Queries the collection and returns the newest `Dataset` that matches the search expression.
`GetOldestDataset`	Queries the collection and returns the oldest `Dataset` that matches the search expression.
`GetQueryableAttribute`	Returns the queryable attribute with the specified name.
`GetQueryableAttributeValue`	Returns the value of the queryable attribute with the specified name.
`GetQueryableAttributesWithDataType`	Returns a list queryable attributes having the specified data type.
`HasLazyPropertyValue`	Returns True if the specified lazy property has a value.
`ImportDatasets`	Copies each `Dataset` in a `list` into this `DatasetCollection`.
`ImportTable`	Creates a new table from an existing `Table`, copying some or all of its fields and rows.
`QueryDatasets`	Queries the collection and returns a `list` of `Dataset`s that match a search expression.
`SetLazyPropertyValue`	Sets the lazy property with the specified name to the specified value.
`TableExists`	Returns True if the specified table exists.
`TestCapability`	Tests whether a capability is supported by this class or an instance of it.