0
# Search Operations
1

2
Provides powerful search capabilities for finding secret items using attribute-based queries. Supports both global searches across all collections and collection-specific searches.
3

4
## Capabilities
5

6
### Global Item Search
7

8
Searches for items across all available collections using attribute matching, providing a comprehensive way to find secrets system-wide.
9

10
```python { .api }
11
def search_items(connection: DBusConnection, attributes: Dict[str, str]) -> Iterator[Item]:
12
    """
13
    Returns items from all collections matching the given attributes.
14
    
15
    Parameters:
16
        connection (DBusConnection): Active D-Bus connection
17
        attributes (Dict[str, str]): Key-value pairs to match against item attributes
18
    
19
    Returns:
20
        Iterator[Item]: Generator yielding matching items from all collections
21
    
22
    Note:
23
        Searches both locked and unlocked collections, but may return items
24
        that require unlocking before accessing their secret data.
25
    """
26
```
27

28
### Collection-Specific Search
29

30
Searches within a specific collection for items matching given attributes, useful when working with organized secret storage.
31

32
```python { .api }
33
# Available as method on Collection class
34
class Collection:
35
    def search_items(self, attributes: Dict[str, str]) -> Iterator[Item]:
36
        """
37
        Returns items from this collection matching the given attributes.
38
        
39
        Parameters:
40
            attributes (Dict[str, str]): Key-value pairs to match
41
        
42
        Returns:
43
            Iterator[Item]: Generator yielding matching items from this collection
44
        """
45
```
46

47
**Usage Examples:**
48

49
```python
50
import secretstorage
51

52
connection = secretstorage.dbus_init()
53

54
# Global search across all collections
55
# Find all database passwords
56
db_items = list(secretstorage.search_items(
57
    connection, 
58
    {"type": "database", "environment": "production"}
59
))
60

61
# Find specific application credentials
62
app_items = list(secretstorage.search_items(
63
    connection,
64
    {"application": "myapp", "username": "admin"}
65
))
66

67
# Collection-specific search
68
collection = secretstorage.get_default_collection(connection)
69
local_items = list(collection.search_items({"service": "github"}))
70

71
# Search with multiple criteria
72
complex_search = list(secretstorage.search_items(
73
    connection,
74
    {
75
        "application": "web-browser",
76
        "domain": "example.com",
77
        "username": "john.doe"
78
    }
79
))
80

81
# Handle search results
82
for item in app_items:
83
    print(f"Found item: {item.get_label()}")
84
    attributes = item.get_attributes()
85
    print(f"  Application: {attributes.get('application')}")
86
    print(f"  Username: {attributes.get('username')}")
87
    
88
    # Check if item is accessible
89
    if not item.is_locked():
90
        secret = item.get_secret()
91
        print(f"  Secret length: {len(secret)} bytes")
92
    else:
93
        print("  Item is locked")
94

95
# Search for items by partial attribute matching
96
# Note: SecretStorage requires exact attribute matching
97
email_items = []
98
for item in secretstorage.search_items(connection, {}):  # Get all items
99
    attrs = item.get_attributes()
100
    if any("email" in key.lower() or "mail" in key.lower() for key in attrs.keys()):
101
        email_items.append(item)
102

103
# Organize search results by application
104
from collections import defaultdict
105

106
results_by_app = defaultdict(list)
107
for item in secretstorage.search_items(connection, {}):
108
    attrs = item.get_attributes()
109
    app = attrs.get("application", "unknown")
110
    results_by_app[app].append(item)
111

112
for app, items in results_by_app.items():
113
    print(f"{app}: {len(items)} items")
114
```
115

116
## Search Patterns
117

118
### Common Attribute Keys
119

120
Applications typically use these standard attribute keys for consistent searching:
121

122
- `application`: Application name (e.g., "firefox", "chrome", "myapp")
123
- `service`: Service name (e.g., "github", "gmail", "database")
124
- `username`: Username or account identifier
125
- `domain`: Domain or server name
126
- `protocol`: Protocol type (e.g., "https", "ssh", "ftp")
127
- `server`: Server hostname or IP
128
- `port`: Port number
129
- `type`: Secret type (e.g., "password", "token", "key")
130

131
### Search Best Practices
132

133
```python
134
# Use specific attributes for precise matching
135
specific_items = list(secretstorage.search_items(
136
    connection,
137
    {
138
        "application": "myapp",
139
        "server": "api.example.com",
140
        "username": "service_account"
141
    }
142
))
143

144
# Fallback search with broader criteria
145
if not specific_items:
146
    broader_items = list(secretstorage.search_items(
147
        connection,
148
        {"application": "myapp"}
149
    ))
150

151
# Check for empty results
152
items = list(secretstorage.search_items(connection, {"nonexistent": "key"}))
153
if not items:
154
    print("No matching items found")
155

156
# Handle multiple matches
157
matches = list(secretstorage.search_items(connection, {"service": "email"}))
158
if len(matches) > 1:
159
    print(f"Found {len(matches)} email accounts:")
160
    for item in matches:
161
        attrs = item.get_attributes()
162
        print(f"  - {attrs.get('username', 'unknown')}@{attrs.get('domain', 'unknown')}")
163
```
164

165
## Types
166

167
```python { .api }
168
from typing import Dict, Iterator
169

170
# From jeepney.io.blocking (external dependency)
171
class DBusConnection:
172
    """D-Bus connection for communicating with system services."""
173

174
# From secretstorage.item
175
class Item:
176
    """Represents a secret item within a collection."""
177
```