kdbxtool.models.group¶

Group model for KDBX database folders.

Classes

Group([uuid, name, notes, times, icon_id, ...])

A group (folder) in a KDBX database.

class kdbxtool.models.group.Group(uuid=<factory>, name=None, notes=None, times=<factory>, icon_id='48', custom_icon_uuid=None, is_expanded=True, default_autotype_sequence=None, enable_autotype=None, enable_searching=None, last_top_visible_entry=None, entries=<factory>, subgroups=<factory>, _parent=None, _is_root=False, _database=None)[source]¶

Bases: object

A group (folder) in a KDBX database.

Groups organize entries into a hierarchical structure. Each group can contain entries and subgroups.

Parameters:

uuid (uuid_module.UUID)
name (str | None)
notes (str | None)
times (Times)
icon_id (str)
custom_icon_uuid (uuid_module.UUID | None)
is_expanded (bool)
default_autotype_sequence (str | None)
enable_autotype (bool | None)
enable_searching (bool | None)
last_top_visible_entry (uuid_module.UUID | None)
entries (list[Entry])
subgroups (list[Group])
_parent (Group | None)
_is_root (bool)
_database (Database | None)

uuid¶

Unique identifier for the group

Type:: uuid_module.UUID

name¶

Display name of the group

Type:: str | None

notes¶

Optional notes/description

Type:: str | None

times¶

Timestamps (creation, modification, access, expiry)

Type:: Times

icon_id¶

Icon ID for display (standard icon)

Type:: str

custom_icon_uuid¶

UUID of custom icon (overrides icon_id if set)

Type:: uuid_module.UUID | None

is_expanded¶

Whether group is expanded in UI

Type:: bool

default_autotype_sequence¶

Default AutoType sequence for entries

Type:: str | None

enable_autotype¶

Whether AutoType is enabled for this group

Type:: bool | None

enable_searching¶

Whether entries in this group are searchable

Type:: bool | None

last_top_visible_entry¶

UUID of last visible entry (UI state)

Type:: uuid_module.UUID | None

entries¶

List of entries in this group

Type:: list[Entry]

subgroups¶

List of subgroups

Type:: list[Group]

uuid: uuid_module.UUID¶

name: str | None = None¶

notes: str | None = None¶

times: Times¶

icon_id: str = '48'¶

custom_icon_uuid: uuid_module.UUID | None = None¶

is_expanded: bool = True¶

default_autotype_sequence: str | None = None¶

enable_autotype: bool | None = None¶

enable_searching: bool | None = None¶

last_top_visible_entry: uuid_module.UUID | None = None¶

entries: list[Entry]¶

subgroups: list[Group]¶

property parent: Group | None¶: Get parent group, or None if this is the root.

property database: Database | None¶: Get the database this group belongs to.

property is_root_group: bool¶: Check if this is the database root group.

property index: int¶

Get the index of this group within its parent group.

Returns:: Zero-based index of this group in the parent’s subgroups list.
Raises:: ValueError – If group has no parent (is root group).

property path: list[str]¶

Get path from root to this group.

Returns:: List of group names from root (exclusive) to this group (inclusive). Empty list for the root group.

property expired: bool¶: Check if group has expired.

property custom_icon: UUID | None¶

Get or set custom icon by UUID or name.

When setting, accepts either a UUID or an icon name (string). If a string is provided, it must match exactly one icon name in the database. Requires the group to be associated with a database for name-based lookup.

Returns:: UUID of the custom icon, or None if not set

touch(modify=False)[source]¶

Update access time, optionally modification time.

Parameters:: modify (bool)
Return type:: None

reindex(new_index)[source]¶

Move this group to a new position within its parent group.

Parameters:

new_index (int) – Target position (zero-based). Negative indices are supported (e.g., -1 for last position).

Raises:

ValueError – If group has no parent (is root group).
IndexError – If new_index is out of range.

Return type:

None

add_entry(entry)[source]¶

Add an entry to this group.

Parameters:: entry (Entry) – Entry to add
Returns:: The added entry
Return type:: Entry

remove_entry(entry)[source]¶

Remove an entry from this group.

Parameters:: entry (Entry) – Entry to remove
Raises:: ValueError – If entry is not in this group
Return type:: None

create_entry(title=None, username=None, password=None, url=None, notes=None, tags=None, *, template=None)[source]¶

Create and add a new entry to this group.

Parameters:

title (str | None) – Entry title
username (str | None) – Username
password (str | None) – Password
url (str | None) – URL
notes (str | None) – Notes
tags (list[str] | None) – Tags
template (EntryTemplate | None) – Optional entry template instance with field values

Returns:

Newly created entry

Return type:

Entry

Example

>>> # Standard entry (no template)
>>> entry = group.create_entry(title="Site", username="user", password="pass")

>>> # Using a template with typed fields
>>> from kdbxtool import Templates
>>> entry = group.create_entry(
...     title="My Visa",
...     template=Templates.CreditCard(
...         card_number="4111111111111111",
...         expiry_date="12/25",
...         cvv="123",
...     ),
... )

>>> # Server template with standard fields
>>> entry = group.create_entry(
...     title="prod-server",
...     username="admin",
...     password="secret",
...     template=Templates.Server(
...         hostname="192.168.1.1",
...         port="22",
...     ),
... )

add_subgroup(group)[source]¶

Add a subgroup to this group.

Parameters:: group (Group) – Group to add
Returns:: The added group
Return type:: Group

remove_subgroup(group)[source]¶

Remove a subgroup from this group.

Parameters:: group (Group) – Group to remove
Raises:: ValueError – If group is not a subgroup of this group
Return type:: None

create_subgroup(name, notes=None, icon_id='48')[source]¶

Create and add a new subgroup.

Parameters:

name (str) – Group name
notes (str | None) – Optional notes
icon_id (str) – Icon ID

Returns:

Newly created group

Return type:

Group

move_to(destination)[source]¶

Move this group to a different parent group.

Removes the group from its current parent and adds it to the destination group. Updates the location_changed timestamp.

Parameters:

destination (Group) – Target parent group to move this group to

Raises:

ValueError – If this is the root group (cannot be moved)
ValueError – If group has no parent (not yet added to a database)
ValueError – If destination is the current parent
ValueError – If destination is this group (cannot move into self)
ValueError – If destination is a descendant of this group (would create cycle)

Return type:

None

iter_entries(recursive=True, history=False)[source]¶

Iterate over entries in this group.

Parameters:

recursive (bool) – If True, include entries from all subgroups
history (bool) – If True, include history entries

Yields:

Entry objects

Return type:

Iterator[Entry]

iter_groups(recursive=True)[source]¶

Iterate over subgroups.

Parameters:: recursive (bool) – If True, include nested subgroups
Yields:: Group objects
Return type:: Iterator[Group]

find_entry_by_uuid(uuid, recursive=True)[source]¶

Find an entry by UUID.

Parameters:

uuid (UUID) – Entry UUID to find
recursive (bool) – Search in subgroups

Returns:

Entry if found, None otherwise

Return type:

Entry | None

find_group_by_uuid(uuid, recursive=True)[source]¶

Find a group by UUID.

Parameters:

uuid (UUID) – Group UUID to find
recursive (bool) – Search in nested subgroups

Returns:

Group if found, None otherwise

Return type:

Group | None

find_entries(title=None, username=None, password=None, url=None, notes=None, otp=None, tags=None, string=None, autotype_enabled=None, autotype_sequence=None, autotype_window=None, recursive=True, history=False)[source]¶

Find entries matching criteria.

All criteria are combined with AND logic. None means “any value”.

Parameters:

title (str | None) – Match entries with this title (exact)
username (str | None) – Match entries with this username (exact)
password (str | None) – Match entries with this password (exact)
url (str | None) – Match entries with this URL (exact)
notes (str | None) – Match entries with these notes (exact)
otp (str | None) – Match entries with this OTP (exact)
tags (list[str] | None) – Match entries containing all these tags
string (dict[str, str] | None) – Match entries with custom properties (dict of key:value)
autotype_enabled (bool | None) – Filter by AutoType enabled state
autotype_sequence (str | None) – Match entries with this AutoType sequence (exact)
autotype_window (str | None) – Match entries with this AutoType window (exact)
recursive (bool) – Search in subgroups
history (bool) – Include history entries in search

Returns:

List of matching entries

Return type:

list[Entry]

find_entries_contains(title=None, username=None, password=None, url=None, notes=None, otp=None, recursive=True, case_sensitive=False, history=False)[source]¶

Find entries where fields contain the given substrings.

All criteria are combined with AND logic. None means “any value”.

Parameters:

title (str | None) – Match entries whose title contains this substring
username (str | None) – Match entries whose username contains this substring
password (str | None) – Match entries whose password contains this substring
url (str | None) – Match entries whose URL contains this substring
notes (str | None) – Match entries whose notes contain this substring
otp (str | None) – Match entries whose OTP contains this substring
recursive (bool) – Search in subgroups
case_sensitive (bool) – If False (default), matching is case-insensitive
history (bool) – Include history entries in search

Returns:

List of matching entries

Return type:

list[Entry]

find_entries_regex(title=None, username=None, password=None, url=None, notes=None, otp=None, recursive=True, case_sensitive=False, history=False)[source]¶

Find entries where fields match the given regex patterns.

All criteria are combined with AND logic. None means “any value”.

Parameters:

title (str | None) – Regex pattern to match against title
username (str | None) – Regex pattern to match against username
password (str | None) – Regex pattern to match against password
url (str | None) – Regex pattern to match against URL
notes (str | None) – Regex pattern to match against notes
otp (str | None) – Regex pattern to match against OTP
recursive (bool) – Search in subgroups
case_sensitive (bool) – If False (default), matching is case-insensitive
history (bool) – Include history entries in search

Returns:

List of matching entries

Raises:

re.error – If any pattern is not a valid regex

Return type:

list[Entry]

find_groups(name=None, recursive=True, first=False)[source]¶

Find groups matching criteria.

Parameters:

name (str | None) – Match groups with this name (exact)
recursive (bool) – Search in nested subgroups
first (bool) – If True, return first matching group or None instead of list

Returns:

List of matching groups, or single Group/None if first=True

Return type:

list[Group] | Group | None

dump(recursive=False)[source]¶

Return a human-readable summary of the group for debugging.

Parameters:: recursive (bool) – If True, include subgroups and entries recursively
Returns:: Multi-line string with group details.
Return type:: str

__init__(uuid=<factory>, name=None, notes=None, times=<factory>, icon_id='48', custom_icon_uuid=None, is_expanded=True, default_autotype_sequence=None, enable_autotype=None, enable_searching=None, last_top_visible_entry=None, entries=<factory>, subgroups=<factory>, _parent=None, _is_root=False, _database=None)¶

Parameters:

uuid (uuid_module.UUID)
name (str | None)
notes (str | None)
times (Times)
icon_id (str)
custom_icon_uuid (uuid_module.UUID | None)
is_expanded (bool)
default_autotype_sequence (str | None)
enable_autotype (bool | None)
enable_searching (bool | None)
last_top_visible_entry (uuid_module.UUID | None)
entries (list[Entry])
subgroups (list[Group])
_parent (Group | None)
_is_root (bool)
_database (Database | None)

Return type:

None

classmethod create_root(name='Root')[source]¶

Create a root group for a new database.

Parameters:: name (str) – Name for the root group
Returns:: New root Group instance
Return type:: Group