### ItemNotFoundException

Source: https://secretstorage.readthedocs.io/en/latest/exceptions.html

Raised when an item does not exist or has been deleted. Includes an example of how to handle this exception.

```APIDOC
## ItemNotFoundException

### Description
Raised when an item does not exist or has been deleted.

### Example Usage
```python
import secretstorage

connection = secretstorage.dbus_init()
item_path = '/not/existing/path'
try:
    item = secretstorage.Item(connection, item_path)
except secretstorage.ItemNotFoundException:
    print('Item not found!')
```
```

--------------------------------

### dbus_init

Source: https://secretstorage.readthedocs.io/en/latest/_modules/secretstorage.html

Initializes a connection to the session bus for SecretStorage operations.

```APIDOC
## dbus_init()

### Description
Returns a new connection to the session bus, an instance of jeepney's DBusConnection class. This connection is required for various SecretStorage functions.

### Returns
- **connection** (DBusConnection) - A connection object to the session bus.

### Exceptions
- **SecretServiceNotAvailableException** - Raised if the D-Bus session bus address is unset or if the connection fails.
```

--------------------------------

### Initialize D-Bus Connection

Source: https://secretstorage.readthedocs.io/en/latest/_modules/secretstorage.html

Establishes a connection to the session bus for SecretStorage operations. Use a context manager to ensure the socket is closed properly.

```python
from contextlib import closing
with closing(dbus_init()) as conn:
    collection = secretstorage.get_default_collection(conn)
    items = collection.search_items({'application': 'myapp'})
```

```python
def dbus_init() -> DBusConnection:
    """Returns a new connection to the session bus, instance of
    jeepney's :class:`DBusConnection` class. This connection can
    then be passed to various SecretStorage functions, such as
    :func:`~secretstorage.collection.get_default_collection`.

    .. warning::
       The D-Bus socket will not be closed automatically. You can
       close it manually using the :meth:`DBusConnection.close` method,
       or you can use the :class:`contextlib.closing` context manager:

       .. code-block:: python

          from contextlib import closing
          with closing(dbus_init()) as conn:
              collection = secretstorage.get_default_collection(conn)
              items = collection.search_items({'application': 'myapp'})

       However, you will not be able to call any methods on the objects
       created within the context after you leave it.

    .. versionchanged:: 3.0
       Before the port to Jeepney, this function returned an
       instance of :class:`dbus.SessionBus` class.

    .. versionchanged:: 3.1
       This function no longer accepts any arguments.
    """
    try:
        connection = open_dbus_connection()
        add_match_rules(connection)
        return connection
    except KeyError as ex:
        # os.environ['DBUS_SESSION_BUS_ADDRESS'] may raise it
        reason = f"Environment variable {ex.args[0]} is unset"
        raise SecretServiceNotAvailableException(reason) from ex
    except (ConnectionError, ValueError) as ex:
        raise SecretServiceNotAvailableException(str(ex)) from ex
```

--------------------------------

### secretstorage.dbus_init

Source: https://secretstorage.readthedocs.io/en/latest

Initializes the D-Bus connection required for SecretStorage operations.

```APIDOC
## FUNCTION secretstorage.dbus_init()

### Description
Initializes a new connection to the session bus, returning an instance of jeepney's DBusConnection class.

### Returns
- **DBusConnection** - A connection object used for subsequent SecretStorage function calls.
```

--------------------------------

### SecretStorage Initialization

Source: https://secretstorage.readthedocs.io/en/latest/_sources/index.rst.txt

Functions for initializing the D-Bus connection and checking for Secret Service availability.

```APIDOC
## SecretStorage Initialization API

### Description
Provides functions to initialize the D-Bus connection and check if the Secret Service daemon is available.

### Methods

#### `secretstorage.dbus_init()`

##### Description
Initializes the D-Bus connection required for SecretStorage operations.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus initialization)

#### `secretstorage.check_service_availability()`

##### Description
Checks if the Secret Service daemon is available without attempting to call its methods.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus check)

### Request Example
```python
import secretstorage

# Initialize D-Bus connection
connection = secretstorage.dbus_init()

# Check for service availability
is_available = secretstorage.check_service_availability()
print(f"Secret Service available: {is_available}")
```

### Response
#### Success Response (200)
- `connection` (object) - A D-Bus connection object.
- `is_available` (boolean) - True if the service is available, False otherwise.

#### Response Example
```json
{
  "connection": "<dbus.Bus object at 0x...>",
  "is_available": true
}
```
```

--------------------------------

### Handle ItemNotFoundException

Source: https://secretstorage.readthedocs.io/en/latest/exceptions.html

Demonstrates catching an ItemNotFoundException when attempting to access a non-existent item path.

```python
>>> import secretstorage
>>> connection = secretstorage.dbus_init()
>>> item_path = '/not/existing/path'
>>> try:
...     item = secretstorage.Item(connection, item_path)
... except secretstorage.ItemNotFoundException:
...     print('Item not found!')
...
Item not found!
```

--------------------------------

### Initialize D-Bus Connection with Context Manager

Source: https://secretstorage.readthedocs.io/en/latest

Initializes a D-Bus connection for SecretStorage operations. Use `contextlib.closing` to ensure the connection is automatically closed after use. This connection can be passed to other SecretStorage functions.

```python
from contextlib import closing
with closing(dbus_init()) as conn:
    collection = secretstorage.get_default_collection(conn)
    items = collection.search_items({'application': 'myapp'})
```

--------------------------------

### Create a new item in the default collection

Source: https://secretstorage.readthedocs.io/en/latest/_sources/index.rst.txt

Initializes a D-Bus connection and creates a new secret item within the default collection using specified attributes.

```python
>>> import secretstorage
>>> connection = secretstorage.dbus_init()
>>> collection = secretstorage.get_default_collection(connection)
>>> attributes = {'application': 'myapp', 'another attribute':
...     'another value'}
>>> item = collection.create_item('My first item', attributes,
...     b'pa$$word')
```

--------------------------------

### Check Secret Service Availability

Source: https://secretstorage.readthedocs.io/en/latest/_modules/secretstorage.html

Verifies if the Secret Service daemon is running or available for activation.

```python
def check_service_availability(connection: DBusConnection) -> bool:
    """Returns True if the Secret Service daemon is either running or
    available for activation via D-Bus, False otherwise.

    .. versionadded:: 3.2
    """
    from secretstorage.util import BUS_NAME
    proxy = Proxy(message_bus, connection)
    return (proxy.NameHasOwner(BUS_NAME)[0] == 1
            or BUS_NAME in proxy.ListActivatableNames()[0])
```

--------------------------------

### Collection Management Functions

Source: https://secretstorage.readthedocs.io/en/latest/collection.html

Functions for creating and retrieving collections, including default, session, and aliased collections.

```APIDOC
## Collection Functions

Provides functions for managing collections.

### Functions

#### `create_collection(_connection: DBusConnection, _label: str, _alias: str = '', _session: Session | None = None) -> Collection`

Creates a new `Collection` with a given label and alias. Requires user prompting. Raises `PromptDismissedException` if the prompt is dismissed.

#### `get_all_collections(_connection: DBusConnection) -> Iterator[Collection]`

Returns a generator that yields all available collections.

#### `get_any_collection(_connection: DBusConnection) -> Collection`

Returns a collection based on preference: default, session, or the first available.

#### `get_collection_by_alias(_connection: DBusConnection, _alias: str) -> Collection`

Retrieves a collection by its alias. Raises `ItemNotFoundException` if no collection with the specified alias exists.

#### `get_default_collection(_connection: DBusConnection, _session: Session | None = None) -> Collection`

Returns the default collection, creating it if it does not already exist.

#### `search_items(_connection: DBusConnection, _attributes: dict[str, str]) -> Iterator[Item]`

Searches for items across all collections that match the given attributes.
```

--------------------------------

### Retrieve item details

Source: https://secretstorage.readthedocs.io/en/latest/_sources/index.rst.txt

Accesses the label, attributes, and secret content of a previously created item.

```python
>>> item.get_label()
'My first item'
>>> item.get_attributes()
{'another attribute': 'another value', 'application': 'myapp'}
>>> item.get_secret()
b'pa$$word'
```

--------------------------------

### Lock and unlock collections

Source: https://secretstorage.readthedocs.io/en/latest/_sources/index.rst.txt

Demonstrates the synchronous API for locking and unlocking a collection, which may block if user interaction is required.

```python
>>> collection.lock()
>>> collection.is_locked()
True
>>> collection.unlock()
>>> collection.is_locked()
False
```

--------------------------------

### secretstorage.util.exec_prompt

Source: https://secretstorage.readthedocs.io/en/latest/util.html

Executes a prompt in a blocking mode. This function is primarily for internal use and not intended for external applications.

```APIDOC
## exec_prompt

### Description
Executes the prompt in a blocking mode.

### Method
Not applicable (utility function)

### Endpoint
Not applicable (utility function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Keyword Parameters
* **_connection** (DBusConnection) - Required - The DBus connection object.
* **_prompt_path** (str) - Required - The path to the prompt.
* **timeout** (float | None) - Optional - The timeout in seconds for the operation. Added in version 3.5.

### Request Example
None (function call)

### Response
#### Success Response
- **dismissed** (bool) - True if the operation was dismissed, False otherwise.
- **result** (tuple) - A two-element tuple containing the signature and result.
  - For creating items and collections, `signature` is 'o' and `result` is a single object path.
  - For unlocking, `signature` is 'ao' and `result` is a list of object paths.

#### Response Example
```python
(False, ('o', '/org/example/item/1'))
```
```

--------------------------------

### check_service_availability

Source: https://secretstorage.readthedocs.io/en/latest/_modules/secretstorage.html

Checks if the Secret Service daemon is available.

```APIDOC
## check_service_availability(connection)

### Description
Returns True if the Secret Service daemon is either running or available for activation via D-Bus, False otherwise.

### Parameters
- **connection** (DBusConnection) - Required - The active D-Bus connection object.

### Returns
- **available** (bool) - True if the service is available, False otherwise.
```

--------------------------------

### secretstorage.check_service_availability

Source: https://secretstorage.readthedocs.io/en/latest

Checks if the Secret Service daemon is available on the system.

```APIDOC
## FUNCTION secretstorage.check_service_availability(connection)

### Description
Verifies if the Secret Service daemon is running or available for activation via D-Bus.

### Parameters
- **connection** (DBusConnection) - Required - The active D-Bus connection.

### Returns
- **bool** - True if the service is available, False otherwise.
```

--------------------------------

### Create a New Secret Item

Source: https://secretstorage.readthedocs.io/en/latest

Creates a new secret item in the default collection. Requires an initialized D-Bus connection and specifies the item's label, attributes, and the secret content as bytes.

```python
import secretstorage
connection = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(connection)
attributes = {'application': 'myapp', 'another attribute':
    'another value'}
item = collection.create_item('My first item', attributes,
    b'pa$$word')
```

--------------------------------

### Collection Class Methods

Source: https://secretstorage.readthedocs.io/en/latest/collection.html

Methods available for interacting with a specific collection, such as creating items, deleting the collection, checking its lock status, and managing its label.

```APIDOC
## Collection Class

Represents a collection where secret items are stored.

### Methods

#### `create_item(_label: str, _attributes: dict[str, str], _secret: bytes, _replace: bool = False, _content_type: str = 'text/plain') -> Item`

Creates a new `Item` with the given label, attributes, and secret. Can replace an existing item and set the content type.

#### `delete() -> None`

Deletes the collection and all items within it.

#### `ensure_not_locked() -> None`

Raises `LockedException` if the collection is currently locked.

#### `get_all_items() -> Iterator[Item]`

Returns a generator yielding all items stored in the collection.

#### `get_label() -> str`

Retrieves and returns the label of the collection.

#### `is_locked() -> bool`

Checks if the collection is locked, returning `True` if it is, `False` otherwise.

#### `lock() -> None`

Locks the collection, preventing modifications until unlocked.

#### `search_items(_attributes: dict[str, str]) -> Iterator[Item]`

Searches for items within the collection that match the provided attributes dictionary.

#### `set_label(_label: str) -> None`

Updates the label of the collection to the specified string.

#### `unlock(_timeout: float | None = None) -> bool`

Requests to unlock the collection. Returns `False` on successful unlocking, `True` if the prompt was dismissed. Raises `TimeoutError` if the timeout is reached.
```

--------------------------------

### SecretStorage Exceptions

Source: https://secretstorage.readthedocs.io/en/latest/genindex.html

Custom exceptions raised by the SecretStorage library.

```APIDOC
## Exceptions

### Description
Custom exceptions that may be raised by the SecretStorage library during operations.

### Exception Types
- `ItemNotFoundException`
- `LockedException`
- `PromptDismissedException`
- `SecretServiceNotAvailableException`
- `SecretStorageException`
```

--------------------------------

### SecretStorage Item Methods

Source: https://secretstorage.readthedocs.io/en/latest/genindex.html

Methods related to managing individual items within collections.

```APIDOC
## Item Methods

### Description
Methods for interacting with and managing individual items (secrets) within collections.

### Methods
- `create_item()`
- `delete()`
- `ensure_not_locked()`
- `get_attributes()`
- `get_created()`
- `get_label()`
- `get_modified()`
- `get_secret()`
- `get_secret_content_type()`
- `is_locked()`
- `set_attributes()`
- `set_label()`
- `set_secret()`
- `unlock()`

### Class
`secretstorage.item.Item`
```

--------------------------------

### Lock and Unlock Collection

Source: https://secretstorage.readthedocs.io/en/latest

Demonstrates locking and unlocking a collection synchronously. The `unlock()` method will block if user interaction is required. `is_locked()` checks the current state.

```python
collection.lock()
collection.is_locked()
collection.unlock()
collection.is_locked()
```

--------------------------------

### Collection Operations

Source: https://secretstorage.readthedocs.io/en/latest/_sources/index.rst.txt

Functions for interacting with collections, including creating items, locking, and unlocking.

```APIDOC
## Collection API

### Description
APIs for managing collections and their items, including creating, retrieving, and locking/unlocking.

### Methods

#### `secretstorage.get_default_collection(connection)`

##### Description
Retrieves the default collection from the D-Bus connection.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

#### `collection.create_item(label, attributes, secret)`

##### Description
Creates a new secret item within the collection.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

##### Parameters

###### Request Body
- **label** (string) - Required - The label for the secret item.
- **attributes** (dict) - Required - A dictionary of attributes for the item.
- **secret** (bytes) - Required - The secret data to store.

#### `collection.lock()`

##### Description
Locks the collection, requiring a password to unlock.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

#### `collection.unlock()`

##### Description
Unlocks the collection. This call may block if user interaction is required.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

#### `collection.is_locked()`

##### Description
Checks if the collection is currently locked.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

### Request Example
```python
import secretstorage

connection = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(connection)

attributes = {'application': 'myapp', 'another attribute': 'another value'}
item = collection.create_item('My first item', attributes, b'pa$$word')

print(f"Item label: {item.get_label()}")
print(f"Item attributes: {item.get_attributes()}")
print(f"Item secret: {item.get_secret()}")

collection.lock()
print(f"Is locked: {collection.is_locked()}")

collection.unlock()
print(f"Is locked: {collection.is_locked()}")
```

### Response
#### Success Response (200)
- `item` (object) - The created secret item object.
- `is_locked` (boolean) - The locked status of the collection.

#### Response Example
```json
{
  "item_label": "My first item",
  "item_attributes": {"another attribute": "another value", "application": "myapp"},
  "item_secret": "pa$$word",
  "is_locked": false
}
```
```

--------------------------------

### SecretStorage Utility Functions

Source: https://secretstorage.readthedocs.io/en/latest/genindex.html

Utility functions provided by the SecretStorage library.

```APIDOC
## Utility Functions

### Description
Additional utility functions available in the SecretStorage library.

### Functions
- `dbus_init()`
- `exec_prompt()`
- `format_secret()`
- `unlock_objects()`
```

--------------------------------

### SecretStorageException

Source: https://secretstorage.readthedocs.io/en/latest/exceptions.html

The base class for all exceptions raised by the secretstorage library.

```APIDOC
## SecretStorageException

### Description
All exceptions derive from this class.
```

--------------------------------

### Retrieve Item Details

Source: https://secretstorage.readthedocs.io/en/latest

Retrieves the label, attributes, and secret from a previously created or retrieved secret item. The secret is returned as bytes.

```python
item.get_label()
item.get_attributes()
item.get_secret()
```

--------------------------------

### SecretStorage Collection Methods

Source: https://secretstorage.readthedocs.io/en/latest/genindex.html

Methods related to managing collections of secrets.

```APIDOC
## Collection Methods

### Description
Methods for interacting with and managing collections of secrets.

### Methods
- `create_collection()`
- `get_all_collections()`
- `get_any_collection()`
- `get_collection_by_alias()`
- `get_default_collection()`
- `search_items()`
- `set_label()`
- `lock()`
- `unlock()`
- `is_locked()`

### Class
`secretstorage.collection.Collection`
```

--------------------------------

### Item Management API

Source: https://secretstorage.readthedocs.io/en/latest/item.html

Methods for interacting with and modifying secret items.

```APIDOC
## DELETE /item/delete

### Description
Deletes the current secret item.

### Method
DELETE

## GET /item/attributes

### Description
Returns the attributes associated with the item.

### Method
GET

### Response
- **attributes** (dict[str, str]) - Dictionary of item attributes.

## GET /item/secret

### Description
Retrieves the secret content of the item.

### Method
GET

### Response
- **secret** (bytes) - The item secret as a bytestring.

## POST /item/attributes

### Description
Updates the attributes for the item.

### Method
POST

### Parameters
#### Request Body
- **attributes** (dict[str, str]) - Required - The new attributes dictionary.

## POST /item/secret

### Description
Sets the secret content and optionally the content type for the item.

### Method
POST

### Parameters
#### Request Body
- **secret** (bytes) - Required - The secret content.
- **content_type** (str) - Optional - The content type of the secret (default: 'text/plain').

## POST /item/unlock

### Description
Requests unlocking the item or its parent collection.

### Method
POST

### Parameters
#### Request Body
- **timeout** (float) - Optional - Timeout in seconds for the unlock prompt.
```

--------------------------------

### Check Secret Service Availability

Source: https://secretstorage.readthedocs.io/en/latest

Checks if the Secret Service daemon is running or can be activated via D-Bus. This function returns a boolean indicating availability without attempting to call any service methods.

```python
secretstorage.check_service_availability(_connection : DBusConnection_)
```

--------------------------------

### Item Operations

Source: https://secretstorage.readthedocs.io/en/latest/_sources/index.rst.txt

Functions for retrieving information about a stored secret item.

```APIDOC
## Item API

### Description
APIs for retrieving details of a secret item stored within a collection.

### Methods

#### `item.get_label()`

##### Description
Retrieves the label of the secret item.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

#### `item.get_attributes()`

##### Description
Retrieves the attributes associated with the secret item.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

#### `item.get_secret()`

##### Description
Retrieves the secret data stored in the item.

##### Method
`CALL`

##### Endpoint
N/A (Internal D-Bus call)

### Request Example
```python
import secretstorage

connection = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(connection)
attributes = {'application': 'myapp'}
item = collection.create_item('My test item', attributes, b'secret123')

label = item.get_label()
retrieved_attributes = item.get_attributes()
secret = item.get_secret()

print(f"Label: {label}")
print(f"Attributes: {retrieved_attributes}")
print(f"Secret: {secret}")
```

### Response
#### Success Response (200)
- `label` (string) - The label of the item.
- `attributes` (dict) - The attributes of the item.
- `secret` (bytes) - The secret data.

#### Response Example
```json
{
  "label": "My test item",
  "attributes": {"application": "myapp"},
  "secret": "secret123"
}
```
```

--------------------------------

### SecretServiceNotAvailableException

Source: https://secretstorage.readthedocs.io/en/latest/exceptions.html

Raised by `Item` or `Collection` constructors, or by other functions in the `secretstorage.collection` module, when the Secret Service API is not available.

```APIDOC
## SecretServiceNotAvailableException

### Description
Raised by `Item` or `Collection` constructors, or by other functions in the `secretstorage.collection` module, when the Secret Service API is not available.
```

--------------------------------

### LockedException

Source: https://secretstorage.readthedocs.io/en/latest/exceptions.html

Raised when an action cannot be performed because the collection is locked. Use `is_locked()` to check if the collection is locked, and `unlock()` to unlock it.

```APIDOC
## LockedException

### Description
Raised when an action cannot be performed because the collection is locked. Use `is_locked()` to check if the collection is locked, and `unlock()` to unlock it.
```

--------------------------------

### PromptDismissedException

Source: https://secretstorage.readthedocs.io/en/latest/exceptions.html

Raised when a prompt was dismissed by the user. Added in version 3.1.

```APIDOC
## PromptDismissedException

### Description
Raised when a prompt was dismissed by the user.

### Version Added
3.1
```

--------------------------------

### secretstorage.util.format_secret

Source: https://secretstorage.readthedocs.io/en/latest/util.html

Formats a secret to be compatible with the Secret Service API. This is an internal utility function.

```APIDOC
## format_secret

### Description
Formats secret to make possible to pass it to the Secret Service API.

### Method
Not applicable (utility function)

### Endpoint
Not applicable (utility function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Arguments
* **_session** (Session) - Required - The session object.
* **_secret** (bytes) - Required - The secret data in bytes.
* **_content_type** (str) - Required - The content type of the secret.

### Request Example
None (function call)

### Response
#### Success Response
- **formatted_secret** (tuple[str, bytes, bytes, str]) - A tuple containing the formatted secret components.

#### Response Example
```python
('text/plain', b'\x01\x02\x03', b'\x04\x05\x06', 'application/octet-stream')
```
```

--------------------------------

### secretstorage.util.unlock_objects

Source: https://secretstorage.readthedocs.io/en/latest/util.html

Requests unlocking of specified objects. This function is intended for internal use.

```APIDOC
## unlock_objects

### Description
Requests unlocking objects specified in paths.

### Method
Not applicable (utility function)

### Endpoint
Not applicable (utility function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Keyword Parameters
* **_connection** (DBusConnection) - Required - The DBus connection object.
* **_paths** (list[str]) - Required - A list of object paths to unlock.
* **timeout** (float | None) - Optional - The timeout in seconds for the operation. Added in version 3.5.

### Request Example
None (function call)

### Response
#### Success Response (bool)
- **dismissed** (bool) - True if the operation was dismissed, False otherwise.

#### Response Example
```python
False
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.