atomlite.Database

class atomlite.Database(database, molecule_table='molecules')

A molecular SQLite database.

Parameters:

• database (Path | str) – The path to the database file.

• molecule_table (LiteralString) – The name of the table which stores the molecules.

Attributes

connection

An open database connection.

Methods

add_entries	Add molecular entries to the database.
get_bool_property	Get a boolean property of a molecule.
get_entries	Get molecular entries from the database.
get_entry	Get a molecular entry from the database.
get_float_property	Get a float property of a molecule.
get_int_property	Get an integer property of a molecule.
get_property	Get the property of a molecule.
get_property_df	Get a DataFrame of the properties in the database.
get_property_entries	Get property entries from the database.
get_property_entry	Get a property entry from the database.
get_str_property	Get a string property of a molecule.
has_entry	Check if a molecular entry is present in the database.
has_property_entry	Check if a property entry is present in the database.
num_entries	Get the number of molecular entries in the database.
num_property_entries	Get the number of property entries in the database.
remove_entries	Remove molecular entries from the database.
remove_property	Remove a property from a molecule.
set_bool_property	Set a boolean property of a molecule.
set_float_property	Set a float property of a molecule.
set_int_property	Set an integer property of a molecule.
set_property	Set the property of a molecule.
set_str_property	Set a string property of a molecule.
update_entries	Update molecular entries in the database.
update_properties	Update property entries in the database.

add_entries(entries, *, commit=True)

Add molecular entries to the database.

Parameters:

• entries (Entry | list[Entry]) – The molecules to add to the database.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

get_bool_property(key, path)

Get a boolean property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) – A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

Returns:

The property. None will be returned if key is not present in the database or path leads to a non-existent property.

Raises:

TypeError – If the property is not a boolean.

Return type:

bool | None

get_entries(keys=None)

Get molecular entries from the database.

Tip

The molecules returned from the database are in JSON format, you may need to convert them to something more usable, for example, rdkit molecules with json_to_rdkit().

Parameters:

keys (str | list[str] | None) – The keys of the molecules to retrieve from the database. If None, all entries will be returned.

Yields:

A molecular entry matching keys.

Return type:

Iterator[Entry]

See also

• get_entry(): For retrieving a single entry.

get_entry(key)

Get a molecular entry from the database.

Tip

The molecules returned from the database are in JSON format, you may need to convert them to something more usable, for example, rdkit molecules with json_to_rdkit().

Parameters:

key (str) – The key of the molecule to retrieve from the database.

Returns:

The molecular entry matching key or None if key is not present in the database.

Return type:

Entry | None

See also

• get_entries(): For retrieving multiple entries.

get_float_property(key, path)

Get a float property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

Returns:

The property. None will be returned if key is not present in the database or path leads to a non-existent property.

Raises:

TypeError – If the property is not a float.

Return type:

float | None

get_int_property(key, path)

Get an integer property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

Returns:

The property. None will be returned if key is not present in the database or path leads to a non-existent property.

Raises:

TypeError – If the property is not an integer.

Return type:

int | None

get_property(key, path)

Get the property of a molecule.

Note

If path does not lead to a property which exists, None will be returned. This means that the same value is returned for a missing value as well as an exisiting value set to None. If you need to distinguish between missing and None values you can use a different value to represent missing data, for example the string "MISSING".

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

Returns:

The property. None will be returned if key is not present in the database or path leads to a non-existent property.

Return type:

Json

get_property_df(properties, *, allow_missing=False)

Get a DataFrame of the properties in the database.

Parameters:

• properties (Sequence[str]) –

  The paths of the properties to retrieve. Valid paths are described here. You can also view various code examples in our docs.

• allow_missing (bool) – If True, rows with some missing properties will be included in the DataFrame and hold null values.

Returns:

A DataFrame of the property entries in the database.

Return type:

DataFrame

get_property_entries(keys=None)

Get property entries from the database.

Parameters:

keys (str | list[str] | None) – The keys of the molecules to whose properties need to be retrieved from the database. If None all entries will be returned.

Yields:

A property entry matching keys.

Return type:

Iterator[PropertyEntry]

See also

• get_property_entry(): For retrieving a single entry.

get_property_entry(key)

Get a property entry from the database.

Parameters:

key (str) – The key of the molecule to retrieve from the database.

Returns:

The property entry matching key or None if key is not present in the database.

Return type:

PropertyEntry | None

See also

• get_property_entries(): For retrieving multiple entries.

get_str_property(key, path)

Get a string property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

Returns:

The property. None will be returned if key is not present in the database or path leads to a non-existent property.

Raises:

TypeError – If the property is not a string.

Return type:

str | None

has_entry(key)

Check if a molecular entry is present in the database.

Parameters:

key (str) – The key of the molecule to check.

Returns:

True if the entry is present in the database, False otherwise.

Return type:

bool

has_property_entry(key)

Check if a property entry is present in the database.

Parameters:

key (str) – The key of the molecule to check.

Returns:

True if the entry is present in the database, False otherwise.

Return type:

bool

num_entries()

Get the number of molecular entries in the database.

Note

This number includes both the commited and uncommited entries.

Return type:

int

num_property_entries()

Get the number of property entries in the database.

Note

This number includes both the commited and uncommited entries.

Return type:

int

remove_entries(keys, *, commit=True)

Remove molecular entries from the database.

Parameters:

• keys (str | Iterable[str]) – The keys of the molecules to remove from the database.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

remove_property(key, path, *, commit=True)

Remove a property from a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

set_bool_property(key, path, property, *, commit=True)

Set a boolean property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

• property (bool) – The desired value of the property.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

set_float_property(key, path, property, *, commit=True)

Set a float property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

• property (float) – The desired value of the property.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

set_int_property(key, path, property, *, commit=True)

Set an integer property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

• property (int) – The desired value of the property.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

set_property(key, path, property, *, commit=True)

Set the property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

• property (float | str | bool | None) – The desired value of the property.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

set_str_property(key, path, property, *, commit=True)

Set a string property of a molecule.

Parameters:

• key (str) – The key of the molecule.

• path (str) –

  A path to the property of the molecule. Valid paths are described here. You can also view various code examples in our docs.

• property (str) – The desired value of the property.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

update_entries(entries, *, merge_properties=True, upsert=True, commit=True)

Update molecular entries in the database.

Parameters:

• entries (Entry | list[Entry]) – The molecule entries to update in the database.

• merge_properties (bool) – If True, the molecular properties will be merged rather than replaced. Properties present in both the update and the database will be overwritten.

• upsert (bool) – If True, entries will be added to the database if missing.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

update_properties(entries, *, merge_properties=True, commit=True)

Update property entries in the database.

Parameters:

• entries (PropertyEntry | list[PropertyEntry]) – The entries to update in the database.

• merge_properties (bool) – If True, the molecular properties will be merged rather than replaced. Properties present in both the update and the database will be overwritten.

• commit (bool) – If True changes will be automatically commited to the database file.

Return type:

None

connection: Connection

An open database connection.

Can be used to run SQL commands against the database.