CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-azure-keyvault-secrets

Microsoft Azure Key Vault secrets client library for Python providing secure storage and management of sensitive information

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

sync-client.mddocs/

Synchronous Secret Operations

Complete synchronous client for managing Azure Key Vault secrets with blocking operations suitable for traditional Python applications. Provides full CRUD operations, versioning, backup/restore, and soft-delete capabilities.

Capabilities

Client Initialization

Create a SecretClient instance for synchronous secret operations with Azure authentication.

class SecretClient:
    def __init__(
        self,
        vault_url: str,
        credential: TokenCredential,
        *,
        api_version: Optional[Union[ApiVersion, str]] = None,
        verify_challenge_resource: bool = True,
        **kwargs
    ):
        """
        Initialize a SecretClient for synchronous operations.

        Parameters:
        - vault_url (str): URL of the Azure Key Vault (e.g., "https://vault.vault.azure.net/")
        - credential (TokenCredential): Authentication credential from azure.identity
        - api_version (ApiVersion | str, optional): API version to use (default: ApiVersion.V7_6)
        - verify_challenge_resource (bool, optional): Whether to verify challenge resource (default: True)
        """

Basic Secret Operations

Core operations for creating, retrieving, and updating secrets.

def get_secret(
    self,
    name: str,
    version: Optional[str] = None,
    **kwargs
) -> KeyVaultSecret:
    """
    Get a secret by name and optional version.

    Parameters:
    - name (str): Name of the secret
    - version (str, optional): Version of the secret. If not specified, gets the latest version

    Returns:
    KeyVaultSecret: The complete secret including value and properties

    Raises:
    ResourceNotFoundError: Secret does not exist
    ClientAuthenticationError: Authentication failed
    """

def set_secret(
    self,
    name: str,
    value: str,
    *,
    enabled: Optional[bool] = None,
    tags: Optional[Dict[str, str]] = None,
    content_type: Optional[str] = None,
    not_before: Optional[datetime] = None,
    expires_on: Optional[datetime] = None,
    **kwargs
) -> KeyVaultSecret:
    """
    Create or update a secret.

    Parameters:
    - name (str): Name of the secret
    - value (str): Value of the secret
    - enabled (bool, optional): Whether the secret is enabled
    - tags (Dict[str, str], optional): User-defined metadata
    - content_type (str, optional): Content type of the secret
    - not_before (datetime, optional): Not valid before date
    - expires_on (datetime, optional): Expiration date

    Returns:
    KeyVaultSecret: The created or updated secret
    """

def update_secret_properties(
    self,
    name: str,
    version: Optional[str] = None,
    *,
    enabled: Optional[bool] = None,
    tags: Optional[Dict[str, str]] = None,
    content_type: Optional[str] = None,
    not_before: Optional[datetime] = None,
    expires_on: Optional[datetime] = None,
    **kwargs
) -> SecretProperties:
    """
    Update secret metadata without changing the value.

    Parameters:
    - name (str): Name of the secret
    - version (str, optional): Version to update. If not specified, updates latest version
    - enabled (bool, optional): Whether the secret is enabled
    - tags (Dict[str, str], optional): User-defined metadata
    - content_type (str, optional): Content type of the secret
    - not_before (datetime, optional): Not valid before date
    - expires_on (datetime, optional): Expiration date

    Returns:
    SecretProperties: Updated secret properties
    """

Listing Operations

Operations for discovering secrets and their versions.

def list_properties_of_secrets(
    self,
    **kwargs
) -> ItemPaged[SecretProperties]:
    """
    List properties of all secrets in the vault.

    Returns:
    ItemPaged[SecretProperties]: Iterator of secret properties (no values)
    """

def list_properties_of_secret_versions(
    self,
    name: str,
    **kwargs
) -> ItemPaged[SecretProperties]:
    """
    List all versions of a specific secret.

    Parameters:
    - name (str): Name of the secret

    Returns:
    ItemPaged[SecretProperties]: Iterator of secret version properties
    """

Backup and Restore Operations

Operations for backing up and restoring secrets for data protection and migration.

def backup_secret(
    self,
    name: str,
    **kwargs
) -> bytes:
    """
    Backup a secret for external storage or migration.

    Parameters:
    - name (str): Name of the secret to backup

    Returns:
    bytes: Encrypted backup data

    Raises:
    ResourceNotFoundError: Secret does not exist
    """

def restore_secret_backup(
    self,
    backup: bytes,
    **kwargs
) -> SecretProperties:
    """
    Restore a secret from backup data.

    Parameters:
    - backup (bytes): Encrypted backup data from backup_secret()

    Returns:
    SecretProperties: Properties of the restored secret

    Raises:
    ResourceExistsError: Secret already exists
    """

Deletion and Recovery Operations

Soft-delete operations with recovery capabilities for data protection.

def begin_delete_secret(
    self,
    name: str,
    **kwargs
) -> LROPoller[DeletedSecret]:
    """
    Delete a secret (soft delete with recovery option).

    Parameters:
    - name (str): Name of the secret to delete

    Returns:
    LROPoller[DeletedSecret]: Long-running operation poller

    Note:
    This is a long-running operation. Use poller.result() to wait for completion.
    """

def get_deleted_secret(
    self,
    name: str,
    **kwargs
) -> DeletedSecret:
    """
    Get information about a deleted secret.

    Parameters:
    - name (str): Name of the deleted secret

    Returns:
    DeletedSecret: Information about the deleted secret including recovery details
    """

def list_deleted_secrets(
    self,
    **kwargs
) -> ItemPaged[DeletedSecret]:
    """
    List all deleted secrets that can be recovered.

    Returns:
    ItemPaged[DeletedSecret]: Iterator of deleted secrets
    """

def purge_deleted_secret(
    self,
    name: str,
    **kwargs
) -> None:
    """
    Permanently delete a secret (cannot be recovered).

    Parameters:
    - name (str): Name of the deleted secret to purge

    Warning:
    This operation is irreversible.
    """

def begin_recover_deleted_secret(
    self,
    name: str,
    **kwargs
) -> LROPoller[SecretProperties]:
    """
    Recover a deleted secret.

    Parameters:
    - name (str): Name of the deleted secret to recover

    Returns:
    LROPoller[SecretProperties]: Long-running operation poller
    """

Client Management

Operations for managing the client lifecycle and custom requests.

def close(self) -> None:
    """
    Close the client and clean up resources.
    """

def send_request(
    self,
    request: HttpRequest,
    *,
    stream: bool = False,
    **kwargs
) -> HttpResponse:
    """
    Send a custom HTTP request using the client's pipeline.

    Parameters:
    - request (HttpRequest): The request to send
    - stream (bool, optional): Whether to stream the response

    Returns:
    HttpResponse: The HTTP response
    """

Context Manager Support

Use SecretClient as a context manager for automatic resource cleanup.

def __enter__(self) -> SecretClient: ...
def __exit__(self, *args) -> None: ...

Properties

@property
def vault_url(self) -> str:
    """The URL of the Key Vault."""

Usage Examples

Complete Secret Lifecycle

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential
import datetime

credential = DefaultAzureCredential()
client = SecretClient("https://vault.vault.azure.net/", credential)

# Create a secret with metadata
secret = client.set_secret(
    "api-key",
    "secret-api-key-value",
    enabled=True,
    tags={"environment": "production", "service": "api"},
    content_type="text/plain",
    expires_on=datetime.datetime(2025, 12, 31)
)

# Retrieve the secret
retrieved = client.get_secret("api-key")
print(f"Secret value: {retrieved.value}")

# Update metadata without changing value
client.update_secret_properties(
    "api-key",
    tags={"environment": "production", "service": "api", "updated": "true"}
)

# List all secrets
for props in client.list_properties_of_secrets():
    print(f"Secret: {props.name}, Enabled: {props.enabled}")

# Backup the secret
backup_data = client.backup_secret("api-key")

# Delete and recover
delete_poller = client.begin_delete_secret("api-key")
deleted_secret = delete_poller.result()

recover_poller = client.begin_recover_deleted_secret("api-key")
recovered_props = recover_poller.result()

Using Context Manager

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

with SecretClient("https://vault.vault.azure.net/", credential) as client:
    # Client automatically closed when exiting context
    secret = client.set_secret("temp-secret", "temporary-value")
    value = client.get_secret("temp-secret").value

Required Imports

from typing import Dict, Optional, Union
from datetime import datetime
from azure.core.polling import LROPoller
from azure.core.paging import ItemPaged
from azure.core.credentials import TokenCredential
from azure.core import HttpRequest, HttpResponse
from azure.keyvault.secrets import (
    SecretClient,
    KeyVaultSecret,
    SecretProperties, 
    DeletedSecret,
    KeyVaultSecretIdentifier,
    ApiVersion
)

Install with Tessl CLI

npx tessl i tessl/pypi-azure-keyvault-secrets

docs

async-client.md

error-handling.md

index.md

models.md

sync-client.md

tile.json