Recommandations en matière de conception de langage du KIT DE DÉVELOPPEMENT logiciel (SDK) Azure pour Python

Les recommandations en matière de conception du langage azure sont des normes complètes qui garantissent la cohérence, la prévisibilité et la facilité d’utilisation dans tous les kits SDK Azure. Ces instructions aident les développeurs à travailler efficacement avec les services Azure en fournissant des modèles et des comportements familiers entre différents services et langages de programmation.

Les instructions se composent de deux catégories :

  • Instructions générales : Principes fondamentaux qui s’appliquent à tous les Kits de développement logiciel (SDK) Azure, quel que soit le langage de programmation.
  • Language-Specific Instructions : Détails de l’implémentation optimisés pour chaque langage pris en charge, notamment Python, .NET, Java, TypeScript, etc. Pour plus d’informations, consultez la table des matières à partir de la page Instructions générales : Présentation .

Ces instructions sont développées ouvertement sur GitHub, ce qui permet une révision et une contribution de la communauté.

Principes généraux de conception

Tous les Kits de développement logiciel (SDK) Azure respectent ces principes fondamentaux :

Principe Descriptif
Utilisation idiomatique Les kits SDK suivent des conventions et des modèles spécifiques au langage.
Cohérence Les comportements sont uniformes entre différents services Azure.
Simplicité Les tâches courantes nécessitent un code minimal.
Divulgation progressive Les fonctionnalités avancées sont disponibles, mais ne compliquent pas l’utilisation de base.
Robustesse La gestion est intégrée pour les erreurs, les nouvelles tentatives et les délais d’expiration.

Instructions spécifiques à Python

Le reste de ce document se concentre sur les instructions Python.

Conventions d’affectation de noms

Les Kits de développement logiciel (SDK) Azure pour Python suivent les conventions d’affectation de noms Python standard :

  • Méthodes : Utiliser snake_case.

    list_containers()
get_secret()
create_database()

  • Variables : Utiliser snake_case.

    connection_string = "..."
retry_count = 3

  • Classes : Utiliser PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Constantes : Utiliser UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Structure de package

Les packages du Kit de développement logiciel (SDK) Azure suivent une structure cohérente :

azure-<service>-<feature>
├── azure/
│   └── <service>/
│       ├── __init__.py
│       ├── _client.py
│       ├── _models.py
│       └── aio/           # Async implementations
│           └── __init__.py

Instanciation du client

Les clients fournissent plusieurs méthodes d’instanciation :

from azure.storage.blob import BlobServiceClient
from azure.identity import DefaultAzureCredential

# Note: Do not use connection string if you can possibly avoid it!

# Using account URL and credential
credential = DefaultAzureCredential()
client = BlobServiceClient(account_url="https://account.blob.core.windows.net", 
                          credential=credential)

Authentication

Les sdk Azure utilisent des modèles d’authentification cohérents :

from azure.identity import DefaultAzureCredential, ClientSecretCredential

# Default credential chain
credential = DefaultAzureCredential()

# Explicit credential
credential = ClientSecretCredential(
    tenant_id="tenant-id",
    client_id="client-id",
    client_secret="secret"
)

Gestionnaires de contexte

La plupart des clients du Kit de développement logiciel (SDK) Azure implémentent des protocoles de gestionnaire de contexte pour le nettoyage automatique des ressources :

from azure.storage.blob import BlobServiceClient

# Automatic cleanup with context manager
with BlobServiceClient.from_connection_string(conn_str) as client:
    container_client = client.get_container_client("mycontainer")
    blob_list = container_client.list_blobs()

Note

Bien que la plupart des clients prennent en charge les gestionnaires de contexte, consultez la documentation du client concerné pour vérifier sa disponibilité.

Opérations asynchrones

Les clients asynchrones sont fournis dans des modules distincts .aio :

from azure.storage.blob.aio import BlobServiceClient
import asyncio

async def list_blobs_async():
    async with BlobServiceClient.from_connection_string(conn_str) as client:
        container_client = client.get_container_client("mycontainer")
        async for blob in container_client.list_blobs():
            print(blob.name)

# Run async function
asyncio.run(list_blobs_async())

Opérations de longue durée

Les opérations de longue durée utilisent le préfixe begin_ et retournent des objets de sonde :

from azure.storage.blob import BlobServiceClient

client = BlobServiceClient.from_connection_string(conn_str)
container_client = client.get_container_client("mycontainer")

# Start long-running operation
poller = container_client.begin_copy_blob_from_url(source_url)

# Wait for completion
result = poller.result()

# Or check status
if poller.done():
    result = poller.result()

Numérotation des pages

Les opérations de liste retournent des itérables qui gèrent automatiquement la pagination :

from azure.storage.blob import BlobServiceClient

client = BlobServiceClient.from_connection_string(conn_str)

# Automatic pagination
for container in client.list_containers():
    print(container.name)

# Manual pagination control
containers = client.list_containers(results_per_page=10).by_page()
for page in containers:
    for container in page:
        print(container.name)

Types de retour

Les méthodes retournent des objets de modèle fortement typés plutôt que des dictionnaires :

from azure.keyvault.secrets import SecretClient

client = SecretClient(vault_url="...", credential=credential)

# Returns KeyVaultSecret object, not dict
secret = client.get_secret("my-secret")
print(secret.value)
print(secret.properties.created_on)

Gestion des erreurs

Les exceptions du Kit de développement logiciel (SDK) Azure héritent de AzureError et fournissent des types d’exceptions spécifiques:

from azure.core.exceptions import (
    AzureError,
    ResourceNotFoundError,
    ResourceExistsError,
    ClientAuthenticationError,
    HttpResponseError
)

try:
    blob_client.download_blob()
except ResourceNotFoundError:
    # Handle missing resource
    print("Blob not found")
except ClientAuthenticationError:
    # Handle authentication failure
    print("Authentication failed")
except HttpResponseError as e:
    # Handle HTTP errors
    print(f"HTTP {e.status_code}: {e.message}")
except AzureError as e:
    # Handle any other Azure SDK error
    print(f"Azure SDK error: {e}")

Options de configuration

Les clients acceptent la configuration par le biais d’arguments de mot clé :

from azure.storage.blob import BlobServiceClient

client = BlobServiceClient(
    account_url="...",
    credential=credential,
    # Configuration options
    max_single_put_size=64 * 1024 * 1024,
    max_block_size=4 * 1024 * 1024,
    retry_total=3,
    logging_enable=True
)

Modèles de SDK courants

Hiérarchie du client de service

Les Kits de développement logiciel (SDK) Azure suivent généralement une hiérarchie à trois niveaux :

  • Client de service : point d’entrée pour les opérations de service :

    service_client = BlobServiceClient(...)

  • Client de ressources : opérations sur des ressources spécifiques :

    container_client = service_client.get_container_client("container")

  • Méthodes d’opération : Actions sur les ressources :

    blob_client = container_client.get_blob_client("blob.txt")
blob_client.upload_blob(data)

Nommage de méthode cohérente

Les noms de méthode suivent des modèles prévisibles :

Opération Modèle de méthode Example
Créer create_<resource> create_container()
Lire get_<resource> get_blob()
Update update_<resource> update_secret()
Supprimer delete_<resource> delete_container()
Liste list_<resources> list_blobs()
Exists exists() blob_client.exists()

Utiliser des Kits de développement logiciel (SDK) Azure

L’exemple suivant montre comment les instructions de conception créent une cohérence entre différents services Azure :

from azure.storage.blob import BlobServiceClient
from azure.keyvault.secrets import SecretClient
from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

# Consistent authentication
credential = DefaultAzureCredential()

# Consistent client instantiation
blob_service = BlobServiceClient(
    account_url="https://account.blob.core.windows.net",
    credential=credential
)
secret_client = SecretClient(
    vault_url="https://vault.vault.azure.net",
    credential=credential
)
cosmos_client = CosmosClient(
    url="https://account.documents.azure.com",
    credential=credential
)

# Consistent method patterns
containers = blob_service.list_containers()
secrets = secret_client.list_properties_of_secrets()
databases = cosmos_client.list_databases()

# Consistent error handling
from azure.core.exceptions import ResourceNotFoundError

try:
    blob_service.get_container_client("container").get_container_properties()
    secret_client.get_secret("secret")
    cosmos_client.get_database_client("database").read()
except ResourceNotFoundError as e:
    print(f"Resource not found: {e}")

Contribuer aux Kits de développement logiciel (SDK) Azure

Lorsque vous étendez ou contribuez aux kits sdk Azure :

  • Suivez les idiomes Python : Utilisez des modèles et des conventions Python.
  • Maintenir la cohérence : Aligner avec les modèles de SDK existants.
  • Écrire des tests complets : Incluez des tests unitaires et d’intégration.
  • Document minutieusement : Fournissez des docstrings et des exemples.
  • Passez en revue les instructions : Consultez le Guide de contribution du Kit de développement logiciel (SDK) Azure.

Voici un exemple d’implémentation d’une méthode cliente personnalisée qui suit les instructions de conception de langage :

def list_items_with_prefix(self, prefix: str, **kwargs) -> ItemPaged[ItemProperties]:
    """List items that start with the specified prefix.
    
    :param str prefix: The prefix to filter items
    :return: An iterable of ItemProperties
    :rtype: ~azure.core.paging.ItemPaged[ItemProperties]
    
    :example:
        items = client.list_items_with_prefix("test-")
        for item in items:
            print(item.name)
    """
    return self.list_items(name_starts_with=prefix, **kwargs)

Contenu connexe

  • Dernière mise à jour :