Yandex Lockbox Python client documentation#

Release v0.2.0

https://img.shields.io/pypi/pyversions/yc-lockbox.svg

https://img.shields.io/pypi/v/yc-lockbox.svg

This library is a simple client for working with Yandex Lockbox over REST API, simplifying work with secrets and allowing you to work with them in the OOP paradigm.

Supported Python versions:

3.10
3.11
3.12

Dependencies:

Currently, the following operations are not supported by the library:

List secret access bindings
Set secret access bindings
Update secret access bindings
List secret operations

Installation#

Installing with pip:

pip install yc-lockbox

Also, you can install from source with:

git clone https://github.com/akimrx/python-yc-lockbox
cd python-yc-lockbox
make install

Quick start#

Authenticate via your OAuth token

from yc_lockbox import YandexLockboxClient

lockbox = YandexLockboxClient("y0_xxxxxxxxxxxx")

Authenticate via IAM token

Note

If you pass a IAM token as credentials, you need to take care of the freshness of the token yourself.

from yc_lockbox import YandexLockboxClient

lockbox = YandexLockboxClient("t1.xxxxxx.xxxxxxx")

Authenticate using service account key

import json
from yc_lockbox import YandexLockboxClient

with open("/path/to/key.json", "r") as keyfile:
   credentials = keyfile.read()

lockbox = YandexLockboxClient(credentials)

Create a new secret#

from yc_lockbox import YandexLockboxClient, INewSecret, INewSecretPayloadEntry

lockbox = YandexLockboxClient("oauth_or_iam_token")

create_secret_operation = lockbox.create_secret(
   INewSecret(
   folder_id="b1xxxxxxxxxxxxxx",
   name="my-secret",
   version_payload_entries=[
      INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
      INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value".encode()),
   ],
   )
)

if create_secret_operation.done:
   new_secret = create_secret_operation.resource
   print(new_secret.id)
   new_secret.deactivate()

Get secret from Lockbox#

from yc_lockbox import YandexLockboxClient, Secret

lockbox = YandexLockboxClient("oauth_or_iam_token")

secret: Secret = lockbox.get_secret("e6qxxxxxxxxxx")
print(secret.status, secret.name)

payload = secret.payload(version_id=secret.current_version.id)  # id is optional, by default using current version
print(payload.entries)  # list of SecretPayloadEntry objects

# Direct access

entry = payload["secret_entry_1"]  # or payload.get("secret_entry_1")

print(entry.text_value)  # return MASKED value like ***********
print(entry.reveal_text_value())  # similar to entry.text_value.get_secret_value()

Add new version of secret#

from yc_lockbox import YandexLockboxClient, Secret, INewSecretVersion, INewSecretPayloadEntry

lockbox = YandexLockboxClient("oauth_or_iam_token")

secret: Secret = lockbox.get_secret("e6qxxxxxxxxxxxx")

secret.add_version(
   INewSecretVersion(
      description="a new version",
      base_version_id=secret.current_version.id,
      payload_entries= [
            INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
            INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value"),
      ]
   )
)

# alternative
lockbox.add_secret_version(
   "secret_id",
   version=INewSecretVersion(
      description="a new version",
      base_version_id=secret.current_version.id,
      payload_entries=[INewSecretPayloadEntry(...), INewSecretPayloadEntry(...)]
   )
)

Other operations with secret#

from yc_lockbox import YandexLockboxClient

lockbox = YandexLockboxClient("oauth_or_iam_token")


for secret in lockbox.list_secrets(folder_id="b1xxxxxxxxxx", iterator=True):
   print(secret.name, secret.status)

   secret.deactivate()
   secret.activate()

   for version in secret.list_versions(iterator=True):  # if iterator=False returns paginated list with ``next_page_token``
      if version.id != secret.current_version.id:
            version.schedule_version_destruction()
            version.cancel_version_destruction()

Async mode#

The client supports asynchronous mode using the aiohttp library. The signature of the methods does not differ from the synchronous implementation.

Just import async client:

from yc_lockbox import AsyncYandexLockboxClient

lockbox = AsyncYandexLockboxClient("oauth_or_iam_token")

Alternative:

from yc_lockbox import YandexLockboxFacade

lockbox = YandexLockboxFacade("oauth_or_iam_token", enable_async=True).client

Example usage:

secret: Secret = await lockbox.get_secret("e6qxxxxxxxxxx")
payload = await secret.payload()
print(payload.entries)  # list of SecretPayloadEntry objects

# Direct access

entry = payload["secret_entry_1"]  # or payload.get("secret_entry_1")

print(entry.text_value)  # return MASKED value like ***********
print(entry.reveal_text_value())  # similar to entry.text_value.get_secret_value()

# Async iterators

secret_versions = await secret.list_versions(iterator=True)

async for version in secret_versions:
   if version.id != secret.current_version.id:
      await version.schedule_version_destruction()
      await version.cancel_version_destruction()

Modules#

Content:

Indices and tables#

Index