kdbxtool.models.entry¶

Entry model for KDBX password entries.

Classes

`AutoType`([enabled, sequence, window, ...])	AutoType settings for an entry.
`BinaryRef`(key, ref)	Reference to a binary attachment.
`Entry`([uuid, times, icon_id, ...])	A password entry in a KDBX database.
`HistoryEntry`([uuid, times, icon_id, ...])	A historical version of an entry.
`StringField`(key[, value, protected])	A string field in an entry.

class kdbxtool.models.entry.StringField(key, value=None, protected=False)[source]¶

Bases: object

A string field in an entry.

Parameters:

key (str)
value (str | None)
protected (bool)

key¶

Field name (e.g., “Title”, “UserName”, “Password”)

Type:: str

value¶

Field value

Type:: str | None

protected¶

Whether the field should be protected in memory

Type:: bool

key: str¶

value: str | None = None¶

protected: bool = False¶

__init__(key, value=None, protected=False)¶

Parameters:

key (str)
value (str | None)
protected (bool)

Return type:

None

class kdbxtool.models.entry.AutoType(enabled=True, sequence=None, window=None, obfuscation=0)[source]¶

Bases: object

AutoType settings for an entry.

Parameters:

enabled (bool)
sequence (str | None)
window (str | None)
obfuscation (int)

enabled¶

Whether AutoType is enabled for this entry

Type:: bool

sequence¶

Default keystroke sequence

Type:: str | None

window¶

Window filter for AutoType

Type:: str | None

obfuscation¶

Data transfer obfuscation level (0 = none)

Type:: int

enabled: bool = True¶

sequence: str | None = None¶

window: str | None = None¶

obfuscation: int = 0¶

__init__(enabled=True, sequence=None, window=None, obfuscation=0)¶

Parameters:

enabled (bool)
sequence (str | None)
window (str | None)
obfuscation (int)

Return type:

None

class kdbxtool.models.entry.BinaryRef(key, ref)[source]¶

Bases: object

Reference to a binary attachment.

Parameters:

key (str)
ref (int)

key¶

Filename of the attachment

Type:: str

ref¶

Reference ID to the binary in the database

Type:: int

key: str¶

ref: int¶

__init__(key, ref)¶

Parameters:

key (str)
ref (int)

Return type:

None

class kdbxtool.models.entry.Entry(uuid=<factory>, times=<factory>, icon_id='0', custom_icon_uuid=None, tags=<factory>, strings=<factory>, binaries=<factory>, autotype=<factory>, history=<factory>, foreground_color=None, background_color=None, override_url=None, quality_check=True, _parent=None, _database=None)[source]¶

Bases: object

A password entry in a KDBX database.

Entries store credentials and associated metadata. Each entry has standard fields (title, username, password, url, notes) plus support for custom string fields and binary attachments.

Parameters:

uuid (uuid_module.UUID)
times (Times)
icon_id (str)
custom_icon_uuid (uuid_module.UUID | None)
tags (list[str])
strings (dict[str, StringField])
binaries (list[BinaryRef])
autotype (AutoType)
history (list[HistoryEntry])
foreground_color (str | None)
background_color (str | None)
override_url (str | None)
quality_check (bool)
_parent (Group | None)
_database (Database | None)

uuid¶

Unique identifier for the entry

Type:: uuid_module.UUID

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

tags¶

List of tags for categorization

Type:: list[str]

strings¶

Dictionary of string fields (key -> StringField)

Type:: dict[str, StringField]

binaries¶

List of binary attachment references

Type:: list[BinaryRef]

autotype¶

AutoType settings

Type:: AutoType

history¶

List of previous versions of this entry

Type:: list[HistoryEntry]

foreground_color¶

Custom foreground color (hex)

Type:: str | None

background_color¶

Custom background color (hex)

Type:: str | None

override_url¶

URL override for AutoType

Type:: str | None

quality_check¶

Whether to check password quality

Type:: bool

uuid: uuid_module.UUID¶

times: Times¶

icon_id: str = '0'¶

custom_icon_uuid: uuid_module.UUID | None = None¶

tags: list[str]¶

strings: dict[str, StringField]¶

binaries: list[BinaryRef]¶

autotype: AutoType¶

history: list[HistoryEntry]¶

foreground_color: str | None = None¶

background_color: str | None = None¶

override_url: str | None = None¶

quality_check: bool = True¶

property title: str | None¶: Get or set entry title.

property username: str | None¶: Get or set entry username.

property password: str | None¶: Get or set entry password.

property url: str | None¶: Get or set entry URL.

property notes: str | None¶: Get or set entry notes.

property otp: str | None¶: Get or set OTP secret (TOTP/HOTP).

totp(*, at=None)[source]¶

Generate current TOTP code from the entry’s otp field.

Supports both standard otpauth:// URIs and KeePassXC legacy format (TOTP Seed / TOTP Settings custom fields).

Parameters:: at (datetime | float | None) – Optional timestamp for code generation. Can be a datetime or Unix timestamp float. Defaults to current time.
Returns:: TotpCode object with code and expiration info, or None if no OTP configured.
Raises:: ValueError – If OTP configuration is invalid
Return type:: TotpCode | None

Example

>>> result = entry.totp()
>>> print(f"Code: {result.code}")
Code: 123456

>>> print(f"Expires in {result.remaining}s")
Expires in 15s

>>> # TotpCode also works as a string
>>> print(result)
123456

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 entry to be associated with a database for name-based lookup.

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

get_custom_property(key)[source]¶

Get a custom property value.

Parameters:: key (str) – Property name (must not be a reserved key)
Returns:: Property value, or None if not set
Raises:: ValueError – If key is a reserved key
Return type:: str | None

set_custom_property(key, value, protected=False)[source]¶

Set a custom property.

Parameters:

key (str) – Property name (must not be a reserved key)
value (str) – Property value
protected (bool) – Whether to mark as protected in memory

Raises:

ValueError – If key is a reserved key

Return type:

None

delete_custom_property(key)[source]¶

Delete a custom property.

Parameters:

key (str) – Property name to delete

Raises:

ValueError – If key is a reserved key
KeyError – If property doesn’t exist

Return type:

None

property custom_properties: dict[str, str | None]¶: Get all custom properties as a dictionary.

property parent: Group | None¶: Get parent group.

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

property index: int¶

Get the index of this entry within its parent group.

Returns:: Zero-based index of this entry in the parent’s entries list.
Raises:: ValueError – If entry has no parent group.

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

touch(modify=False)[source]¶

Update access time, optionally modification time.

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

reindex(new_index)[source]¶

Move this entry 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 entry has no parent group.
IndexError – If new_index is out of range.

Return type:

None

save_history()[source]¶

Save current state to history before making changes.

Return type:: None

delete_history(history_entry=None, *, all=False)[source]¶

Delete history entries.

Either deletes a specific history entry or all history entries. At least one of history_entry or all=True must be specified.

Parameters:

history_entry (HistoryEntry | None) – Specific history entry to delete
all (bool) – If True, delete all history entries

Raises:

ValueError – If neither history_entry nor all=True is specified
ValueError – If history_entry is not in this entry’s history

Return type:

None

clear_history()[source]¶

Clear all history entries.

This is a convenience method equivalent to delete_history(all=True).

Return type:: None

move_to(destination)[source]¶

Move this entry to a different group.

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

Parameters:

destination (Group) – Target group to move the entry to

Raises:

ValueError – If entry has no parent (not yet added to a group)
ValueError – If destination is the current parent (no-op would be confusing)

Return type:

None

ref(field)[source]¶

Create a reference string pointing to a field of this entry.

Creates a KeePass field reference string that can be used in other entries to reference values from this entry. References use the entry’s UUID for lookup.

Parameters:: field (str) – One of ‘title’, ‘username’, ‘password’, ‘url’, ‘notes’, or ‘uuid’
Returns:: X@I:UUID}
Return type:: Field reference string in format {REF
Raises:: ValueError – If field is not a valid field name

Example

>>> main_entry = db.find_entries(title='Main Account', first=True)
>>> ref_string = main_entry.ref('password')
>>> # Returns '{REF:P@I:...UUID...}'
>>> other_entry.password = ref_string

deref(field)[source]¶

Resolve any field references in the given field’s value.

If the field’s value contains KeePass field references ({REF:X@Y:Z}), resolves them to the actual values from the referenced entries.

Parameters:: field (str) – One of ‘title’, ‘username’, ‘password’, ‘url’, ‘notes’
Returns:: The resolved value with all references replaced, a UUID if the referenced field is ‘uuid’, or None if a referenced entry is not found
Raises:: ValueError – If no database reference is available
Return type:: str | UUID | None

Example

>>> # If entry.password contains '{REF:P@I:...UUID...}'
>>> actual_password = entry.deref('password')

dump()[source]¶

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

Returns:: Multi-line string with entry details (passwords are masked).
Return type:: str

__init__(uuid=<factory>, times=<factory>, icon_id='0', custom_icon_uuid=None, tags=<factory>, strings=<factory>, binaries=<factory>, autotype=<factory>, history=<factory>, foreground_color=None, background_color=None, override_url=None, quality_check=True, _parent=None, _database=None)¶

Parameters:

uuid (uuid_module.UUID)
times (Times)
icon_id (str)
custom_icon_uuid (uuid_module.UUID | None)
tags (list[str])
strings (dict[str, StringField])
binaries (list[BinaryRef])
autotype (AutoType)
history (list[HistoryEntry])
foreground_color (str | None)
background_color (str | None)
override_url (str | None)
quality_check (bool)
_parent (Group | None)
_database (Database | None)

Return type:

None

classmethod create(title=None, username=None, password=None, url=None, notes=None, tags=None, icon_id='0', expires=False, expiry_time=None)[source]¶

Create a new entry with common fields.

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) – List of tags
icon_id (str) – Icon ID
expires (bool) – Whether entry expires
expiry_time (datetime | None) – Expiration time

Returns:

New Entry instance

Return type:

Entry

class kdbxtool.models.entry.HistoryEntry(uuid=<factory>, times=<factory>, icon_id='0', custom_icon_uuid=None, tags=<factory>, strings=<factory>, binaries=<factory>, autotype=<factory>, history=<factory>, foreground_color=None, background_color=None, override_url=None, quality_check=True, _parent=None, _database=None)[source]¶

Bases: Entry

A historical version of an entry.

History entries are snapshots of an entry at a previous point in time. They share the same UUID as their parent entry.

Parameters:

uuid (uuid_module.UUID)
times (Times)
icon_id (str)
custom_icon_uuid (uuid_module.UUID | None)
tags (list[str])
strings (dict[str, StringField])
binaries (list[BinaryRef])
autotype (AutoType)
history (list[HistoryEntry])
foreground_color (str | None)
background_color (str | None)
override_url (str | None)
quality_check (bool)
_parent (Group | None)
_database (Database | None)

Parameters:

uuid (uuid_module.UUID)
times (Times)
icon_id (str)
custom_icon_uuid (uuid_module.UUID | None)
tags (list[str])
strings (dict[str, StringField])
binaries (list[BinaryRef])
autotype (AutoType)
history (list[HistoryEntry])
foreground_color (str | None)
background_color (str | None)
override_url (str | None)
quality_check (bool)
_parent (Group | None)
_database (Database | None)

Return type:

None

classmethod from_entry(entry)[source]¶

Create a history entry from an existing entry.

Parameters:: entry (Entry) – Entry to create history from
Returns:: New HistoryEntry with copied data
Return type:: HistoryEntry