or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

attachments.mddatabase-operations.mdentry-management.mdgroup-management.mdindex.md
tile.json

tessl/pypi-pykeepass

Python library to interact with keepass databases (supports KDBX3 and KDBX4)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pykeepass@3.2.x

To install, run

npx @tessl/cli install tessl/pypi-pykeepass@3.2.0

index.mddocs/

PyKeePass

A comprehensive Python library for interacting with KeePass password databases, supporting both KDBX3 and KDBX4 formats. PyKeePass enables developers to programmatically read, write, and manipulate KeePass databases, including creating and modifying entries and groups, managing attachments, handling custom fields, and implementing secure database operations with password and keyfile authentication.

Package Information

  • Package Name: pykeepass
  • Language: Python
  • Installation: pip install pykeepass
  • Version: 3.2.1
  • License: GPL3

Core Imports

from pykeepass import PyKeePass, create_database

Import specific classes for direct use:

from pykeepass import PyKeePass
from pykeepass.entry import Entry
from pykeepass.group import Group
from pykeepass.attachment import Attachment

Import exception classes for error handling:

from pykeepass.exceptions import CredentialsError, PayloadChecksumError, HeaderChecksumError, BinaryError

Import icon constants:

from pykeepass.icons import KEY, GLOBE, WARNING_SIGN, SERVER

Basic Usage

from pykeepass import PyKeePass, create_database

# Create a new database
kp = create_database('new_database.kdbx', password='supersecret')

# Open an existing database
kp = PyKeePass('existing_database.kdbx', password='supersecret')

# Alternative authentication methods
kp = PyKeePass('database.kdbx', keyfile='keyfile.key')
kp = PyKeePass('database.kdbx', password='secret', keyfile='keyfile.key')

# Work with groups
root_group = kp.root_group
social_group = kp.add_group(root_group, 'Social')

# Work with entries
facebook_entry = kp.add_entry(
    social_group, 
    'Facebook', 
    'myusername', 
    'mypassword',
    url='https://facebook.com',
    notes='My social media account'
)

# Save changes
kp.save()

# Search for entries and groups
entries = kp.find_entries(title='Facebook', first=True)
groups = kp.find_groups(name='Social', first=True)

Architecture

PyKeePass is built around a hierarchical database structure that mirrors KeePass databases:

  • PyKeePass: The main database controller providing high-level operations and search capabilities
  • Group: Hierarchical containers (folders) that organize entries and other groups
  • Entry: Individual password records containing credentials and metadata
  • Attachment: File attachments linked to entries for storing additional data
  • BaseElement: Shared functionality for Groups and Entries including timestamps, UUIDs, and expiration

The library supports both KDBX3 and KDBX4 database formats with full encryption and authentication including password-based authentication, keyfile authentication, and combined authentication methods.

Capabilities

Database Operations

Core functionality for creating, opening, saving, and managing KeePass database files with support for various authentication methods and database formats.

class PyKeePass:
    def __init__(filename, password=None, keyfile=None, transformed_key=None): ...
    def read(filename=None, password=None, keyfile=None, transformed_key=None): ...
    def save(filename=None, transformed_key=None): ...

def create_database(filename, password=None, keyfile=None, transformed_key=None) -> PyKeePass: ...

Database Operations

Entry Management

Comprehensive entry management including creation, modification, deletion, and advanced search capabilities across all entry fields with regex support.

# PyKeePass entry methods
def add_entry(destination_group, title, username, password, url=None, notes=None, expiry_time=None, tags=None, icon=None, force_creation=False): ...
def delete_entry(entry): ...
def move_entry(entry, destination_group): ...
def find_entries(**kwargs): ...
def find_entries_by_title(title, regex=False, flags=None, group=None, history=False, first=False): ...

# Entry class
class Entry:
    def __init__(title=None, username=None, password=None, url=None, notes=None, tags=None, expires=False, expiry_time=None, icon=None, autotype_sequence=None, autotype_enabled=True, element=None, kp=None): ...
    def set_custom_property(key, value): ...
    def get_custom_property(key): ...
    def save_history(): ...

Entry Management

Group Management

Group (folder) operations for organizing database structure including hierarchical management, creation, deletion, and search functionality.

# PyKeePass group methods  
def add_group(destination_group, group_name, icon=None, notes=None): ...
def delete_group(group): ...
def move_group(group, destination_group): ...
def find_groups(**kwargs): ...
def find_groups_by_name(group_name, regex=False, flags=None, group=None, first=False): ...

# Group class
class Group:
    def __init__(name=None, element=None, icon=None, notes=None, kp=None, expires=None, expiry_time=None): ...
    def append(entries): ...

Group Management

Attachment and Binary Management

File attachment handling including adding, retrieving, and managing binary data associated with database entries.

# PyKeePass attachment methods
def find_attachments(**kwargs): ...
def add_binary(data, compressed=True, protected=True): ...
def delete_binary(id): ...

# Entry attachment methods
def add_attachment(id, filename): ...
def delete_attachment(attachment): ...

# Attachment class
class Attachment:
    def __init__(element=None, kp=None, id=None, filename=None): ...
    def delete(): ...

Attachments

Types and Exceptions

Exception Classes

class CredentialsError(Exception):
    """Wrong password/keyfile or transformed key"""

class PayloadChecksumError(Exception):
    """Payload block checksum error (corruption)"""

class HeaderChecksumError(Exception):
    """Header checksum error (tampering/corruption)"""

class BinaryError(Exception):
    """Binary/attachment related errors"""

Common Data Types

# Core classes inherit from BaseElement
class BaseElement:
    @property
    def uuid() -> uuid.UUID: ...
    @property
    def icon() -> str: ...
    @property  
    def expires() -> bool: ...
    @property
    def expired() -> bool: ...
    @property
    def expiry_time() -> datetime: ...
    @property
    def ctime() -> datetime: ...
    @property
    def atime() -> datetime: ...
    @property
    def mtime() -> datetime: ...
    @property
    def group() -> Group: ...
    @property
    def parentgroup() -> Group: ...  # Alias for group property
    
    def delete(): ...
    def dump_xml(pretty_print=False): ...