tessl/pypi-pykeepass

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

—

Pending

Overview

Eval results

Files

Entry Management

Name: tessl/pypi-pykeepass
Author: tessl

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

Capabilities

Entry Creation

Create new password entries in the database with comprehensive field support.

def add_entry(destination_group, title, username, password, url=None, notes=None, expiry_time=None, tags=None, icon=None, force_creation=False):
    """
    Create a new entry in the specified group.
    
    Parameters:
    - destination_group (Group): Group where the entry will be created
    - title (str): Entry title/name
    - username (str): Username field
    - password (str): Password field
    - url (str, optional): URL field
    - notes (str, optional): Notes field
    - expiry_time (datetime, optional): When the entry expires
    - tags (list, optional): List of tags as strings
    - icon (str, optional): Icon ID (use icons from pykeepass.icons)
    - force_creation (bool): Create even if similar entry exists
    
    Returns:
    Entry: The newly created entry object
    """

Usage Examples:

from pykeepass import PyKeePass
from pykeepass.icons import KEY, GLOBE
from datetime import datetime, timedelta

kp = PyKeePass('database.kdbx', password='secret')
group = kp.find_groups(name='Social', first=True)

# Basic entry
entry = kp.add_entry(group, 'Facebook', 'myusername', 'mypassword')

# Full entry with all fields
entry = kp.add_entry(
    group,
    'Gmail Account', 
    'user@gmail.com',
    'supersecret',
    url='https://gmail.com',
    notes='Primary email account',
    expiry_time=datetime.now() + timedelta(days=365),
    tags=['email', 'important'],
    icon=GLOBE
)

kp.save()

Entry Search and Retrieval

Comprehensive search functionality across all entry fields with regex support and flexible filtering.

def find_entries(**kwargs):
    """
    Find entries with flexible criteria.
    
    Parameters:
    - title (str, optional): Match title field
    - username (str, optional): Match username field  
    - password (str, optional): Match password field
    - url (str, optional): Match URL field
    - notes (str, optional): Match notes field
    - path (str, optional): Match full path
    - uuid (str, optional): Match UUID
    - string (str, optional): Match any string field
    - group (Group, optional): Limit search to specific group
    - regex (bool): Use regex matching
    - flags (int, optional): Regex flags
    - history (bool): Include history entries
    - first (bool): Return only first match
    
    Returns:
    list or Entry: List of matching entries, or single entry if first=True
    """

def find_entries_by_title(title, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by title field."""

def find_entries_by_username(username, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by username field."""

def find_entries_by_password(password, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by password field."""

def find_entries_by_url(url, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by URL field."""

def find_entries_by_notes(notes, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by notes field."""

def find_entries_by_path(path, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by full path."""

def find_entries_by_uuid(uuid, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by UUID."""

def find_entries_by_string(string, regex=False, flags=None, group=None, history=False, first=False):
    """Find entries by matching any string field."""

Usage Examples:

import re

# Basic searches
facebook_entries = kp.find_entries(title='Facebook')
gmail_entry = kp.find_entries_by_title('Gmail', first=True)
admin_entries = kp.find_entries_by_username('admin')

# Regex searches
email_entries = kp.find_entries_by_username(r'.*@gmail\.com', regex=True)
secure_entries = kp.find_entries_by_password(r'^.{12,}$', regex=True)  # 12+ chars

# Case-insensitive search
social_entries = kp.find_entries_by_string('social', regex=True, flags=re.IGNORECASE)

# Limit search to specific group
work_group = kp.find_groups(name='Work', first=True)
work_entries = kp.find_entries(group=work_group)

# Multiple criteria
entries = kp.find_entries(title='test', username='admin', first=True)

Entry Modification and Management

Modify existing entries and manage their lifecycle including deletion and movement.

def delete_entry(entry):
    """
    Delete an entry from the database.
    
    Parameters:
    - entry (Entry): Entry object to delete
    """

def move_entry(entry, destination_group):
    """
    Move an entry to a different group.
    
    Parameters:
    - entry (Entry): Entry to move
    - destination_group (Group): Destination group
    """

Usage Examples:

# Delete entry
old_entry = kp.find_entries_by_title('Old Account', first=True)
if old_entry:
    kp.delete_entry(old_entry)

# Move entry
entry = kp.find_entries_by_title('Facebook', first=True)
social_group = kp.find_groups(name='Social', first=True)
kp.move_entry(entry, social_group)

kp.save()

Entry Class and Properties

The Entry class represents individual password records with comprehensive field access and management.

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):
        """Create a new Entry object."""
    
    # Standard fields
    @property
    def title() -> str:
        """Entry title/name"""
    
    @property
    def username() -> str:
        """Username field"""
    
    @property  
    def password() -> str:
        """Password field"""
    
    @property
    def url() -> str:
        """URL field"""
    
    @property
    def notes() -> str:
        """Notes field"""
    
    @property
    def tags() -> list:
        """Entry tags as list of strings"""
    
    @property
    def icon() -> str:
        """Icon ID"""
    
    # Additional properties
    @property
    def history() -> list:
        """Entry history versions as list of Entry objects"""
    
    @property
    def autotype_enabled() -> bool:
        """AutoType enabled status"""
    
    @property
    def autotype_sequence() -> str:
        """AutoType key sequence"""
    
    @property
    def is_a_history_entry() -> bool:
        """Whether this entry is a history entry"""
    
    @property
    def path() -> str:
        """Full path to entry"""
    
    @property
    def attachments() -> list:
        """Entry attachments as list of Attachment objects"""
    
    @property
    def custom_properties() -> dict:
        """Custom string fields as dictionary"""

Custom Fields Management

Manage custom string fields for entries beyond the standard title/username/password/url/notes fields.

def set_custom_property(key, value):
    """
    Set a custom string field.
    
    Parameters:
    - key (str): Custom field name
    - value (str): Custom field value
    """

def get_custom_property(key):
    """
    Get a custom string field value.
    
    Parameters:
    - key (str): Custom field name
    
    Returns:
    str: Custom field value, or None if not found
    """

def delete_custom_property(key):
    """
    Remove a custom string field.
    
    Parameters:
    - key (str): Custom field name to remove
    """

Usage Examples:

entry = kp.find_entries_by_title('My Account', first=True)

# Set custom fields
entry.set_custom_property('Department', 'Engineering')
entry.set_custom_property('Employee ID', '12345')
entry.set_custom_property('Security Question', 'Mother maiden name')

# Get custom field
dept = entry.get_custom_property('Department')
emp_id = entry.get_custom_property('Employee ID')

# Remove custom field
entry.delete_custom_property('Security Question')

# View all custom properties
custom_fields = entry.custom_properties
print(custom_fields)

kp.save()

Entry History and Timestamps

Manage entry history and update timestamps for tracking changes.

def save_history():
    """Save current entry state to history before making changes."""

def touch(modify=False):
    """
    Update access time and optionally modification time.
    
    Parameters:
    - modify (bool): Also update modification time if True
    """

Usage Examples:

entry = kp.find_entries_by_title('Important Account', first=True)

# Save current state to history before changes
entry.save_history()

# Make changes
entry.password = 'new_password'
entry.notes = 'Updated password on 2023-10-15'

# Update timestamps
entry.touch(modify=True)

# View history
for hist_entry in entry.history:
    print(f"History: {hist_entry.password} at {hist_entry.mtime}")

kp.save()

Entry References and Dereferencing

Handle field references between entries and resolve references to actual values.

def deref(attribute):
    """
    Dereference field value, resolving any references.
    
    Parameters:
    - attribute (str): Attribute name to dereference
    
    Returns:
    str: Dereferenced value
    """

def ref(attribute):
    """
    Create reference to this entry's attribute.
    
    Parameters:
    - attribute (str): Attribute name to reference
    
    Returns:
    str: Reference string that can be used in other entries
    """

Usage Examples:

# Create reference to entry
source_entry = kp.find_entries_by_title('Master Account', first=True)
ref_string = source_entry.ref('password')

# Use reference in another entry
target_entry = kp.find_entries_by_title('Linked Account', first=True)
target_entry.password = ref_string

# Dereference to get actual value
actual_password = target_entry.deref('password')
print(f"Referenced password: {actual_password}")

kp.save()

Install with Tessl CLI