0
# Item Management
1
2
Handles individual secret items with comprehensive operations for storing, retrieving, and managing secret data, attributes, and metadata. Items represent individual secrets stored within collections.
3
4
## Capabilities
5
6
### Item Class
7
8
The main interface for working with individual secret items, providing access to secret data, attributes, labels, and metadata.
9
10
```python { .api }
11
class Item:
12
"""Represents a secret item within a collection."""
13
14
def __init__(self, connection: DBusConnection, item_path: str, session: Optional[Session] = None) -> None:
15
"""
16
Initialize item instance.
17
18
Parameters:
19
connection (DBusConnection): Active D-Bus connection
20
item_path (str): D-Bus object path for the item
21
session (Session, optional): Encryption session
22
"""
23
24
def __eq__(self, other: "Item") -> bool:
25
"""Compare items by their D-Bus object path."""
26
27
# Lock/Unlock Operations
28
def is_locked(self) -> bool:
29
"""Returns True if item is locked, False otherwise."""
30
31
def ensure_not_locked(self) -> None:
32
"""Raises LockedException if item is locked."""
33
34
def unlock(self) -> bool:
35
"""
36
Requests unlocking the item (usually unlocks the entire collection).
37
38
Returns:
39
bool: False if successfully unlocked, True if prompt dismissed
40
"""
41
42
# Secret Operations
43
def get_secret(self) -> bytes:
44
"""
45
Returns the item's secret data.
46
47
Returns:
48
bytes: Decrypted secret data
49
50
Raises:
51
LockedException: If item/collection is locked
52
"""
53
54
def get_secret_content_type(self) -> str:
55
"""
56
Returns the content type of the item's secret.
57
58
Returns:
59
str: MIME type of secret data (e.g., 'text/plain')
60
61
Raises:
62
LockedException: If item/collection is locked
63
"""
64
65
def set_secret(self, secret: bytes, content_type: str = 'text/plain') -> None:
66
"""
67
Sets the item's secret data.
68
69
Parameters:
70
secret (bytes): New secret data to store
71
content_type (str): MIME type of the secret data
72
73
Raises:
74
LockedException: If item/collection is locked
75
"""
76
77
# Attribute Operations
78
def get_attributes(self) -> Dict[str, str]:
79
"""
80
Returns item attributes as a dictionary.
81
82
Returns:
83
Dict[str, str]: Key-value attribute pairs used for searching
84
"""
85
86
def set_attributes(self, attributes: Dict[str, str]) -> None:
87
"""
88
Sets item attributes.
89
90
Parameters:
91
attributes (Dict[str, str]): New attribute key-value pairs
92
"""
93
94
# Label Operations
95
def get_label(self) -> str:
96
"""
97
Returns the item's human-readable label.
98
99
Returns:
100
str: Item label/name
101
"""
102
103
def set_label(self, label: str) -> None:
104
"""
105
Sets the item's label.
106
107
Parameters:
108
label (str): New item label
109
110
Raises:
111
LockedException: If item/collection is locked
112
"""
113
114
# Metadata Operations
115
def get_created(self) -> int:
116
"""
117
Returns UNIX timestamp when the item was created.
118
119
Returns:
120
int: Creation timestamp
121
"""
122
123
def get_modified(self) -> int:
124
"""
125
Returns UNIX timestamp when the item was last modified.
126
127
Returns:
128
int: Modification timestamp
129
"""
130
131
# Item Management
132
def delete(self) -> None:
133
"""
134
Deletes the item from its collection.
135
136
Raises:
137
LockedException: If item/collection is locked
138
PromptDismissedException: If user dismisses deletion prompt
139
"""
140
```
141
142
**Usage Examples:**
143
144
```python
145
import secretstorage
146
from datetime import datetime
147
148
connection = secretstorage.dbus_init()
149
collection = secretstorage.get_default_collection(connection)
150
151
# Create an item
152
item = collection.create_item(
153
"API Key",
154
{"service": "github", "username": "johndoe"},
155
b"ghp_1234567890abcdef"
156
)
157
158
# Retrieve secret data
159
secret = item.get_secret()
160
print(f"Secret: {secret.decode()}")
161
162
# Check content type
163
content_type = item.get_secret_content_type()
164
print(f"Content type: {content_type}")
165
166
# Work with attributes
167
attributes = item.get_attributes()
168
print(f"Service: {attributes['service']}")
169
170
# Update attributes
171
attributes["last_used"] = str(int(datetime.now().timestamp()))
172
item.set_attributes(attributes)
173
174
# Update the secret
175
item.set_secret(b"new_api_key_value")
176
177
# Check metadata
178
created = item.get_created()
179
modified = item.get_modified()
180
print(f"Created: {datetime.fromtimestamp(created)}")
181
print(f"Modified: {datetime.fromtimestamp(modified)}")
182
183
# Update label
184
item.set_label("GitHub API Key (Updated)")
185
186
# Handle locked items
187
if item.is_locked():
188
dismissed = item.unlock()
189
if not dismissed:
190
secret = item.get_secret()
191
192
# Delete item when no longer needed
193
item.delete()
194
```
195
196
## Types
197
198
```python { .api }
199
from typing import Dict, Optional
200
201
# From jeepney.io.blocking (external dependency)
202
class DBusConnection:
203
"""D-Bus connection for communicating with system services."""
204
205
# From secretstorage.dhcrypto
206
class Session:
207
"""Cryptographic session for secure data transfer."""
208
```