forensicfit.database.database module#

Created on Mon Apr 12 09:36:25 2021

@author: Pedram Tavadze used PyChemia Database class as a guide MaterialsDiscovery/PyChemia

class forensicfit.database.database.ClassMap[source]#

Bases: Mapping

A custom mapping class that maps string keys to specific classes.

This class is a subclass of collections.abc.Mapping and provides a custom mapping between string keys and classes. The keys ‘material’, ‘analysis’, and ‘any’ are mapped to the classes Tape, TapeAnalyzer, and Image respectively.

mapping#

The internal dictionary that stores the mapping between keys and classes.

Type:: dict

__contains__(x: str) → bool[source]#: Check if x is a key in the mapping.

__getitem__(x: str) → Tape | TapeAnalyzer | Image[source]#: Get the class associated with the key x. If x is not a key in the mapping, return the class associated with the key ‘any’.

__iter__() → Iterator[source]#: Return an iterator over the keys in the mapping.

__len__() → int[source]#: Return the number of key-value pairs in the mapping.

Methods

`get`(k[,d])
`items`()
`keys`()
`values`()

Initialize a new instance of ClassMap.

Methods

`get`(k[,d])
`items`()
`keys`()
`values`()

__init__()[source]#: Initialize a new instance of ClassMap.

class forensicfit.database.database.Database(name='forensicfit', host='localhost', port=27017, username='', password='', verbose=False, **kwargs)[source]#

Bases: object

Attributes:

collection_names: Get the names of the collections in the MongoDB database.
connected: Check if the Database instance is currently connected to the MongoDB database.
server_info: Get the server information for the MongoDB database.

Methods

`add_collection`(collection)	Add a new collection to the database.
`count_documents`(filter, collection)	Count the number of documents in the specified collection that match the provided filter.
`delete`(filter, collection)	Delete documents from the specified collection that match the provided filter.
`delete_database`()	Delete the MongoDB database associated with this Database instance.
`disconnect`()
`drop_collection`(collection)	Drop the specified collection from the MongoDB database.
`exists`([filter, collection, metadata])	Check if a document exists in the specified collection based on the provided filter or metadata.
`export_to_files`(destination, filter, collection)	Export objects from the specified collection that match the provided filter to files.
`filter_with_metadata`(inp, filter, collection)	Filter a list of filenames based on metadata and return the indices of the matching filenames.
`find`(filter[, collection, ext, version, ...])	Find and return objects from the specified collection that match the provided filter.
`find_one`([filter, collection])	Find and return one object from the specified collection that matches the provided filter.
`find_with_id`(_id, collection)	Find and return an object from the specified collection based on its MongoDB _id.
`insert`(obj[, ext, overwrite, skip, collection])	Insert an object into the specified collection in the MongoDB database.
`map_to`(func, filter, collection_source, ...)	Apply a function to each object in the source collection that matches the provided filter and insert the results into the target collection.

__init__(name='forensicfit', host='localhost', port=27017, username='', password='', verbose=False, **kwargs)[source]#

disconnect()[source]#

add_collection(collection)[source]#

Add a new collection to the database.

This method creates a new GridFS instance for the specified collection and adds it to the fs attribute.

Parameters:: collection (str) – The name of the collection to add.
Return type:: None

exists(filter=None, collection=None, metadata=None)[source]#

Check if a document exists in the specified collection based on the provided filter or metadata.

This method checks if a document exists in the specified collection of the MongoDB database that matches the provided filter or metadata. If a document is found, it returns the ObjectId of the document. If no document is found, it returns False.

Return type:

Union[ObjectId, bool]

Parameters:

filter (dict, optional) – A dictionary specifying the filter criteria to use when searching for the document.
collection (str, optional) – The name of the collection to search in. If not provided, the collection name is determined from the ‘mode’ field of the metadata.
metadata (Metadata, optional) – A Metadata object specifying the metadata to use when searching for the document. If provided, the ‘mode’ field of the metadata is used as the collection name and the metadata is converted to a MongoDB filter.

Returns:

The ObjectId of the found document if a matching document is found, False otherwise.

Return type:

ObjectId or bool

Raises:

Exception – If neither metadata nor filter and collection are provided.

insert(obj, ext='.png', overwrite=False, skip=False, collection=None)[source]#

Insert an object into the specified collection in the MongoDB database.

This method inserts an object into the specified collection of the MongoDB database. If the object already exists in the database, the behavior depends on the overwrite and skip parameters. If overwrite is True, the existing object is deleted and the new object is inserted. If skip is True, the insertion is skipped and the ObjectId of the existing object is returned. If neither overwrite nor skip is True and the object already exists, an exception is raised.

Return type:

ObjectId

Parameters:

obj (Union[Image, Tape, TapeAnalyzer]) – The object to insert into the database.
ext (str, optional) – The file extension to use when converting the object to a buffer, defaults to ‘.png’.
overwrite (bool, optional) – Whether to overwrite the existing object if it already exists, defaults to False.
skip (bool, optional) – Whether to skip the insertion if the object already exists, defaults to False.
collection (str, optional) – The name of the collection to insert the object into. If not provided, the collection name is determined from the ‘mode’ field of the object’s metadata.

Returns:

The ObjectId of the inserted object.

Return type:

ObjectId

Raises:

Exception – If the object already exists in the database and neither overwrite nor skip is True.

find(filter, collection='analysis', ext='.png', version=-1, no_cursor_timeout=False)[source]#

Find and return objects from the specified collection that match the provided filter.

This method finds and returns objects from the specified collection of the MongoDB database that match the provided filter. The objects are returned as instances of the class associated with the collection in the class mapping. The objects are sorted by their upload date in the order specified by the version parameter.

Return type:

list

Parameters:

filter (dict) – A dictionary specifying the filter criteria to use when searching for the objects.
collection (str, optional) – The name of the collection to search in, defaults to ‘analysis’.
ext (str, optional) – The file extension to use when converting the objects to buffers, defaults to ‘.png’.
version (int, optional) – The sort order for the objects based on their upload date. If version is -1, the objects are sorted in descending order. If version is 1, the objects are sorted in ascending order, defaults to -1.
no_cursor_timeout (bool, optional) – Whether to prevent the server-side cursor from timing out after an inactivity period, defaults to False.

Returns:

A list of objects from the specified collection that match the provided filter. The objects are returned as instances of the class associated with the collection in the class mapping.

Return type:

list

map_to(func, filter, collection_source, collection_target, verbose=True, no_cursor_timeout=False)[source]#

Apply a function to each object in the source collection that matches the provided filter and insert the results into the target collection.

This method applies a function to each object in the source collection of the MongoDB database that matches the provided filter. The results are inserted into the target collection. The objects are retrieved as instances of the class associated with the source collection in the class mapping.

Parameters:

func (Callable) – The function to apply to each object. The function should take an object as input and return an object.
filter (dict) – A dictionary specifying the filter criteria to use when searching for the objects in the source collection.
collection_source (str) – The name of the source collection to search in.
collection_target (str) – The name of the target collection to insert the results into.
verbose (bool, optional) – Whether to print the filename of each object being processed, defaults to True.
no_cursor_timeout (bool, optional) – Whether to prevent the server-side cursor from timing out after an inactivity period, defaults to False.

Return type:

None

find_one(filter=None, collection=None)[source]#

Find and return one object from the specified collection that matches the provided filter.

This method finds and returns one object from the specified collection of the MongoDB database that matches the provided filter. The object is returned as an instance of the class associated with the collection in the class mapping. If no collection is specified, one is chosen randomly.

Return type:

object

Parameters:

filter (dict, optional) – A dictionary specifying the filter criteria to use when searching for the object. If not provided, the first object in the collection is returned.
collection (str, optional) – The name of the collection to search in. If not provided, a collection is chosen randomly.

Returns:

An object from the specified collection that matches the provided filter. The object is returned as an instance of the class associated with the collection in the class mapping.

Return type:

object

Raises:

ValueError – If no object is found that matches the provided filter.

find_with_id(_id, collection)[source]#

Find and return an object from the specified collection based on its MongoDB _id.

This method finds and returns an object from the specified collection of the MongoDB database based on its MongoDB _id. The object is returned as an instance of the class associated with the collection in the class mapping.

Return type:

object

Parameters:

_id (str) – The MongoDB _id of the object to find.
collection (str) – The name of the collection to search in.

Returns:

An object from the specified collection with the provided MongoDB _id. The object is returned as an instance of the class associated with the collection in the class mapping.

Return type:

object

filter_with_metadata(inp, filter, collection)[source]#

Filter a list of filenames based on metadata and return the indices of the matching filenames.

This method filters a list of filenames based on the provided filter and the metadata of the files in the specified collection of the MongoDB database. It returns a list of indices of the input list that correspond to the filenames that match the filter.

Return type:

List[int]

Parameters:

inp (List[str]) – The list of filenames to filter.
filter (dict) – A dictionary specifying the filter criteria to use when filtering the filenames.
collection (str) – The name of the collection to search in.

Returns:

A list of indices of the input list that correspond to the filenames that match the filter.

Return type:

List[int]

count_documents(filter, collection)[source]#

Count the number of documents in the specified collection that match the provided filter.

This method counts the number of documents in the specified collection of the MongoDB database that match the provided filter. If the collection does not exist, it returns 0.

Return type:

int

Parameters:

filter (dict) – A dictionary specifying the filter criteria to use when counting the documents.
collection (str) – The name of the collection to count the documents in.

Returns:

The number of documents in the specified collection that match the provided filter.

Return type:

int

export_to_files(destination, filter, collection, ext='.png', verbose=True, no_cursor_timeout=False)[source]#

Export objects from the specified collection that match the provided filter to files.

This method exports objects from the specified collection of the MongoDB database that match the provided filter to files. The objects are saved as files in the specified destination directory. The objects are retrieved as instances of the class associated with the collection in the class mapping.

Parameters:

destination (str) – The path to the directory where the files should be saved.
filter (dict) – A dictionary specifying the filter criteria to use when searching for the objects.
collection (str) – The name of the collection to search in.
ext (str, optional) – The file extension to use when saving the objects, defaults to ‘.png’.
verbose (bool, optional) – Whether to print the path of each file being saved, defaults to True.
no_cursor_timeout (bool, optional) – Whether to prevent the server-side cursor from timing out after an inactivity period, defaults to False.

Return type:

None

drop_collection(collection)[source]#

Drop the specified collection from the MongoDB database.

This method drops the specified collection and its associated ‘files’ and ‘chunks’ collections from the MongoDB database.

Parameters:: collection (str) – The name of the collection to drop.
Return type:: None

delete(filter, collection)[source]#

Delete documents from the specified collection that match the provided filter.

This method deletes documents from the specified collection of the MongoDB database that match the provided filter.

Parameters:

filter (dict) – A dictionary specifying the filter criteria to use when deleting the documents.
collection (str) – The name of the collection to delete the documents from.

Return type:

None

delete_database()[source]#

Delete the MongoDB database associated with this Database instance.

This method deletes the MongoDB database that this Database instance is connected to.

Return type:: None

property collection_names: List[str]#

Get the names of the collections in the MongoDB database.

This method returns the names of the collections in the MongoDB database that this Database instance is connected to. The ‘.files’ suffix is removed from the collection names.

Returns:: A list of the names of the collections in the MongoDB database.
Return type:: List[str]

property connected: bool#

Check if the Database instance is currently connected to the MongoDB database.

This method checks if the Database instance is currently connected to the MongoDB database by attempting to retrieve the server information. If the server information is successfully retrieved, the method returns True. If a ServerSelectionTimeoutError occurs, the method prints the error and returns False.

Returns:: True if the Database instance is currently connected to the MongoDB database, False otherwise.
Return type:: bool

property server_info: dict#

Get the server information for the MongoDB database.

This method retrieves and returns the server information for the MongoDB database that this Database instance is connected to.

Returns:: A dictionary containing the server information for the MongoDB database.
Return type:: dict

forensicfit.database.database.dict2mongo_query(inp, previous_key='')[source]#

Convert a dictionary into a MongoDB query.

This function takes a dictionary and converts it into a MongoDB query. The keys of the dictionary are concatenated with the previous_key parameter to form the keys of the query. The values of the dictionary are used as the values of the query.

Return type:

dict

Parameters:

inp (dict) – The dictionary to convert into a MongoDB query.
previous_key (str, optional) – The key to prepend to the keys of the dictionary when forming the keys of the query, defaults to an empty string.

Returns:

The MongoDB query formed from the input dictionary.

Return type:

dict

forensicfit.database.database.list_databases(host='localhost', port=27017, username='', password='')[source]#

List the names of all databases on a MongoDB server.

This function connects to a MongoDB server using the provided host, port, username, and password, and returns a list of the names of all databases on the server.

Return type:

List[str]

Parameters:

host (str, optional) – The host IP address or hostname where the MongoDB server is running, defaults to ‘localhost’.
port (int, optional) – The port number to connect to the MongoDB server, defaults to 27017.
username (str, optional) – The username for authenticating with the MongoDB server, defaults to an empty string.
password (str, optional) – The password for authenticating with the MongoDB server, defaults to an empty string.

Returns:

A list of the names of all databases on the MongoDB server.

Return type:

List[str]

forensicfit.database.database.dump(db=None, host=None, port=None, username=None, password=None, out=None, collection=None)[source]#

Dump a MongoDB database or collection to a BSON file.

This function uses the mongodump command to dump a MongoDB database or collection to a BSON file. The mongodump command is a utility for creating a binary export of the contents of a database.

Parameters:

db (str, optional) – The name of the database to dump. If not provided, all databases are dumped.
host (str, optional) – The host IP address or hostname where the MongoDB server is running. If not provided, ‘localhost’ is used.
port (int, optional) – The port number to connect to the MongoDB server. If not provided, 27017 is used.
username (str, optional) – The username for authenticating with the MongoDB server. If not provided, no authentication is used.
password (str, optional) – The password for authenticating with the MongoDB server. If not provided, no authentication is used.
out (str, optional) – The directory where the dump should be output. If not provided, the dump is output to the ‘dump’ directory in the current working directory.
collection (str, optional) – The name of the collection to dump. If not provided, all collections in the specified database are dumped.

Return type:

None

forensicfit.database.database.restore(path=None, db=None, host=None, port=None, username=None, password=None, collection=None)[source]#

Restore a MongoDB database or collection from a BSON file.

This function uses the mongorestore command to restore a MongoDB database or collection from a BSON file. The mongorestore command is a utility for creating a binary import from the contents of a BSON file.

Parameters:

path (str, optional) – The path to the BSON file. If not provided, the ‘dump’ directory in the current working directory is used.
db (str, optional) – The name of the database to restore. If not provided, all databases are restored.
host (str, optional) – The host IP address or hostname where the MongoDB server is running. If not provided, ‘localhost’ is used.
port (int, optional) – The port number to connect to the MongoDB server. If not provided, 27017 is used.
username (str, optional) – The username for authenticating with the MongoDB server. If not provided, no authentication is used.
password (str, optional) – The password for authenticating with the MongoDB server. If not provided, no authentication is used.
collection (str, optional) – The name of the collection to restore. If not provided, all collections in the specified database are restored.

Return type:

None