API: Connection and Base Classes¶

The Digikam Class¶

class digikamdb.conn.Digikam(database, root_override=None, sql_echo=False)[source]¶

Connection to the Digikam database.

This object connects to the Digikam database using the SQLAlchemy ORM. It generates its own set of classes so that you can use multiple Digikam objects to connect to different databases.

When initializing a Digikam object, you have to supply parameters to specify the database. This is usually done with the database parameter. It can be one of the following:

The string “digikamrc”:: Use the local Digikam application’s database configuration in $HOME/.config/digikamrc.
Any other str:: Use the string as database URL in create_engine().
A SQLAlchemy Engine object:: Use this object as the database engine

Access to actual data is mostly done through the following properties:

images (class Images)
tags (class Tags)
albums (class Albums)
albumroots (class AlbumRoots)
settings (class Settings)

Parameters:

database (str | Engine) – Digikam database.
sql_echo (bool) – Sets the echo option of SQLAlchemy.
root_override (Mapping | None) – Can be used to override the location of album roots in the file system. See `Root Overrides`_ for more information.

classmethod db_from_config(sql_echo=False)[source]¶

Creates the database connection from digikamrc.

Returns:: Database connection object
Raises:: DigikamConfigError – ~/.config/digikamrc cannot be read or interpreted.
Return type:: Engine

destroy()[source]¶

Clears the object.

This will call close() and dispose() for the session and engine objects.

property albumRoots: AlbumRoots¶: The AlbumRoots object

property albums: Albums¶: The Albums object

property base: type¶: Base class for table-mapped classes

property db_version: int¶: The Digikam database version

Added in version 0.2.2.

property has_tags_nested_sets: bool¶: Indicates if the Tags table has nested sets

Added in version 0.2.2.

property images: Images¶: The Images object

property is_mysql: bool¶: True if database is MySQL

property session: Session¶: The SQLAlchemy ORM session

property settings: Settings¶: The Settings object

property tags: Tags¶: The Tags object

Base Class for Mapped Tables¶

class _sqla.DigikamObject(**kwargs)¶

Abstract base class for objects stored in database. Derived from DeferredReflection and declarative_base().

Parameters:: kwargs (Any)

property digikam: Digikam¶: The Digikam object

Digikam Table¶

class digikamdb.table.DigikamTable(digikam, log_create=True)[source]¶

An abstract base class for table classes

Provides some low-level methods for accessing data:

Members can be accessed by id via object[id].
Class is iterable, returning all rows of the table.
Some internal functionality

Parameters:

digikam (Digikam) – The “parent” Digikam object
log_create (bool) – Used internally to control logging

select(*args, **kwargs)[source]¶

Returns the result of a SELECT on the table.

Each positional argument must be a string containing a valid WHERE clause (without WHERE). These clauses are combined with AND. Keyword arguments are used as additional WHERE clauses checking for equality. For example, select('a > 2', b = 1) will result in a SELECT ... WHERE a>2 AND b=1 SQL statement.

The result is a Query object that can be refined further. When adding additional conditions, the column names must be prefixed with _.

The results can be accessed by iterating over the query or through methods like all() or one_or_none().

Parameters:

args – WHERE clauses as text
kwargs – Columns to check for equality

Returns:

The resulting Query object.

Return type:

Query

Basic Properties¶

class digikamdb.properties.BasicProperties(parent)[source]¶

Basic class for properties

Instances of this class belong to a Digikam object that has a property (e.g. properties) that points to the BasicProperties instance. The individual properties can be accessed similarly to dict values:

obj.properties['myprop'] = 'myvalue'        # set a property
if 'myprop' in obj.properties:              # check if a property exists
    opj.properties.remove('myprop')         # remove a property

The class is iterable, yielding all property names, and has a method items() similar to that of dict.

The number of properties can be found with len(obj.properties)

Parameters:: parent (DigikamObject) – Object the properties belong to.

get(prop, default=None)[source]¶

Works similar to dict.get().

Parameters:

prop (str | int | Sequence)
default (Any | None)

Return type:

str

items()[source]¶

Returns the properties as an iterable yielding (key, value) tuples.

Return type:: Iterable[Tuple]

remove(prop)[source]¶

Removes the given property.

Parameters:: prop (str | int | Iterable | None) – Property to remove.

update(values=None, **kwargs)[source]¶

Updates multiple properties.

This method behaves like dict.update().

Parameters:

values (Mapping | None) – dict with new values
kwargs – Mapping for new values

property parent: DigikamObject¶: Returns the parent object.

Digikam Settings¶

class digikamdb.settings.Settings(digikam)[source]¶

Digikam settings class

The Digikam settings can be accessed like a dict:

dk = digikamdb.Digikam()
if 'DBVersion' in dk.settings:
    db_version = dk.settings['DBVersion']           # Get DB version
dk.settings['databaseUserImageFormats'] = '-xcf'    # Exclude GIMP files
for k in dk.settings:                               # Iterate over settings
    print(k, '=', dk.settings[k])
for k, v in dk.settings.items():                    # Iterate over settings
    print(k, '=', v)