tessl/pypi-pykeepass
Python library to interact with keepass databases (supports KDBX3 and KDBX4)
—
Pending
database-operations.mddocs/
Database Operations
Core functionality for creating, opening, saving, and managing KeePass database files with support for various authentication methods and database formats.
Capabilities
Database Creation
Creates a new KeePass database file with specified authentication credentials.
def create_database(filename, password=None, keyfile=None, transformed_key=None) -> PyKeePass:
"""
Create a new KeePass database.
Parameters:
- filename (str): Path where the new database file will be saved
- password (str, optional): Master password for the database
- keyfile (str, optional): Path to keyfile for authentication
- transformed_key (bytes, optional): Pre-computed transformed key
Returns:
PyKeePass: New database instance ready for use
Raises:
BinaryError: If there's an issue creating the database structure
"""Usage Example:
from pykeepass import create_database
# Create with password only
kp = create_database('my_passwords.kdbx', password='supersecret')
# Create with keyfile only
kp = create_database('my_passwords.kdbx', keyfile='my_keyfile.key')
# Create with both password and keyfile
kp = create_database('my_passwords.kdbx', password='secret', keyfile='keyfile.key')Database Opening and Reading
Opens existing KeePass database files with various authentication methods.
class PyKeePass:
def __init__(filename, password=None, keyfile=None, transformed_key=None):
"""
Open a KeePass database.
Parameters:
- filename (str): Path to the KeePass database file
- password (str, optional): Master password for the database
- keyfile (str, optional): Path to keyfile for authentication
- transformed_key (bytes, optional): Pre-computed transformed key for faster opening
Raises:
CredentialsError: Wrong password/keyfile or transformed key
PayloadChecksumError: Payload block checksum error (corruption)
HeaderChecksumError: Header checksum error (tampering/corruption)
"""
def read(filename=None, password=None, keyfile=None, transformed_key=None):
"""
Read/reload database from file.
Parameters:
- filename (str, optional): Path to database file (uses current if None)
- password (str, optional): Master password
- keyfile (str, optional): Path to keyfile
- transformed_key (bytes, optional): Pre-computed transformed key
Raises:
CredentialsError: Authentication failed
PayloadChecksumError: Database corruption detected
HeaderChecksumError: Database tampering detected
"""Usage Examples:
from pykeepass import PyKeePass
# Open with password
kp = PyKeePass('database.kdbx', password='mypassword')
# Open with keyfile
kp = PyKeePass('database.kdbx', keyfile='my_keyfile.key')
# Open with both password and keyfile
kp = PyKeePass('database.kdbx', password='secret', keyfile='keyfile.key')
# Reload database (useful after external changes)
kp.read()
# Read from different file
kp.read('backup_database.kdbx', password='mypassword')Database Saving
Saves the current database state to disk with optional filename and transformed key optimization.
def save(filename=None, transformed_key=None):
"""
Save database to disk.
Parameters:
- filename (str, optional): Path to save database (uses current filename if None)
- transformed_key (bytes, optional): Pre-computed transformed key for optimization
Raises:
BinaryError: If there's an issue writing the database
"""Usage Examples:
# Save to current filename
kp.save()
# Save to new filename
kp.save('backup_database.kdbx')
# Save with transformed key for performance
kp.save(transformed_key=kp.transformed_key)Database Properties and Metadata
Access database version information, encryption settings, and internal structure.
class PyKeePass:
@property
def version() -> tuple:
"""Database version as (major, minor) tuple, e.g., (3, 1) or (4, 0)"""
@property
def encryption_algorithm() -> str:
"""Encryption algorithm: 'aes256', 'chacha20', or 'twofish'"""
@property
def kdf_algorithm() -> str:
"""Key derivation algorithm: 'aeskdf' or 'argon2'"""
@property
def transformed_key() -> bytes:
"""Transformed key for faster database opening"""
@property
def tree() -> lxml.etree._ElementTree:
"""Database XML payload"""
@property
def root_group() -> Group:
"""Root group of the database"""
@property
def groups() -> list:
"""All groups in database"""
@property
def entries() -> list:
"""All entries in database (excluding history)"""
@property
def attachments() -> list:
"""All attachments in database"""
@property
def binaries() -> list:
"""Binary data storage"""Usage Examples:
# Check database version and encryption
print(f"Database version: {kp.version}")
print(f"Encryption: {kp.encryption_algorithm}")
print(f"Key derivation: {kp.kdf_algorithm}")
# Access database structure
root = kp.root_group
all_groups = kp.groups
all_entries = kp.entries
# Store transformed key for faster subsequent opens
transformed_key = kp.transformed_key
# Use this key later: PyKeePass('db.kdbx', transformed_key=transformed_key)Database Export and XML Operations
Export database content to XML format for analysis or backup purposes.
def xml() -> str:
"""
Get XML payload as string.
Returns:
str: Complete database XML content
"""
def dump_xml(filename):
"""
Export database XML to file.
Parameters:
- filename (str): Path where XML file will be saved
"""Usage Examples:
# Get XML as string
xml_content = kp.xml()
print(xml_content[:200]) # Preview first 200 characters
# Export to XML file
kp.dump_xml('database_backup.xml')Utility Functions
Utility functions for working with database field references and values.
def deref(value) -> str:
"""
Dereference field references in values.
Parameters:
- value (str): Value that may contain field references like {REF:T@I:46C9B1FFBD4ABC4BBB260C6190BAD20B}
Returns:
str: Dereferenced value with references resolved to actual values
"""Usage Example:
# Resolve field references in entry values
entry_title = kp.deref(entry.title)
entry_notes = kp.deref(entry.notes)Install with Tessl CLI
npx tessl i tessl/pypi-pykeepass