0
# PyKeePass
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pykeepass
7
- **Language**: Python
8
- **Installation**: `pip install pykeepass`
9
- **Version**: 3.2.1
10
- **License**: GPL3
11

12
## Core Imports
13

14
```python
15
from pykeepass import PyKeePass, create_database
16
```
17

18
Import specific classes for direct use:
19

20
```python
21
from pykeepass import PyKeePass
22
from pykeepass.entry import Entry
23
from pykeepass.group import Group
24
from pykeepass.attachment import Attachment
25
```
26

27
Import exception classes for error handling:
28

29
```python
30
from pykeepass.exceptions import CredentialsError, PayloadChecksumError, HeaderChecksumError, BinaryError
31
```
32

33
Import icon constants:
34

35
```python
36
from pykeepass.icons import KEY, GLOBE, WARNING_SIGN, SERVER
37
```
38

39
## Basic Usage
40

41
```python
42
from pykeepass import PyKeePass, create_database
43

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

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

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

54
# Work with groups
55
root_group = kp.root_group
56
social_group = kp.add_group(root_group, 'Social')
57

58
# Work with entries
59
facebook_entry = kp.add_entry(
60
    social_group, 
61
    'Facebook', 
62
    'myusername', 
63
    'mypassword',
64
    url='https://facebook.com',
65
    notes='My social media account'
66
)
67

68
# Save changes
69
kp.save()
70

71
# Search for entries and groups
72
entries = kp.find_entries(title='Facebook', first=True)
73
groups = kp.find_groups(name='Social', first=True)
74
```
75

76
## Architecture
77

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

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

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

88
## Capabilities
89

90
### Database Operations
91

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

94
```python { .api }
95
class PyKeePass:
96
    def __init__(filename, password=None, keyfile=None, transformed_key=None): ...
97
    def read(filename=None, password=None, keyfile=None, transformed_key=None): ...
98
    def save(filename=None, transformed_key=None): ...
99

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

103
[Database Operations](./database-operations.md)
104

105
### Entry Management
106

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

109
```python { .api }
110
# PyKeePass entry methods
111
def add_entry(destination_group, title, username, password, url=None, notes=None, expiry_time=None, tags=None, icon=None, force_creation=False): ...
112
def delete_entry(entry): ...
113
def move_entry(entry, destination_group): ...
114
def find_entries(**kwargs): ...
115
def find_entries_by_title(title, regex=False, flags=None, group=None, history=False, first=False): ...
116

117
# Entry class
118
class Entry:
119
    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): ...
120
    def set_custom_property(key, value): ...
121
    def get_custom_property(key): ...
122
    def save_history(): ...
123
```
124

125
[Entry Management](./entry-management.md)
126

127
### Group Management
128

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

131
```python { .api }
132
# PyKeePass group methods  
133
def add_group(destination_group, group_name, icon=None, notes=None): ...
134
def delete_group(group): ...
135
def move_group(group, destination_group): ...
136
def find_groups(**kwargs): ...
137
def find_groups_by_name(group_name, regex=False, flags=None, group=None, first=False): ...
138

139
# Group class
140
class Group:
141
    def __init__(name=None, element=None, icon=None, notes=None, kp=None, expires=None, expiry_time=None): ...
142
    def append(entries): ...
143
```
144

145
[Group Management](./group-management.md)
146

147
### Attachment and Binary Management
148

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

151
```python { .api }
152
# PyKeePass attachment methods
153
def find_attachments(**kwargs): ...
154
def add_binary(data, compressed=True, protected=True): ...
155
def delete_binary(id): ...
156

157
# Entry attachment methods
158
def add_attachment(id, filename): ...
159
def delete_attachment(attachment): ...
160

161
# Attachment class
162
class Attachment:
163
    def __init__(element=None, kp=None, id=None, filename=None): ...
164
    def delete(): ...
165
```
166

167
[Attachments](./attachments.md)
168

169
## Types and Exceptions
170

171
### Exception Classes
172

173
```python { .api }
174
class CredentialsError(Exception):
175
    """Wrong password/keyfile or transformed key"""
176

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

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

183
class BinaryError(Exception):
184
    """Binary/attachment related errors"""
185
```
186

187
### Common Data Types
188

189
```python { .api }
190
# Core classes inherit from BaseElement
191
class BaseElement:
192
    @property
193
    def uuid() -> uuid.UUID: ...
194
    @property
195
    def icon() -> str: ...
196
    @property  
197
    def expires() -> bool: ...
198
    @property
199
    def expired() -> bool: ...
200
    @property
201
    def expiry_time() -> datetime: ...
202
    @property
203
    def ctime() -> datetime: ...
204
    @property
205
    def atime() -> datetime: ...
206
    @property
207
    def mtime() -> datetime: ...
208
    @property
209
    def group() -> Group: ...
210
    @property
211
    def parentgroup() -> Group: ...  # Alias for group property
212
    
213
    def delete(): ...
214
    def dump_xml(pretty_print=False): ...
215
```