populse_mia.data_manager.database_mia¶

Module containing a class that provides tools adapted to Mia for interacting with the populse_db API.

Contains:

Class:

DatabaseMIA
DatabaseMiaSchema
DatabaseMiaData

Classes

`DatabaseMIA`(database_engine)	Class providing tools for interacting with a database, under the supervision of populse_db.
`DatabaseMiaData`(storage_data)	Managing database interactions within the MIA framework.
`DatabaseMiaSchema`(storage_schema)	Provides tools for managing the schema of a MIA database.

populse_mia.data_manager.database_mia.contextmanager(func)[source]¶

@contextmanager decorator.

Typical usage:

@contextmanager def some_generator(<arguments>):

<setup> try:

yield <value>

finally:
<cleanup>

This makes this:

with some_generator(<arguments>) as <variable>:
<body>

equivalent to this:

<setup> try:

<variable> = <value> <body>

finally:
<cleanup>

populse_mia.data_manager.database_mia.str_to_type(str)[source]¶

Convert a string to a Python type.

Examples

str_to_type('str') == str
str_to_type('list[str]') == list[str]

populse_mia.data_manager.database_mia.type_to_str(type)[source]¶

Convert a Python type to a string.

Examples

type_to_str(str) == 'str'
type_to_str(list[str]) == 'list[str]'

class populse_mia.data_manager.database_mia.Storage(database_file: str | Path, timeout: float | None = 10000, create: bool = False, echo_sql: TextIO | None = None, secret: str | None = None)[source]¶

Bases: object

default_collection = '_'¶

schema_collection = '_schema'¶

default_field = '_'¶

default_document_id = '_'¶

__init__(database_file: str | Path, timeout: float | None = 10000, create: bool = False, echo_sql: TextIO | None = None, secret: str | None = None)[source]¶

access_token(write)[source]¶

data(exclusive=None, write=False, create=False)[source]¶

schema()[source]¶

start_session(exclusive=None, write=False, create=False)[source]¶

end_session(storage_session, rollback=False)[source]¶

populse_mia.data_manager.database_mia.FIELD_TYPE_BOOLEAN¶: alias of bool

populse_mia.data_manager.database_mia.FIELD_TYPE_STRING¶: alias of str

class populse_mia.data_manager.database_mia.DatabaseMIA(database_engine)[source]¶

Bases: object

Class providing tools for interacting with a database, under the supervision of populse_db.

__init__(database_engine)[source]¶

Initializes a DatabaseMIA instance with the given database file.

Parameters:: (str) (database_engine) – Path to the database file (e.g., ‘/a/folder/path/file.db’).

close()[source]¶

Closes any open resources or connections held by the instance.

This method sets the storage attribute to None, effectively releasing any held references and cleaning up the object’s state.

data(write=None, create=None)[source]¶

Provides a context manager for accessing the database data layer.

This method allows safe read and write access to the database data, ensuring proper resource management.

Parameters:

(bool) (create) – If True, enables write mode.
(bool) – If True, allows creating new records.

Yields (DatabaseMiaData):

The data interface for the database.

schema()[source]¶

Provides a context manager for accessing the database schema.

This method allows safe access to the database schema, ensuring proper resource management.

Yields (DatabaseMiaSchema):: The schema interface for the database.

class populse_mia.data_manager.database_mia.DatabaseMiaSchema(storage_schema)[source]¶

Bases: object

Provides tools for managing the schema of a MIA database.

This class allows users to manipulate database collections, fields, and field attributes under the supervision of populse_db.

__init__(storage_schema)[source]¶

Initializes the DatabaseMiaSchema instance.

Parameters:: (populse_db.storage.Storage) (storage_schema) – The schema storage interface for the database.

add_collection(collection_name, primary_key, visibility, origin, unit, default_value)[source]¶

Add a new collection to the storage database, if it does not already exist.

This method overrides the default behavior to add a collection with additional field attributes, ensuring proper schema updates and collection initialization.

Parameters:

(str) (unit) – The name of the new collection.
(str) – The primary key column for the collection.
(bool) (visibility) – Visibility of the primary key field.
(str) – Origin of the primary key field.
(str) – Unit of the primary key field.
(Any) (default_value) – Default value for the primary key field.

add_field(fields)[source]¶

Adds one or more fields to the collection.

Each field should be represented as a dictionary containing the following keys:

collection_name (str): The collection to which the field belongs.
field_name (str): The name of the field.
field_type (str): The data type of the field.
description (str): A brief description of the field.
visibility (bool): The visibility status of the field.
origin (str): The origin of the field.
unit (str): The unit associated with the field.
default_value (Any): The default value of the field.

Parameters:: list[dict]) (fields (dict |) – A dictionary representing a single field’s attributes, or a list of dictionaries representing multiple fields’ attributes.

add_field_attributes_collection()[source]¶

Ensures that the FIELD_ATTRIBUTES_COLLECTION is available in the database.

If it does not exist, it creates the collection and adds specific fields to it such as ‘visibility’, ‘origin’, ‘unit’, and ‘default_value’.

data()[source]¶

Provides a context manager for accessing the database data.

This method ensures safe access to the database data layer, managing resources properly.

Yields (DatabaseMiaData):: The data interface for the database.

remove_field(collection_name, field_name)[source]¶

Removes a specified field in the collection_name

This method updates the schema to remove the specified field from the collection and handles associated attributes cleanup.

Parameters:

(str) (field_name) – The name of the collection from which the field will be removed (must exist).
(str) – The name of the field to remove (must exist).

Raises:

ValueError – If the collection_name does not exist or if the field_name does not exist.

remove_field_attributes(collection_name, field_name)[source]¶

Remove attributes associated with a specific field in a collection.

This method deletes the document storing metadata or attributes for the specified field in the given collection.

Parameters:

(str) (field_name) – The name of the collection containing the field.
(str) – The name of the field whose attributes are to be removed.

Raises:

ValueError – If the attributes document does not exist or cannot be removed.

update_field_attributes(collection_name, field_name, visibility, origin, unit, default_value, description, field_type)[source]¶

Updates the attributes of a field in the database for a specific collection.

This method constructs an index using the provided collection and field_name (‘collection|field_name’), and then updates the field’s attributes in the FIELD_ATTRIBUTES_COLLECTION.

Parameters:

(str) (description) – The name of the collection the field belongs to.
(str) – The name of the field to update.
(bool) (visibility) – The visibility status of the field.
(str) – The origin or source of the field.
(str) – The unit of measurement for the field.
(Any) (field_type) – The default value to assign to the field.
(str) – The description of the field.
(Any) – The type of the field.

class populse_mia.data_manager.database_mia.DatabaseMiaData(storage_data)[source]¶

Bases: object

Managing database interactions within the MIA framework.

This class provides methods to handle collections and documents within the database, allowing operations such as retrieving, adding, updating, and removing records.

__init__(storage_data)[source]¶

Initializes a new instance of the DatabaseMiaData class.

Parameters:: (populse_db.storage.Storage) (storage_data) – The data storage interface for the database.

add_document(collection_name, document)[source]¶

Adds a document to a specified collection in the storage.

If the specified collection exists, the document is added to it. The method assigns a primary key to the document based on the collection’s primary key configuration. The changes are saved to the storage.

Parameters:

(str) (document) – The name of the collection where the document should be added.
(str) – The document name to be added.

filter_documents(collection_name, filter_query)[source]¶

Retrieve documents from a specified collection that match a given filter.

This method searches for documents in the specified collection based on the provided filter query. It returns the results as a list of rows from the collection table.

The filter_query can either be:

The result of self.filter_query().
A string defining a filter.

Filter Query Format:

A filter condition must follow this syntax:
{<field>} <operator> “<value>”.
Supported operators:
==, !=, <=, >=, <, >, IN, ILIKE, LIKE.
Multiple filter conditions can be combined using AND or OR.
Example:
` "((({BandWidth} == "50000")) AND (({FileName} LIKE "%G1%")))" `

Note: Due to potential database access issues such as “database already open.”, this implementation currently returns a list instead of using yield. However, using yield may be reconsidered in the future for better memory management.

Parameters:

(str) (filter_query) – The name of the collection to filter (must exist).
(str) – The filter query to apply.

Return (list):

A list of rows matching the filter criteria.

get_collection_names()[source]¶

Retrieves a list of all collection names in the database.

Return (list):: All collection names in the database.

get_document(collection_name, primary_keys=None, fields=None)[source]¶

Retrieve documents from the specified collection with optional filtering.

This method checks if the specified collection exists. If it does, it retrieves documents from the collection, optionally filtering by primary keys and selecting specific fields. If the collection does not exist, an empty list is returned.

Parameters:

(str) (collection_name) – Name of the document collection. The collection must already exist in the database.
optional) (fields (str | list[str],) – A single primary key or a list of primary keys to filter documents. If None, no filtering by primary keys is applied.
optional) – A single field or a list of fields to include in the result. If None, all fields are included.

Return (list):

A list of documents matching the specified criteria, or an empty list if the collection does not exist.

get_document_names(collection_name)[source]¶

Retrieve a list of all document names in the specified collection.

Parameters:: (str) (collection_name) – The name of the collection to retrieve document names from. The collection must already exist.
Return (list[str]):: A list of document names if the collection exists, otherwise an empty list.

get_field_attributes(collection_name, field_name=None)[source]¶

Retrieve attributes of a specific field or all fields in a collection from the storage.

Parameters:

(str) (collection_name) – The name of the collection.
optional) (field_name (str,) – The name of a specific field within the collection. If not provided, attributes for all fields in the collection will be retrieved.

Return (dict | list[dict]):

Attributes of the specified field as a dictionary, or a list of dictionaries with attributes for all fields if field_name is not provided.

get_field_names(collection_name)[source]¶

Retrieve the list of all field names in the specified collection.

Parameters:: (str) (collection_name) – The name of the collection to retrieve field names from. The collection must exist in the database.
Return (list | None):: A list of all field names in the collection if it exists, or None if the collection has no fields or does not exist.

get_primary_key_name(collection_name)[source]¶

Retrieve the primary key of the specified collection.

This method returns the first key from the specified collection within the database.

Parameters:: (str) (collection_name) – The name of the collection to retrieve the primary key from.
Return (str):: The first key in the collection, representing the primary key.

get_shown_tags()[source]¶

Give the list of visible tags.

Return (list):: The list of visible tags.

get_value(collection_name, primary_key, field)[source]¶

Retrieves the current value of a specific field in a document from the specified collection.

This method accesses the underlying storage to fetch the value of a given field within a document, identified by its primary key, in the specified collection.

Parameters:

(str) (field) – The name of the collection containing the document.
(str) – The unique identifier (primary key) of the document.
(str) – The name of the field within the document to retrieve.

Return (Any):

The current value of the specified field.

has_collection(collection_name)[source]¶

Checks if a collection with the specified name exists in the database.

Parameters:: (str) (collection_name) – The name of the collection to check.
Return (bool):: True if the collection exists, otherwise False.

has_document(collection_name, primary_key)[source]¶

Checks if a document with the specified primary key exists in the given collection.

Parameters:

(str) (primary_key) – The name of the collection.
(str) – The primary key of the document to check.

Return (bool):

True if the document exists, False otherwise.

remove_document(collection_name, primary_key)[source]¶

Remove a document from a specified collection.

This method deletes the document identified by primary_key from the given collection in the storage.

Parameters:

(str) (primary_key) – The name of the collection containing the document.
(str) – The unique identifier of the document to be removed.

Raises:

KeyError – If the collection or the document does not exist.

remove_value(collection_name, primary_key, field)[source]¶

Removes the specified field from a document in the given collection, if it exists. Raises a KeyError if the field, collection, or document is not found.

Parameters:

(str) (field) – The name of the collection containing the document.
(str) – The primary key of the document in the collection.
(str) – The field to be removed from the document.

Raises:

KeyError – If the collection or document cannot be found.

set_shown_tags(fields_shown)[source]¶

Set the list of visible tags.

Parameters:: (list) (fields_shown) – A list of visible tags.

set_value(collection_name, primary_key, values_dict)[source]¶

Store or update a record in the specified collection.

This method either stores a new record or updates an existing record in the specified collection, using the provided primary key. The fields of the record are set according to the data in the provided dictionary.

Parameters:

(str) (primary_key) – The name of the collection where the record will be stored or updated.
(str) – The unique key used to identify the record.
(dict) (values_dict) – A dictionary containing the data to store or update in the record. Keys represent field names, and values represent the corresponding data.