API for Tags

The Tags Class

class digikamdb.tags.Tags(digikam)[source]

Bases: DigikamTable

Offers access to the tags in the Digikam instance.

Tags represents all tags present in the Digikam database. It is usually accessed through the Digikam property tags.

Basic usage:

dk = Digikam(...)
mytag = dk.tags['My Tag']           # access by name
mytag2 = dk.tags['parent/child']    # access by hierarchical name
mytag3 = dk.tags[42]                # access by id
newtag = dk.tags.add('New Tag', 0)  # creates new tag with name 'New Tag'

Access via [] raises an exception if the name or id cannot be found, or if there are multiple matches.

Parameters:

digikam (Digikam) – Digikam object for access to database and other classes.

Raises:

  • DigikamObjectNotFoundError – No matching tag was found.

  • DigikamMultipleObjectsFoundError – Multiple tags where found when one was expected.

See also

add(name, parent, icon=None)[source]

Adds a new tag.

To create a Tag at the root of the tag tree, set parent to 0. name can be a hierarchical name (e.g. “locations/cities/Amsterdam”), in which case the intermediate tags (“locations” and “cities” in the given example) are created too, without setting an icon if one is specified.

Parameters:

  • name (str) – The new tag’s name

  • parent (int | Tag) – The new tag’s parent as an id or a Tag object

  • icon (Image | str | int | None) – The new tag’s icon. If given as an Image, the icon is set to this Image from the Digikam collection. If given as an int, the icon is set to the image with the id icon. If given as a str, the icon is set to the corresponding KDE icon.

Returns:

The newly created tag object.

Return type:

Tag

check()[source]

Checks the integrity of the Tags table.

Checks that

  • each tag is among the children of its parent

  • each tag is contained in its ancestors

  • there are no circular parent-child relations

  • the nested sets and adjacency list structures are consistent (MySQL with DBVersion <= 10 only)

Raises:

DigikamDataIntegrityError – Table is in an inconsistent state.

Changed in version 0.2.2: Do not check nested sets for DBVersion > 10

remove(tag)[source]

Removes a tag.

Parameters:

tag (int | Tag) – the tag to delete. Can be a Tag object or an id.

setup()[source]

Sets the event listeners for nested sets.

Called by Digikam constructor.

The Tag Class (mapped)

class _sqla.Tag(**kwargs)

Bases: DigikamObject

Digikam tag.

Tags in Digikam are hierarchical. Tag reflects this by providing:

Note

The tree structure differs between SQLite and MySQL:

  • On SQLite, tags at the top level have a pid == 0, and there is no row with id == 0. There can be many tags without a parent tag.

  • On MySQL, there is a tag _Digikam_Root_Tag_ with id == 0 and pid == -1, and there is no tag with id == -1. All other tags are descendents of _Digikam_Root_Tag_.

  • On MySQL with DBVersion <= 10, the Tags table implements an additional nested sets structure with columns lft and rgt.

See also

hierarchicalname()

Returns the name including parents, separated by /.

Return type:

str

property children: Iterable[Tag]

Returns the tag’s children.

property icon: Image | str | None

Returns the tag’s icon.

Possible types are:

Image:

The icon is an image from the Digikam collection. When setting, you can also specify the image’s id.

Str:

The icon is a KDE icon string

None:

No icon is set

property id: int

The tag’s id (read-only)

property images: Iterable[Image]

Images belonging to the tag (no setter)

property name: str

The tag’s name

property parent: Tag | None

Returns the tag’s parent object.

Returns None for

  • the root tag on MySQL or

  • tags at top level on SQLite

property pid: int

The parent tag’s id (read-only)

property properties: TagProperties

Returns the tag’s properties

Tag Properties

class digikamdb.tags.TagProperties(parent)[source]

Bases: BasicProperties

Tag Properties

Parameters:

  • digikam (Digikam) – Digikam object.

  • parent (Tag) – The corresponding Tag object.