0
# Entry Management
1

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

4
## Capabilities
5

6
### Entry Creation
7

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

10
```python { .api }
11
def add_entry(destination_group, title, username, password, url=None, notes=None, expiry_time=None, tags=None, icon=None, force_creation=False):
12
    """
13
    Create a new entry in the specified group.
14
    
15
    Parameters:
16
    - destination_group (Group): Group where the entry will be created
17
    - title (str): Entry title/name
18
    - username (str): Username field
19
    - password (str): Password field
20
    - url (str, optional): URL field
21
    - notes (str, optional): Notes field
22
    - expiry_time (datetime, optional): When the entry expires
23
    - tags (list, optional): List of tags as strings
24
    - icon (str, optional): Icon ID (use icons from pykeepass.icons)
25
    - force_creation (bool): Create even if similar entry exists
26
    
27
    Returns:
28
    Entry: The newly created entry object
29
    """
30
```
31

32
**Usage Examples:**
33

34
```python
35
from pykeepass import PyKeePass
36
from pykeepass.icons import KEY, GLOBE
37
from datetime import datetime, timedelta
38

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

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

45
# Full entry with all fields
46
entry = kp.add_entry(
47
    group,
48
    'Gmail Account', 
49
    'user@gmail.com',
50
    'supersecret',
51
    url='https://gmail.com',
52
    notes='Primary email account',
53
    expiry_time=datetime.now() + timedelta(days=365),
54
    tags=['email', 'important'],
55
    icon=GLOBE
56
)
57

58
kp.save()
59
```
60

61
### Entry Search and Retrieval
62

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

65
```python { .api }
66
def find_entries(**kwargs):
67
    """
68
    Find entries with flexible criteria.
69
    
70
    Parameters:
71
    - title (str, optional): Match title field
72
    - username (str, optional): Match username field  
73
    - password (str, optional): Match password field
74
    - url (str, optional): Match URL field
75
    - notes (str, optional): Match notes field
76
    - path (str, optional): Match full path
77
    - uuid (str, optional): Match UUID
78
    - string (str, optional): Match any string field
79
    - group (Group, optional): Limit search to specific group
80
    - regex (bool): Use regex matching
81
    - flags (int, optional): Regex flags
82
    - history (bool): Include history entries
83
    - first (bool): Return only first match
84
    
85
    Returns:
86
    list or Entry: List of matching entries, or single entry if first=True
87
    """
88

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

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

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

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

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

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

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

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

114
**Usage Examples:**
115

116
```python
117
import re
118

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

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

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

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

135
# Multiple criteria
136
entries = kp.find_entries(title='test', username='admin', first=True)
137
```
138

139
### Entry Modification and Management
140

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

143
```python { .api }
144
def delete_entry(entry):
145
    """
146
    Delete an entry from the database.
147
    
148
    Parameters:
149
    - entry (Entry): Entry object to delete
150
    """
151

152
def move_entry(entry, destination_group):
153
    """
154
    Move an entry to a different group.
155
    
156
    Parameters:
157
    - entry (Entry): Entry to move
158
    - destination_group (Group): Destination group
159
    """
160
```
161

162
**Usage Examples:**
163

164
```python
165
# Delete entry
166
old_entry = kp.find_entries_by_title('Old Account', first=True)
167
if old_entry:
168
    kp.delete_entry(old_entry)
169

170
# Move entry
171
entry = kp.find_entries_by_title('Facebook', first=True)
172
social_group = kp.find_groups(name='Social', first=True)
173
kp.move_entry(entry, social_group)
174

175
kp.save()
176
```
177

178
### Entry Class and Properties
179

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

182
```python { .api }
183
class Entry:
184
    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):
185
        """Create a new Entry object."""
186
    
187
    # Standard fields
188
    @property
189
    def title() -> str:
190
        """Entry title/name"""
191
    
192
    @property
193
    def username() -> str:
194
        """Username field"""
195
    
196
    @property  
197
    def password() -> str:
198
        """Password field"""
199
    
200
    @property
201
    def url() -> str:
202
        """URL field"""
203
    
204
    @property
205
    def notes() -> str:
206
        """Notes field"""
207
    
208
    @property
209
    def tags() -> list:
210
        """Entry tags as list of strings"""
211
    
212
    @property
213
    def icon() -> str:
214
        """Icon ID"""
215
    
216
    # Additional properties
217
    @property
218
    def history() -> list:
219
        """Entry history versions as list of Entry objects"""
220
    
221
    @property
222
    def autotype_enabled() -> bool:
223
        """AutoType enabled status"""
224
    
225
    @property
226
    def autotype_sequence() -> str:
227
        """AutoType key sequence"""
228
    
229
    @property
230
    def is_a_history_entry() -> bool:
231
        """Whether this entry is a history entry"""
232
    
233
    @property
234
    def path() -> str:
235
        """Full path to entry"""
236
    
237
    @property
238
    def attachments() -> list:
239
        """Entry attachments as list of Attachment objects"""
240
    
241
    @property
242
    def custom_properties() -> dict:
243
        """Custom string fields as dictionary"""
244
```
245

246
### Custom Fields Management
247

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

250
```python { .api }
251
def set_custom_property(key, value):
252
    """
253
    Set a custom string field.
254
    
255
    Parameters:
256
    - key (str): Custom field name
257
    - value (str): Custom field value
258
    """
259

260
def get_custom_property(key):
261
    """
262
    Get a custom string field value.
263
    
264
    Parameters:
265
    - key (str): Custom field name
266
    
267
    Returns:
268
    str: Custom field value, or None if not found
269
    """
270

271
def delete_custom_property(key):
272
    """
273
    Remove a custom string field.
274
    
275
    Parameters:
276
    - key (str): Custom field name to remove
277
    """
278
```
279

280
**Usage Examples:**
281

282
```python
283
entry = kp.find_entries_by_title('My Account', first=True)
284

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

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

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

297
# View all custom properties
298
custom_fields = entry.custom_properties
299
print(custom_fields)
300

301
kp.save()
302
```
303

304
### Entry History and Timestamps
305

306
Manage entry history and update timestamps for tracking changes.
307

308
```python { .api }
309
def save_history():
310
    """Save current entry state to history before making changes."""
311

312
def touch(modify=False):
313
    """
314
    Update access time and optionally modification time.
315
    
316
    Parameters:
317
    - modify (bool): Also update modification time if True
318
    """
319
```
320

321
**Usage Examples:**
322

323
```python
324
entry = kp.find_entries_by_title('Important Account', first=True)
325

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

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

333
# Update timestamps
334
entry.touch(modify=True)
335

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

340
kp.save()
341
```
342

343
### Entry References and Dereferencing
344

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

347
```python { .api }
348
def deref(attribute):
349
    """
350
    Dereference field value, resolving any references.
351
    
352
    Parameters:
353
    - attribute (str): Attribute name to dereference
354
    
355
    Returns:
356
    str: Dereferenced value
357
    """
358

359
def ref(attribute):
360
    """
361
    Create reference to this entry's attribute.
362
    
363
    Parameters:
364
    - attribute (str): Attribute name to reference
365
    
366
    Returns:
367
    str: Reference string that can be used in other entries
368
    """
369
```
370

371
**Usage Examples:**
372

373
```python
374
# Create reference to entry
375
source_entry = kp.find_entries_by_title('Master Account', first=True)
376
ref_string = source_entry.ref('password')
377

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

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

386
kp.save()
387
```