0
# Group Management
1

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

4
## Capabilities
5

6
### Group Creation
7

8
Create new groups (folders) to organize entries hierarchically within the database.
9

10
```python { .api }
11
def add_group(destination_group, group_name, icon=None, notes=None):
12
    """
13
    Create a new group in the specified parent group.
14
    
15
    Parameters:
16
    - destination_group (Group): Parent group where new group will be created
17
    - group_name (str): Name for the new group
18
    - icon (str, optional): Icon ID for the group (use icons from pykeepass.icons)
19
    - notes (str, optional): Notes for the group
20
    
21
    Returns:
22
    Group: The newly created group object
23
    """
24
```
25

26
**Usage Examples:**
27

28
```python
29
from pykeepass import PyKeePass
30
from pykeepass.icons import FOLDER_OPEN, LOCK_CLOSED
31

32
kp = PyKeePass('database.kdbx', password='secret')
33
root = kp.root_group
34

35
# Basic group creation
36
social_group = kp.add_group(root, 'Social Media')
37

38
# Group with icon and notes
39
work_group = kp.add_group(
40
    root, 
41
    'Work Accounts',
42
    icon=LOCK_CLOSED,
43
    notes='All work-related passwords and accounts'
44
)
45

46
# Nested group creation
47
dev_group = kp.add_group(work_group, 'Development Tools')
48

49
kp.save()
50
```
51

52
### Group Search and Retrieval
53

54
Comprehensive search functionality for finding groups by various criteria with regex support.
55

56
```python { .api }
57
def find_groups(**kwargs):
58
    """
59
    Find groups with flexible criteria.
60
    
61
    Parameters:
62
    - name (str, optional): Match group name
63
    - path (str, optional): Match full path  
64
    - uuid (str, optional): Match UUID
65
    - notes (str, optional): Match notes field
66
    - group (Group, optional): Limit search to specific parent group
67
    - regex (bool): Use regex matching
68
    - flags (int, optional): Regex flags
69
    - first (bool): Return only first match
70
    
71
    Returns:
72
    list or Group: List of matching groups, or single group if first=True
73
    """
74

75
def find_groups_by_name(group_name, regex=False, flags=None, group=None, first=False):
76
    """
77
    Find groups by name.
78
    
79
    Parameters:
80
    - group_name (str): Group name to search for
81
    - regex (bool): Use regex matching
82
    - flags (int, optional): Regex flags
83
    - group (Group, optional): Limit search to specific parent group
84
    - first (bool): Return only first match
85
    
86
    Returns:
87
    list or Group: Matching groups
88
    """
89

90
def find_groups_by_path(group_path_str=None, regex=False, flags=None, group=None, first=False):
91
    """
92
    Find groups by full path.
93
    
94
    Parameters:
95
    - group_path_str (str): Full group path to search for
96
    - regex (bool): Use regex matching
97
    - flags (int, optional): Regex flags  
98
    - group (Group, optional): Limit search to specific parent group
99
    - first (bool): Return only first match
100
    
101
    Returns:
102
    list or Group: Matching groups
103
    """
104

105
def find_groups_by_uuid(uuid, regex=False, flags=None, group=None, history=False, first=False):
106
    """Find groups by UUID."""
107

108
def find_groups_by_notes(notes, regex=False, flags=None, group=None, history=False, first=False):
109
    """Find groups by notes field."""
110
```
111

112
**Usage Examples:**
113

114
```python
115
import re
116

117
# Basic searches
118
social_groups = kp.find_groups(name='Social')
119
work_group = kp.find_groups_by_name('Work', first=True)
120

121
# Path-based search
122
dev_group = kp.find_groups_by_path('Root/Work/Development', first=True)
123

124
# Regex searches
125
media_groups = kp.find_groups_by_name(r'.*[Mm]edia.*', regex=True)
126
important_groups = kp.find_groups_by_notes('important', regex=True, flags=re.IGNORECASE)
127

128
# Limit search scope
129
work_group = kp.find_groups_by_name('Work', first=True)
130
sub_groups = kp.find_groups(group=work_group)
131

132
# Find all groups
133
all_groups = kp.groups
134
```
135

136
### Group Modification and Management
137

138
Modify existing groups and manage their lifecycle including deletion and movement.
139

140
```python { .api }
141
def delete_group(group):
142
    """
143
    Delete a group and all its contents from the database.
144
    
145
    Parameters:
146
    - group (Group): Group object to delete
147
    
148
    Note: This will also delete all entries and subgroups within the group
149
    """
150

151
def move_group(group, destination_group):
152
    """
153
    Move a group to a different parent group.
154
    
155
    Parameters:
156
    - group (Group): Group to move
157
    - destination_group (Group): New parent group
158
    """
159
```
160

161
**Usage Examples:**
162

163
```python
164
# Delete empty group
165
old_group = kp.find_groups_by_name('Temporary', first=True)
166
if old_group and not old_group.entries and not old_group.subgroups:
167
    kp.delete_group(old_group)
168

169
# Move group to new parent
170
social_group = kp.find_groups_by_name('Social Media', first=True)
171
personal_group = kp.find_groups_by_name('Personal', first=True)
172
kp.move_group(social_group, personal_group)
173

174
kp.save()
175
```
176

177
### Group Class and Properties
178

179
The Group class represents hierarchical containers (folders) for organizing entries and other groups.
180

181
```python { .api }
182
class Group:
183
    def __init__(name=None, element=None, icon=None, notes=None, kp=None, expires=None, expiry_time=None):
184
        """Create a new Group object."""
185
    
186
    @property
187
    def name() -> str:
188
        """Group name"""
189
    
190
    @property
191
    def notes() -> str:
192
        """Group notes"""
193
    
194
    @property
195
    def entries() -> list:
196
        """Entries in this group as list of Entry objects"""
197
    
198
    @property  
199
    def subgroups() -> list:
200
        """Child groups as list of Group objects"""
201
    
202
    @property
203
    def is_root_group() -> bool:
204
        """Whether this is the root group"""
205
    
206
    @property
207
    def path() -> str:
208
        """Full path to group"""
209
    
210
    def append(entries):
211
        """
212
        Add entries or groups to this group.
213
        
214
        Parameters:
215
        - entries (Entry or Group or list): Entry/Group objects or list of objects to add
216
        """
217
```
218

219
**Usage Examples:**
220

221
```python
222
# Access group properties
223
work_group = kp.find_groups_by_name('Work', first=True)
224
print(f"Group name: {work_group.name}")
225
print(f"Group path: {work_group.path}")
226
print(f"Notes: {work_group.notes}")
227

228
# Check if root group
229
if work_group.is_root_group:
230
    print("This is the root group")
231

232
# Access group contents
233
print(f"Entries in group: {len(work_group.entries)}")
234
print(f"Subgroups: {len(work_group.subgroups)}")
235

236
# List all entries in group
237
for entry in work_group.entries:
238
    print(f"  Entry: {entry.title}")
239

240
# List all subgroups
241
for subgroup in work_group.subgroups:
242
    print(f"  Subgroup: {subgroup.name}")
243
```
244

245
### Group Content Management
246

247
Add entries and groups to existing groups programmatically.
248

249
```python { .api }
250
def append(entries):
251
    """
252
    Add entries or groups to this group.
253
    
254
    Parameters:
255
    - entries (Entry or Group or list): Entry/Group objects or list of objects to add to this group
256
    """
257
```
258

259
**Usage Examples:**
260

261
```python
262
# Move existing entry to group
263
entry = kp.find_entries_by_title('Facebook', first=True)
264
social_group = kp.find_groups_by_name('Social', first=True)
265
social_group.append(entry)
266

267
# Move multiple entries
268
entries = kp.find_entries_by_string('work', regex=True)
269
work_group = kp.find_groups_by_name('Work', first=True)
270
work_group.append(entries)  # Can pass a list
271

272
# Move subgroup
273
dev_group = kp.find_groups_by_name('Development', first=True)
274
tech_group = kp.find_groups_by_name('Technology', first=True)
275
tech_group.append(dev_group)
276

277
kp.save()
278
```
279

280
### Hierarchical Navigation
281

282
Navigate and work with the hierarchical group structure.
283

284
**Usage Examples:**
285

286
```python
287
# Start from root and navigate down
288
root = kp.root_group
289
print(f"Root group: {root.name}")
290

291
# Find specific paths
292
for subgroup in root.subgroups:
293
    print(f"Top-level group: {subgroup.name}")
294
    for sub_subgroup in subgroup.subgroups:
295
        print(f"  Subgroup: {sub_subgroup.name}")
296

297
# Get full hierarchy paths
298
def print_group_tree(group, indent=0):
299
    print("  " * indent + f"Group: {group.name}")
300
    for entry in group.entries:
301
        print("  " * (indent + 1) + f"Entry: {entry.title}")
302
    for subgroup in group.subgroups:
303
        print_group_tree(subgroup, indent + 1)
304

305
print_group_tree(root)
306

307
# Navigate by path components
308
path_parts = ['Work', 'Development', 'GitHub']
309
current_group = root
310
for part in path_parts:
311
    current_group = next(
312
        (g for g in current_group.subgroups if g.name == part), 
313
        None
314
    )
315
    if not current_group:
316
        break
317

318
if current_group:
319
    print(f"Found group: {current_group.path}")
320
```
321

322
### Group Organization Patterns
323

324
Common patterns for organizing groups effectively.
325

326
**Usage Examples:**
327

328
```python
329
# Create organized structure
330
root = kp.root_group
331

332
# By category
333
personal = kp.add_group(root, 'Personal')
334
work = kp.add_group(root, 'Work') 
335
finance = kp.add_group(root, 'Finance')
336

337
# By access level
338
kp.add_group(work, 'Public')
339
kp.add_group(work, 'Internal')
340
kp.add_group(work, 'Confidential')
341

342
# By platform/service type
343
kp.add_group(personal, 'Social Media')
344
kp.add_group(personal, 'Email Accounts')
345
kp.add_group(personal, 'Shopping')
346
kp.add_group(work, 'Development Tools')
347
kp.add_group(work, 'Cloud Services')
348

349
# By project
350
projects = kp.add_group(work, 'Projects')
351
kp.add_group(projects, 'Project Alpha')
352
kp.add_group(projects, 'Project Beta')
353

354
kp.save()
355
```