Python Keyring

https://keyring.readthedocs.io/en/latest
Admin
A Python library that provides secure access to system keyring services for storing and retrieving...
Tokens:17,453
Snippets:281
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and verify Keyring on Ubuntu 16.04

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Commands to install dependencies, set up a virtual environment, and verify password storage functionality.

```bash
$ sudo apt install python3-venv libdbus-glib-1-dev
$ cd /tmp
$ pyvenv py3
$ source py3/bin/activate
$ pip install -U pip
$ pip install secretstorage dbus-python
$ pip install keyring
$ python
>>> import keyring
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8>
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'
```

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

### Keyring Configuration File Example

Source: https://keyring.readthedocs.io/en/latest?badge=latest

An example configuration file content for keyring, specifying a default keyring backend and an additional path to search for modules. This is used to customize keyring's behavior.

```ini
[backend]
default-keyring=simplekeyring.SimpleKeyring
keyring-path=demo
```

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

### Install and Use Keyring on Ubuntu 16.04

Source: https://keyring.readthedocs.io/en/latest?badge=latest

This snippet demonstrates the complete process of installing and using the Keyring library in a virtual environment on Ubuntu 16.04, including setting and retrieving a password.

```bash
$ sudo apt install python3-venv libdbus-glib-1-dev
$ cd /tmp
$ pyvenv py3
$ source py3/bin/activate
$ pip install -U pip
$ pip install secretstorage dbus-python
$ pip install keyring
$ python
>>> import keyring
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8>
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'
```

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

### Install Keyring with Completion Extra

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Installs the keyring library with the 'completion' extra, which is required for shell tab completion functionality.

```bash
$ pip install 'keyring[completion]'
```

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

### Install Completion Extra

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Install the completion extra to enable shell tab completion support.

```bash
$ pip install 'keyring[completion]'
```

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

### Set and Get Password using Keyring API

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Demonstrates the basic usage of the keyring library to set and retrieve a password for a given system and username. Ensure the keyring library is installed.

```python
import keyring
keyring.set_password("system", "username", "password")
keyring.get_password("system", "username")
```

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

### Configure keyring backend in keyringrc.cfg

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Example configuration for specifying a custom backend class and adding a module path to the search path.

```ini
[backend]
default-keyring=simplekeyring.SimpleKeyring
keyring-path=demo
```

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

### Display Keyring Command-Line Help

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Shows how to display the help message for the keyring command-line utility. This command is installed with the keyring package.

```bash
$ keyring --help
```

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

### Install and verify Keyring in a Docker container

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Steps to configure a privileged Ubuntu 18.04 container, initialize a D-Bus session, and unlock the keyring daemon.

```bash
docker run -it -d --privileged ubuntu:18.04

$ apt-get update
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # source a virtual environment to avoid polluting your system
$ pip3 install --upgrade pip
$ pip3 install keyring
$ dbus-run-session -- sh # this will drop you into a new D-bus shell
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # unlock the system's keyring

$ python
>>> import keyring
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8>
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'
```

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

### Install and Use Keyring in a Docker Container

Source: https://keyring.readthedocs.io/en/latest?badge=latest

This snippet shows the steps to install and use the Keyring library with the SecretService backend within a Docker container on Ubuntu 18.04, including unlocking the system's keyring.

```bash
docker run -it -d --privileged ubuntu:18.04

$ apt-get update
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # source a virtual environment to avoid polluting your system
$ pip3 install --upgrade pip
$ pip3 install keyring
$ dbus-run-session -- sh # this will drop you into a new D-bus shell
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # unlock the system's keyring

$ python
>>> import keyring
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring object at 0x7f9b9c971ba8>
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'
```

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

### SchemeSelectable Backend Query Examples

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Demonstrates how the SchemeSelectable backend queries credentials with different schemes and parameters. It shows the flexibility in handling service and username configurations.

```python
>>> backend = SchemeSelectable()
>>> backend._query('contoso', 'alice')
{'username': 'alice', 'service': 'contoso'}
>>> backend._query('contoso')
{'service': 'contoso'}
>>> backend.scheme = 'KeePassXC'
>>> backend._query('contoso', 'alice')
{'UserName': 'alice', 'Title': 'contoso'}
>>> backend._query('contoso', 'alice', foo='bar')
{'UserName': 'alice', 'Title': 'contoso', 'foo': 'bar'}
```

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

### Generate Shell Completions

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Generate and install shell completion scripts for bash, zsh, or tcsh.

```bash
$ keyring --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring
$ keyring --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring
$ keyring --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
```

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

### Get Current Keyring Backend

Source: https://keyring.readthedocs.io/en/latest/index.html

Retrieves the currently active keyring backend implementation.

```python
keyring.get_keyring() -> KeyringBackend
```

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

### Keyring Backend - Get Viable Backends

Source: https://keyring.readthedocs.io/en/latest/index.html

Class method to return an iterator over all subclasses of KeyringBackend that are considered viable for use.

```python
classmethod get_viable_backends() -> filter[type[KeyringBackend]]
```

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

### Class Property Example

Source: https://keyring.readthedocs.io/en/latest/index.html

Illustrates the usage of a class property, which behaves like a property but operates at the class level. It supports getters and setters.

```python
import classproperty

class X:
    val = None
    @classproperty
    def foo(cls):
        return cls.val
    @foo.setter
    def foo(cls, val):
        cls.val = val

# Example usage:
# X.foo = 3
# X.foo
# 3
# x = X()
# x.foo
# 3
# X.foo = 4
# x.foo
# 4
```

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

### Exception Trap Example

Source: https://keyring.readthedocs.io/en/latest/index.html

Demonstrates using the ExceptionTrap decorator to catch specific exceptions and return a boolean indicating success or failure.

```python
import functools

class ExceptionTrap:
    def __init__(self, exc_type):
        self.exc_type = exc_type

    def __call__(self, func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            try:
                func(*args, **kwargs)
                return True
            except self.exc_type:
                return False
        return wrapper


# Example usage:
# @ExceptionTrap(ValueError).passes
# def fail():
#     raise ValueError('failed')

# fail()
# False
```

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

### Classproperty usage with setter

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Illustrates the usage of the classproperty decorator to create properties that behave like class attributes. This example shows how to define a getter and a setter for a classproperty, and how setting it on an instance affects the class.

```python
>>> class X(metaclass=classproperty.Meta):
...   val = None
...   @classproperty
...   def foo(cls):
...     return cls.val
...   @foo.setter
...   def foo(cls, val):
...     cls.val = val
>>> X.foo
>>> X.foo = 3
>>> X.foo
3
>>> x = X()
>>> x.foo
3
>>> X.foo = 4
>>> x.foo
4

```

```python
>>> x.foo = 5
>>> x.foo
5
>>> X.foo
5
>>> vars(x)
{}
>>> X().foo
5

```

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

### Get Password using Keyring Command-Line

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves a previously set password for a username in a specific system using the keyring command-line utility.

```bash
$ keyring get system username
password
```

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

### Generate Bash Shell Completions

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Generates bash shell completion scripts for the keyring command and prints them to standard output. This output can be redirected to a file for installation.

```bash
$ keyring --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring
```

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

### Keyring Backend Interface - Get Password

Source: https://keyring.readthedocs.io/en/latest/index.html

Abstract method definition for retrieving a password from a keyring backend. Implementations must provide this functionality.

```python
abstractmethod get_password(_service : str_, _username : str_) -> str | None
```

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

### Get Credential

Source: https://keyring.readthedocs.io/en/latest/index.html

Retrieves a Credential object (containing username and password) for the specified service. The username can be optional.

```python
keyring.get_credential(_service_name : str_, _username : str | None_) -> Credential | None
```

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

### Generate Zsh Shell Completions

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Generates zsh shell completion scripts for the keyring command and prints them to standard output. This output can be redirected to a file for installation.

```bash
$ keyring --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring
```

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

### Get Password

Source: https://keyring.readthedocs.io/en/latest/index.html

Retrieves the password for a given username and service name. Returns None if the password is not found.

```python
keyring.get_password(_service_name : str_, _username : str_) -> str | None
```

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

### Legacy classproperty usage without metaclass

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Illustrates the legacy behavior of classproperty when the metaclass is not explicitly specified. This example highlights the difference in behavior, particularly when setting properties on instances.

```python
>>> class X:
...   val = None
...   @classproperty
...   def foo(cls):
...     return cls.val
...   @foo.setter
...   def foo(cls, val):
...     cls.val = val
>>> X.foo
>>> X.foo = 3
>>> X.foo
3
>>> x = X()
>>> x.foo
3
>>> X.foo = 4
>>> x.foo
4

```

```python
>>> x.foo = 5
>>> x.foo
5
>>> X.foo  # should be 5
4
>>> vars(x)  # should be empty
{'foo': 5}
>>> X().foo  # should be 5
4

```

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

### Get Password using Keyring Module

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves a previously set password for a username in a specific system by invoking the keyring module directly from Python.

```bash
$ python -m keyring get system username
password
```

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

### Generate Tcsh Shell Completions

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Generates tcsh shell completion scripts for the keyring command and prints them to standard output. This output can be redirected to a file for installation.

```bash
$ keyring --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
```

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

### Keyring Backend Interface - Get Credential

Source: https://keyring.readthedocs.io/en/latest/index.html

Abstract method definition for retrieving a Credential object for a given service and optional username. Callers must use the returned username.

```python
get_credential(_service : str_, _username : str | None_) -> Credential | None
```

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

### Example of using ExceptionTrap decorator

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Demonstrates how to use the ExceptionTrap decorator to catch specific exceptions and return a boolean indicating success or failure. This is useful for functions that are expected to fail under certain conditions.

```python
>>> @ExceptionTrap(ValueError).passes
... def fail():
...     raise ValueError('failed')

```

```python
>>> fail()
False

```

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

### Initialize Backend with Recommended Keyrings

Source: https://keyring.readthedocs.io/en/latest/history.html

Limits backend initialization to only recommended keyrings with a priority of 1 or greater. Use this to ensure only preferred backends are loaded.

```python
keyring.core.init_backend(limit=keyring.core.recommended)

```

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

### Define and Use a Custom Keyring Backend

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Demonstrates how to define a custom keyring backend by extending `keyring.backend.KeyringBackend` and then setting it as the active keyring for the library.

```python
import keyring.backend

class TestKeyring(keyring.backend.KeyringBackend):
    """A test keyring which always outputs the same password
    """
    priority = 1

    def set_password(self, servicename, username, password):
        pass

    def get_password(self, servicename, username):
        return "password from TestKeyring"

    def delete_password(self, servicename, username):
        pass

# set the keyring for keyring lib
keyring.set_keyring(TestKeyring())

# invoke the keyring lib
try:
    keyring.set_password("demo-service", "tarek", "passexample")
    print("password stored successfully")
except keyring.errors.PasswordSetError:
    print("failed to store password")
print("password", keyring.get_password("demo-service", "tarek"))

```

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

### Invoke Keyring from Command Line

Source: https://keyring.readthedocs.io/en/latest/history.html

Demonstrates how to invoke the Keyring library directly from the command line using the python -m keyring command.

```python
python -m keyring

```

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

### Set Password using Keyring Command-Line

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Demonstrates setting a password for a username in a specific system using the keyring command-line utility. You will be prompted to enter the password.

```bash
$ keyring set system username
Password for 'username' in 'system':
```

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

### keyring.core.init_backend

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Loads a detected keyring backend, optionally filtered by a provided callable.

```APIDOC
## keyring.core.init_backend

### Description
Load a detected backend.

### Method
Not specified (assumed to be a function call).

### Parameters
#### Path Parameters
- **_limit** (Callable[[KeyringBackend], bool] | None) - Optional - A callable to filter detected backends.
```

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

### Display Keyring Module Help

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Shows how to display the help message for the keyring module when invoked as an executable package from Python.

```bash
$ python -m keyring --help
```

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

### keyring.core.init_backend

Source: https://keyring.readthedocs.io/en/latest/index.html

Loads a detected keyring backend, optionally filtering by a provided limit function. This function helps in initializing the appropriate backend for credential operations.

```APIDOC
## keyring.core.init_backend

### Description
Load a detected backend.

### Method
`POST` (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
#### Request Body
None

### Parameters
*   **_limit** (Callable[[KeyringBackend], bool] | None) - An optional callable function to filter backends. If provided, only backends for which this function returns True will be considered.
```

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

### keyring.core.recommended

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Checks if a given backend is recommended.

```APIDOC
## keyring.core.recommended

### Description
Checks if a backend is recommended.

### Method
Not specified (assumed to be a function call).

### Parameters
#### Path Parameters
- **_backend_** (KeyringBackend) - Required - The backend to check.
```

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

### Basic Password Management

Source: https://keyring.readthedocs.io/en/latest/index.html

Demonstrates the fundamental usage of keyring for setting and retrieving passwords programmatically. Ensure the 'keyring' library is imported.

```python
>>> import keyring
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'
```

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

### Set Password using Keyring Module

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Demonstrates setting a password for a username in a specific system by invoking the keyring module directly from Python. You will be prompted to enter the password.

```bash
$ python -m keyring set system username
Password for 'username' in 'system':
```

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

### Select Schemes with SchemeSelectable

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Demonstrates how to use SchemeSelectable to map service and username fields to different naming conventions based on the selected scheme.

```python
>>> backend = SchemeSelectable()
>>> backend._query('contoso', 'alice')
{'username': 'alice', 'service': 'contoso'}
>>> backend._query('contoso')
{'service': 'contoso'}
>>> backend.scheme = 'KeePassXC'
>>> backend._query('contoso', 'alice')
{'UserName': 'alice', 'Title': 'contoso'}
>>> backend._query('contoso', 'alice', foo='bar')
{'UserName': 'alice', 'Title': 'contoso', 'foo': 'bar'}
```

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

### Set OS X Keyring Store to 'internet'

Source: https://keyring.readthedocs.io/en/latest/history.html

Demonstrates how to change the default store for the OS X Keyring backend to 'internet' and then set and retrieve a password.

```python
keys = keyring.backends.OS_X.Keyring()
keys.store = 'internet'
keys.set_password(system, user, password)
keys.get_password(system, user)
```

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

### Keyring Backend - Set Properties from Environment

Source: https://keyring.readthedocs.io/en/latest/index.html

Sets keyring properties based on environment variables prefixed with KEYRING_PROPERTY_.

```python
set_properties_from_env() -> None
```

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

### keyring.core.load_env

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Loads a keyring configuration from environment variables.

```APIDOC
## keyring.core.load_env

### Description
Load a keyring configured in the environment variable.

### Method
Not specified (assumed to be a function call).

### Parameters
None.

### Response
#### Success Response
- **KeyringBackend | None** - The loaded keyring backend, or None if not configured via environment variables.
```

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

### keyring.core.load_config

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Loads a keyring configuration from the system's configuration file.

```APIDOC
## keyring.core.load_config

### Description
Load a keyring using the config file in the config root.

### Method
Not specified (assumed to be a function call).

### Parameters
None.

### Response
#### Success Response
- **KeyringBackend | None** - The loaded keyring backend, or None if no configuration is found.
```

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

### Select Keyring Backend via Environment Variable

Source: https://keyring.readthedocs.io/en/latest/history.html

Allows selection of a specific keyring backend using the PYTHON_KEYRING_BACKEND environment variable. Useful for disabling keyring by setting it to keyring.backends.null.Keyring.

```bash
export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring
```

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

### keyring.backend.KeyringBackend.get_viable_backends

Source: https://keyring.readthedocs.io/en/latest/index.html

Class method to return all subclasses deemed viable as keyring backends.

```APIDOC
## get_viable_backends() -> filter[type[KeyringBackend]]

### Description
Return all subclasses deemed viable.

### Parameters
None

### Method
N/A (Class Method)

### Endpoint
N/A (Class Method)
```

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

### keyring.core.load_config

Source: https://keyring.readthedocs.io/en/latest/index.html

Loads a keyring backend configuration from the configuration file. This allows for persistent backend settings across application runs.

```APIDOC
## keyring.core.load_config

### Description
Load a keyring using the config file in the config root.

### Method
`GET` (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
None

### Response
#### Success Response
*   **KeyringBackend | None** - The loaded KeyringBackend instance from the config file, or None if no configuration is found.
```

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

### keyring.core.load_env

Source: https://keyring.readthedocs.io/en/latest/index.html

Loads a keyring backend configured via environment variables. This provides a flexible way to configure the keyring without modifying code.

```APIDOC
## keyring.core.load_env

### Description
Load a keyring configured in the environment variable.

### Method
`GET` (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
None

### Response
#### Success Response
*   **KeyringBackend | None** - The loaded KeyringBackend instance from environment variables, or None if not configured.
```

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

### Executable Package Usage

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Invoke the keyring functionality as an executable module via Python.

```bash
$ python -m keyring --help
$ python -m keyring set system username
Password for 'username' in 'system':
$ python -m keyring get system username
password
```

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

### keyring.backend.get_all_keyring

Source: https://keyring.readthedocs.io/en/latest/index.html

Returns a list of all implemented keyring backends that can be constructed without parameters. This is useful for discovering available credential management options.

```APIDOC
## keyring.backend.get_all_keyring

### Description
Return a list of all implemented keyrings that can be constructed without parameters.

### Method
`GET` (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
None

### Response
#### Success Response
*   **list[KeyringBackend]** - A list of available KeyringBackend instances.
```

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

### Keyring Backend - With Properties

Source: https://keyring.readthedocs.io/en/latest/index.html

A method or decorator that allows setting specific properties for a keyring backend instance.

```python
with_properties(_** kwargs: Any_) -> KeyringBackend
```

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

### Set Default OS X Keyring Store

Source: https://keyring.readthedocs.io/en/latest/history.html

Shows how to set the default store for all instances of the OS X Keyring backend to 'internet'.

```python
keyring.backends.OS_X.Keyring.store = 'internet'
```

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

### keyring.core.load_keyring

Source: https://keyring.readthedocs.io/en/latest/index.html

Loads a specific keyring backend by its fully-qualified name. This allows direct instantiation of a desired keyring implementation.

```APIDOC
## keyring.core.load_keyring

### Description
Load the specified keyring by name.

### Method
`GET` (conceptual, as this is a library function)

### Endpoint
N/A (Library function)

### Parameters
#### Request Body
None

### Parameters
*   **_keyring_name** (str) - The fully-qualified name of the keyring to load (e.g., 'keyring.backends.file.PlaintextKeyring').

### Response
#### Success Response
*   **KeyringBackend** - The loaded KeyringBackend instance.
```

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

### keyring.get_keyring

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves the currently configured keyring backend.

```APIDOC
## keyring.get_keyring

### Description
Gets the current keyring backend instance.

### Method
`keyring.get_keyring() → KeyringBackend`

### Returns
`KeyringBackend` - The current keyring backend.
```

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

### keyring.get_keyring

Source: https://keyring.readthedocs.io/en/latest/index.html

Retrieves the currently configured keyring backend.

```APIDOC
## get_keyring() -> KeyringBackend

### Description
Get current keyring backend.

### Parameters
None

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)
```

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

### Disabling Keyring and Handling Errors

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Shows how to disable the current keyring and demonstrates the expected RuntimeError when attempting to disable it again.

```python
>>> fs = getfixture('fs')
>>> disable()
>>> disable()
Traceback (most recent call last):
... 
RuntimeError: Refusing to overwrite...
```

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

### Command-line Utility Usage

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Manage passwords directly from the terminal using the keyring command.

```bash
$ keyring --help
$ keyring set system username
Password for 'username' in 'system':
$ keyring get system username
password
```

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

### EnvironCredential Equality Comparison

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Illustrates the equality comparison for EnvironCredential objects. Two credentials are equal if their environment variable names for user and password match.

```python
>>> e1 = EnvironCredential('a', 'b')
>>> e2 = EnvironCredential('a', 'b')
>>> e3 = EnvironCredential('a', 'c')
>>> e1 == e2
True
>>> e2 == e3
False
```

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

### keyring.backend.get_all_keyring

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Returns a list of all implemented keyrings that can be constructed without parameters.

```APIDOC
## keyring.backend.get_all_keyring

### Description
Return a list of all implemented keyrings that can be constructed without parameters.

### Method
Not specified (assumed to be a function call).

### Parameters
None.

### Response
#### Success Response
- **list[KeyringBackend]** - A list of constructible KeyringBackend instances.
```

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

### Set Keyring Backend

Source: https://keyring.readthedocs.io/en/latest/index.html

Sets a specific keyring backend implementation to be used.

```python
keyring.set_keyring(_keyring : KeyringBackend_) -> None
```

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

### keyring.core.load_keyring

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Loads a specific keyring by its fully-qualified name.

```APIDOC
## keyring.core.load_keyring

### Description
Load the specified keyring by name (a fully-qualified name to the keyring, such as ‘keyring.backends.file.PlaintextKeyring’)

### Method
Not specified (assumed to be a function call).

### Parameters
#### Path Parameters
- **_keyring_name** (str) - Required - The fully-qualified name of the keyring to load.
```

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

### keyring.set_keyring

Source: https://keyring.readthedocs.io/en/latest/index.html

Sets the current keyring backend to a new instance.

```APIDOC
## set_keyring(_keyring : KeyringBackend_) -> None

### Description
Set current keyring backend.

### Parameters
#### Path Parameters
- **_keyring** (KeyringBackend) - Required - The KeyringBackend instance to set as the current backend.

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)
```

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

### keyring.core.get_keyring

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves the currently active keyring backend.

```APIDOC
## keyring.core.get_keyring

### Description
Get current keyring backend.

### Method
Not specified (assumed to be a function call).

### Parameters
None.

### Response
#### Success Response
- **KeyringBackend** - The current keyring backend instance.
```

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

### Classproperty with classmethod and staticmethod

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Shows how to combine classproperty with classmethod and staticmethod. This allows for properties that can be accessed and called at the class level, providing flexibility in defining class-level behaviors.

```python
>>> class Static(metaclass=classproperty.Meta):
...   @classproperty
...   @classmethod
...   def foo(cls):
...     return 'foo'
...   @classproperty
...   @staticmethod
...   def bar():
...     return 'bar'
>>> Static.foo
'foo'
>>> Static.bar
'bar'

```

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

### Keyring Backend Interface - Set Password

Source: https://keyring.readthedocs.io/en/latest/index.html

Abstract method definition for setting a password for a user and service within a keyring backend. Implementations must handle password storage.

```python
abstractmethod set_password(_service : str_, _username : str_, _password : str_) -> None
```

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

### keyring.set_keyring

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Sets the current keyring backend.

```APIDOC
## keyring.set_keyring

### Description
Sets the current keyring backend to the provided instance.

### Method
`keyring.set_keyring(_keyring : KeyringBackend_)`

### Parameters
*   **_keyring** (KeyringBackend) - The KeyringBackend instance to set as the current backend.

### Returns
None
```

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

### Legacy Class Property Behavior

Source: https://keyring.readthedocs.io/en/latest/index.html

Demonstrates the legacy behavior of class properties when the metaclass is not explicitly specified. Setting properties on instances may not have the intended effect on the class.

```python
class X:
    val = None
    @classproperty
    def foo(cls):
        return cls.val
    @foo.setter
    def foo(cls, val):
        cls.val = val

# Example usage:
# X.foo = 3
# X.foo
# 3
# x = X()
# x.foo
# 3
# X.foo = 4
# x.foo
# 4
# x.foo = 5 # This assignment affects only the instance in legacy mode
# X.foo
# 4
```

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

### keyring.set_properties_from_env

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Sets keyring properties from environment variables.

```APIDOC
## keyring.set_properties_from_env

### Description
For all KEYRING_PROPERTY_* env var, set that property.

### Method
`set_properties_from_env() → None`

### Returns
None
```

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

### Use get_password with getpass.getuser()

Source: https://keyring.readthedocs.io/en/latest/history.html

Replaces the deprecated getpassbackend module. Use this pattern to retrieve a password using the current user and a specified service name.

```python
import getpass
import keyring

keyring.get_password(getpass.getuser(), 'Python')
```

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

### keyring.core.get_credential

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves a Credential object for a given service and optional username.

```APIDOC
## keyring.core.get_credential

### Description
Get a Credential for the specified service.

### Method
Not specified (assumed to be a function call).

### Parameters
#### Path Parameters
- **_service_name** (str) - Required - The name of the service.
- **_username** (str | None) - Optional - The username associated with the credential.

### Response
#### Success Response
- **Credential | None** - The Credential object if found, otherwise None.
```

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

### keyring.backend.KeyringBackend.get_credential

Source: https://keyring.readthedocs.io/en/latest/index.html

Abstract method to retrieve a Credential for a given service and username from a backend.

```APIDOC
## get_credential(_service : str_, _username : str | None_) -> Credential | None

### Description
Gets the username and password for the service. Returns a Credential instance. The _username_ argument is optional and may be omitted by the caller or ignored by the backend. Callers must use the returned username.

### Parameters
#### Path Parameters
- **_service** (str) - Required - The name of the service.
- **_username** (str | None) - Optional - The username for which to retrieve the credential.

### Method
N/A (Abstract Method)

### Endpoint
N/A (Abstract Method)
```

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

### Disable Keyring Backend

Source: https://keyring.readthedocs.io/en/latest?__cf_chl_rt_tk=79bwTgTlvNpuwD2.YU4viICjxT9W0hBIEoCPLFDTikM-1785114375-1.0.1.1-r4XiOu64bbN8cFUVM_CFHZCdMwqaBtYQFgGCBTOWYEQ

Shows the behavior of the disable function, which configures the null keyring as the default and raises a RuntimeError if called when already disabled.

```python
>>> fs = getfixture('fs')
>>> disable()
>>> disable()
Traceback (most recent call last):
...
RuntimeError: Refusing to overwrite...
```

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

### keyring.core.disable

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Configures the null keyring as the default, effectively disabling password storage.

```APIDOC
## keyring.core.disable

### Description
Configure the null keyring as the default.

### Method
Not specified (assumed to be a function call).

### Parameters
None.

### Response
#### Success Response
None (operation is void).

### Error Handling
- `RuntimeError`: Raised if attempting to overwrite an existing configuration.
```

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

### keyring.backend.KeyringBackend.get_credential

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves a Credential object for a given username and service from a backend.

```APIDOC
## keyring.backend.KeyringBackend.get_credential

### Description
Gets the username and password for the service. Returns a Credential instance. The _username_ argument is optional and may be omitted by the caller or ignored by the backend. Callers must use the returned username.

### Method
`get_credential(_service : str_, _username : str | None_) → Credential | None`

### Parameters
*   **_service** (str) - The name of the service.
*   **_username** (str | None) - The username for which to retrieve the credential. This argument is optional.

### Returns
`Credential | None` - A Credential object if found, otherwise None.
```

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

### Set Custom Keychain for OS X Backend

Source: https://keyring.readthedocs.io/en/latest/history.html

Allows specifying a custom keychain file for the OS X backend when retrieving passwords. This is useful in environments like cron where the default keychain may differ.

```python
keyring.get_keyring().keychain = '/path/to/login.keychain'
pw = keyring.get_password(...)

```

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

### Override SecretService/libsecret scheme with properties

Source: https://keyring.readthedocs.io/en/latest/history.html

Use the `.with_properties` method to create a new keyring instance with overridden properties, such as the scheme for SecretService/libsecret backends. This is useful for compatibility with different schemes like KeePassXC.

```python
keypass = keyring.get_keyring().with_properties(scheme='KeePassXC')
```

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

### keyring.get_credential

Source: https://keyring.readthedocs.io/en/latest/index.html

Retrieves a Credential object for a given user and service name.

```APIDOC
## get_credential _service_name : str_, _username : str | None_ -> Credential | None

### Description
Get a Credential for the specified service. The username may be optional.

### Parameters
#### Path Parameters
- **_service_name** (str) - Required - The name of the service.
- **_username** (str | None) - Optional - The username for which to retrieve the credential.

### Method
N/A (Function Call)

### Endpoint
N/A (Function Call)
```

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

### keyring.get_credential

Source: https://keyring.readthedocs.io/en/latest?badge=latest

Retrieves a Credential object for a given username and service name.

```APIDOC
## keyring.get_credential

### Description
Gets a Credential for the specified service. The username argument is optional.

### Method
`keyring.get_credential(_service_name : str_, _username : str | None_)`

### Parameters
*   **_service_name** (str) - The name of the service.
*   **_username** (str | None) - The username for which to retrieve the credential. This argument is optional.

### Returns
`Credential | None` - A Credential object if found, otherwise None.
```

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

### keyring.backend.KeyringBackend.set_password

Source: https://keyring.readthedocs.io/en/latest/index.html

Abstract method to set a password for a given service and username in a backend.

```APIDOC
## set_password(_service : str_, _username : str_, _password : str_) -> None

### Description
Set password for the username of the service. If the backend cannot store passwords, raise PasswordSetError.

### Parameters
#### Path Parameters
- **_service** (str) - Required - The name of the service.
- **_username** (str) - Required - The username for which to set the password.
- **_password** (str) - Required - The password to set.

### Method
N/A (Abstract Method)

### Endpoint
N/A (Abstract Method)
```
Tokens:
Raw