0
# Collection Operations
1

2
Manages collections (keyrings) which serve as secure containers for organizing related secret items. Collections can be locked/unlocked, created/deleted, and configured with labels and aliases.
3

4
## Capabilities
5

6
### Default Collection Access
7

8
Retrieves the default collection, which is the primary keyring where most applications store their secrets. Creates the collection if it doesn't exist.
9

10
```python { .api }
11
def get_default_collection(connection: DBusConnection, session: Optional[Session] = None) -> Collection:
12
    """
13
    Returns the default collection, creating it if necessary.
14
    
15
    Parameters:
16
        connection (DBusConnection): Active D-Bus connection
17
        session (Session, optional): Encryption session for secure operations
18
    
19
    Returns:
20
        Collection: The default collection instance
21
    
22
    Raises:
23
        SecretServiceNotAvailableException: If Secret Service is unavailable
24
    """
25
```
26

27
### Collection Enumeration
28

29
Lists all available collections on the system, allowing applications to discover and access multiple keyrings.
30

31
```python { .api }
32
def get_all_collections(connection: DBusConnection) -> Iterator[Collection]:
33
    """
34
    Returns a generator of all available collections.
35
    
36
    Parameters:
37
        connection (DBusConnection): Active D-Bus connection
38
    
39
    Returns:
40
        Iterator[Collection]: Generator yielding Collection instances
41
    """
42

43
def get_any_collection(connection: DBusConnection) -> Collection:
44
    """
45
    Returns any available collection in order of preference:
46
    1. Default collection
47
    2. Session collection (temporary)
48
    3. First collection in the list
49
    
50
    Parameters:
51
        connection (DBusConnection): Active D-Bus connection
52
    
53
    Returns:
54
        Collection: First available collection
55
    
56
    Raises:
57
        ItemNotFoundException: If no collections are found
58
    """
59

60
def get_collection_by_alias(connection: DBusConnection, alias: str) -> Collection:
61
    """
62
    Returns the collection with the given alias.
63
    
64
    Parameters:
65
        connection (DBusConnection): Active D-Bus connection
66
        alias (str): Collection alias identifier
67
    
68
    Returns:
69
        Collection: Collection with specified alias
70
    
71
    Raises:
72
        ItemNotFoundException: If no collection with the alias exists
73
    """
74
```
75

76
### Collection Creation
77

78
Creates new collections with custom labels and aliases for organizing different types of secrets.
79

80
```python { .api }
81
def create_collection(connection: DBusConnection, label: str, alias: str = '', session: Optional[Session] = None) -> Collection:
82
    """
83
    Creates a new collection with given label and alias.
84
    
85
    Parameters:
86
        connection (DBusConnection): Active D-Bus connection
87
        label (str): Human-readable collection name
88
        alias (str, optional): Collection alias for programmatic access
89
        session (Session, optional): Encryption session
90
    
91
    Returns:
92
        Collection: Newly created collection
93
    
94
    Raises:
95
        PromptDismissedException: If user dismisses creation prompt
96
        SecretServiceNotAvailableException: If Secret Service is unavailable
97
    """
98
```
99

100
### Collection Class
101

102
The main interface for working with individual collections, providing methods for item management, locking/unlocking, and collection metadata.
103

104
```python { .api }
105
class Collection:
106
    """Represents a collection of secret items."""
107
    
108
    def __init__(self, connection: DBusConnection, collection_path: str = DEFAULT_COLLECTION, session: Optional[Session] = None) -> None:
109
        """
110
        Initialize collection instance.
111
        
112
        Parameters:
113
            connection (DBusConnection): Active D-Bus connection
114
            collection_path (str): D-Bus object path for the collection
115
            session (Session, optional): Encryption session
116
        """
117
    
118
    # Lock/Unlock Operations
119
    def is_locked(self) -> bool:
120
        """Returns True if collection is locked, False otherwise."""
121
    
122
    def ensure_not_locked(self) -> None:
123
        """Raises LockedException if collection is locked."""
124
    
125
    def unlock(self) -> bool:
126
        """
127
        Requests unlocking the collection.
128
        
129
        Returns:
130
            bool: False if successfully unlocked, True if prompt dismissed
131
        
132
        Raises:
133
            SecretServiceNotAvailableException: If Secret Service unavailable
134
        """
135
    
136
    def lock(self) -> None:
137
        """Locks the collection."""
138
    
139
    # Collection Management
140
    def delete(self) -> None:
141
        """
142
        Deletes the collection and all items inside it.
143
        
144
        Raises:
145
            LockedException: If collection is locked
146
            PromptDismissedException: If user dismisses deletion prompt
147
        """
148
    
149
    def get_label(self) -> str:
150
        """Returns the collection label."""
151
    
152
    def set_label(self, label: str) -> None:
153
        """
154
        Sets collection label.
155
        
156
        Parameters:
157
            label (str): New collection label
158
        
159
        Raises:
160
            LockedException: If collection is locked
161
        """
162
    
163
    # Item Operations
164
    def get_all_items(self) -> Iterator[Item]:
165
        """Returns a generator of all items in the collection."""
166
    
167
    def search_items(self, attributes: Dict[str, str]) -> Iterator[Item]:
168
        """
169
        Returns items matching the given attributes.
170
        
171
        Parameters:
172
            attributes (Dict[str, str]): Key-value pairs to match
173
        
174
        Returns:
175
            Iterator[Item]: Generator yielding matching items
176
        """
177
    
178
    def create_item(self, label: str, attributes: Dict[str, str], secret: bytes, 
179
                   replace: bool = False, content_type: str = 'text/plain') -> Item:
180
        """
181
        Creates a new secret item in the collection.
182
        
183
        Parameters:
184
            label (str): Human-readable item name
185
            attributes (Dict[str, str]): Key-value attributes for searching
186
            secret (bytes): Secret data to store
187
            replace (bool): Whether to replace existing item with same attributes
188
            content_type (str): MIME type of secret data
189
        
190
        Returns:
191
            Item: Newly created item instance
192
        
193
        Raises:
194
            LockedException: If collection is locked
195
            PromptDismissedException: If user dismisses creation prompt
196
        """
197
```
198

199
**Usage Examples:**
200

201
```python
202
import secretstorage
203

204
# Get default collection
205
connection = secretstorage.dbus_init()
206
collection = secretstorage.get_default_collection(connection)
207

208
# Create a new collection
209
new_collection = secretstorage.create_collection(
210
    connection, 
211
    "My App Secrets", 
212
    "myapp"
213
)
214

215
# Work with locked collections
216
if collection.is_locked():
217
    dismissed = collection.unlock()
218
    if dismissed:
219
        print("User dismissed unlock prompt")
220
    else:
221
        print("Collection unlocked successfully")
222

223
# Create an item in the collection
224
item = collection.create_item(
225
    "Database Password",
226
    {"application": "myapp", "server": "db.example.com"},
227
    b"super_secret_password"
228
)
229
```
230

231
## Types
232

233
```python { .api }
234
from typing import Dict, Iterator, Optional
235

236
# From secretstorage.dhcrypto
237
class Session:
238
    """Cryptographic session for secure data transfer."""
239
```