tessl/pypi-secretstorage
Python bindings to FreeDesktop.org Secret Service API for secure password and credential storage
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
collection-operations.mddocs/
Collection Operations
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.
Capabilities
Default Collection Access
Retrieves the default collection, which is the primary keyring where most applications store their secrets. Creates the collection if it doesn't exist.
def get_default_collection(connection: DBusConnection, session: Optional[Session] = None) -> Collection:
"""
Returns the default collection, creating it if necessary.
Parameters:
connection (DBusConnection): Active D-Bus connection
session (Session, optional): Encryption session for secure operations
Returns:
Collection: The default collection instance
Raises:
SecretServiceNotAvailableException: If Secret Service is unavailable
"""Collection Enumeration
Lists all available collections on the system, allowing applications to discover and access multiple keyrings.
def get_all_collections(connection: DBusConnection) -> Iterator[Collection]:
"""
Returns a generator of all available collections.
Parameters:
connection (DBusConnection): Active D-Bus connection
Returns:
Iterator[Collection]: Generator yielding Collection instances
"""
def get_any_collection(connection: DBusConnection) -> Collection:
"""
Returns any available collection in order of preference:
1. Default collection
2. Session collection (temporary)
3. First collection in the list
Parameters:
connection (DBusConnection): Active D-Bus connection
Returns:
Collection: First available collection
Raises:
ItemNotFoundException: If no collections are found
"""
def get_collection_by_alias(connection: DBusConnection, alias: str) -> Collection:
"""
Returns the collection with the given alias.
Parameters:
connection (DBusConnection): Active D-Bus connection
alias (str): Collection alias identifier
Returns:
Collection: Collection with specified alias
Raises:
ItemNotFoundException: If no collection with the alias exists
"""Collection Creation
Creates new collections with custom labels and aliases for organizing different types of secrets.
def create_collection(connection: DBusConnection, label: str, alias: str = '', session: Optional[Session] = None) -> Collection:
"""
Creates a new collection with given label and alias.
Parameters:
connection (DBusConnection): Active D-Bus connection
label (str): Human-readable collection name
alias (str, optional): Collection alias for programmatic access
session (Session, optional): Encryption session
Returns:
Collection: Newly created collection
Raises:
PromptDismissedException: If user dismisses creation prompt
SecretServiceNotAvailableException: If Secret Service is unavailable
"""Collection Class
The main interface for working with individual collections, providing methods for item management, locking/unlocking, and collection metadata.
class Collection:
"""Represents a collection of secret items."""
def __init__(self, connection: DBusConnection, collection_path: str = DEFAULT_COLLECTION, session: Optional[Session] = None) -> None:
"""
Initialize collection instance.
Parameters:
connection (DBusConnection): Active D-Bus connection
collection_path (str): D-Bus object path for the collection
session (Session, optional): Encryption session
"""
# Lock/Unlock Operations
def is_locked(self) -> bool:
"""Returns True if collection is locked, False otherwise."""
def ensure_not_locked(self) -> None:
"""Raises LockedException if collection is locked."""
def unlock(self) -> bool:
"""
Requests unlocking the collection.
Returns:
bool: False if successfully unlocked, True if prompt dismissed
Raises:
SecretServiceNotAvailableException: If Secret Service unavailable
"""
def lock(self) -> None:
"""Locks the collection."""
# Collection Management
def delete(self) -> None:
"""
Deletes the collection and all items inside it.
Raises:
LockedException: If collection is locked
PromptDismissedException: If user dismisses deletion prompt
"""
def get_label(self) -> str:
"""Returns the collection label."""
def set_label(self, label: str) -> None:
"""
Sets collection label.
Parameters:
label (str): New collection label
Raises:
LockedException: If collection is locked
"""
# Item Operations
def get_all_items(self) -> Iterator[Item]:
"""Returns a generator of all items in the collection."""
def search_items(self, attributes: Dict[str, str]) -> Iterator[Item]:
"""
Returns items matching the given attributes.
Parameters:
attributes (Dict[str, str]): Key-value pairs to match
Returns:
Iterator[Item]: Generator yielding matching items
"""
def create_item(self, label: str, attributes: Dict[str, str], secret: bytes,
replace: bool = False, content_type: str = 'text/plain') -> Item:
"""
Creates a new secret item in the collection.
Parameters:
label (str): Human-readable item name
attributes (Dict[str, str]): Key-value attributes for searching
secret (bytes): Secret data to store
replace (bool): Whether to replace existing item with same attributes
content_type (str): MIME type of secret data
Returns:
Item: Newly created item instance
Raises:
LockedException: If collection is locked
PromptDismissedException: If user dismisses creation prompt
"""Usage Examples:
import secretstorage
# Get default collection
connection = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(connection)
# Create a new collection
new_collection = secretstorage.create_collection(
connection,
"My App Secrets",
"myapp"
)
# Work with locked collections
if collection.is_locked():
dismissed = collection.unlock()
if dismissed:
print("User dismissed unlock prompt")
else:
print("Collection unlocked successfully")
# Create an item in the collection
item = collection.create_item(
"Database Password",
{"application": "myapp", "server": "db.example.com"},
b"super_secret_password"
)Types
from typing import Dict, Iterator, Optional
# From secretstorage.dhcrypto
class Session:
"""Cryptographic session for secure data transfer."""Install with Tessl CLI
npx tessl i tessl/pypi-secretstorage