Entwurfsrichtlinien für Azure SDK-Sprachen für Python

Azure SDK-Sprachdesignrichtlinien sind umfassende Standards, die Konsistenz, Vorhersagbarkeit und Benutzerfreundlichkeit für alle Azure SDKs gewährleisten. Diese Richtlinien helfen Entwicklern, effizient mit Azure-Diensten zu arbeiten, indem sie vertraute Muster und Verhaltensweisen in verschiedenen Diensten und Programmiersprachen bereitstellen.

Die Richtlinien bestehen aus zwei Kategorien:

  • Allgemeine Richtlinien: Kernprinzipien, die für alle Azure-SDKs gelten, unabhängig von der Programmiersprache.
  • Language-Specific Richtlinien: Implementierungsdetails, die für jede unterstützte Sprache optimiert sind, einschließlich Python, .NET, Java, TypeScript und viele mehr. Weitere Informationen finden Sie im Inhaltsverzeichnis beginnend auf der Seite Allgemeine Richtlinien: Einführung.

Diese Richtlinien werden offen auf GitHub entwickelt, was die Überprüfung und den Beitrag der Community ermöglicht.

Allgemeine Designprinzipien

Alle Azure-SDKs folgen den folgenden Grundprinzipien:

Prinzip Description
Idiomatische Verwendung SDKs folgen sprachspezifischen Konventionen und Mustern.
Konsistenz Verhaltensweisen sind in verschiedenen Azure-Diensten einheitlich.
Einfachheit Allgemeine Aufgaben erfordern minimalen Code.
Progressive Offenlegung Erweiterte Features sind verfügbar, erschweren jedoch keine grundlegende Verwendung.
Robustheit Die Verarbeitung ist für Fehler, Wiederholungen und Timeouts integriert.

Python-spezifische Richtlinien

Der Rest dieses Dokuments konzentriert sich auf die Python-Richtlinien.

Benennungskonventionen

Azure SDKs für Python folgen standardmäßigen Python-Benennungskonventionen:

  • Methoden: Verwenden Sie snake_case.

    list_containers()
get_secret()
create_database()

  • Variablen: Verwenden Sie snake_case.

    connection_string = "..."
retry_count = 3

  • Klassen: Verwenden Sie PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Konstanten: Verwenden Sie UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Paketstruktur

Azure SDK-Pakete folgen einer konsistenten Struktur:

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

Clientinstanziierung

Clients bieten mehrere Instanziierungsmethoden:

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)

Authentifizierung

Azure SDKs verwenden konsistente Authentifizierungsmuster:

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"
)

Kontextmanager

Die meisten Azure SDK-Clients implementieren Kontext-Manager-Protokolle für die automatische Ressourcenbereinigung:

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()

Hinweis

Obwohl die meisten Clients Kontextmanager unterstützen, überprüfen Sie die spezifische Clientdokumentation auf Verfügbarkeit.

Asynchrone Vorgänge

Asynchrone Clients werden in separaten .aio Modulen bereitgestellt:

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())

Lange ausgeführte Vorgänge

Lang ausgeführte Vorgänge verwenden das begin_-Präfix und geben Poller-Objekte zurück.

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()

Paginierung

Listenvorgänge geben Iterables zurück, die die Paginierung automatisch behandeln:

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)

Rückgabetypen

Methoden geben stark typierte Modellobjekte anstelle von Wörterbüchern zurück:

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)

Fehlerbehandlung

Azure SDK-Ausnahmen erben von AzureError und bieten spezifische Ausnahmetypen an:

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}")

Konfigurationsoptionen

Clients akzeptieren die Konfiguration über Schlüsselwortargumente:

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
)

Allgemeine SDK-Muster

Dienstclienthierarchie

Azure SDKs folgen in der Regel einer Hierarchie mit drei Ebenen:

  • Dienstclient: Einstiegspunkt für Dienstoperationen:

    service_client = BlobServiceClient(...)

  • Ressourcenclient: Vorgänge für bestimmte Ressourcen:

    container_client = service_client.get_container_client("container")

  • Vorgangsmethoden: Aktionen für Ressourcen:

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

Einheitliche Methodenbenennung

Methodennamen folgen vorhersagbaren Mustern:

Operation Methodenmuster Example
Create create_<resource> create_container()
Lesen Sie get_<resource> get_blob()
Update update_<resource> update_secret()
Löschen delete_<resource> delete_container()
List list_<resources> list_blobs()
Existiert exists() blob_client.exists()

Arbeiten mit Azure SDKs

Im folgenden Beispiel wird veranschaulicht, wie Entwurfsrichtlinien Konsistenz in verschiedenen Azure-Diensten schaffen:

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}")

Mitwirken zu Azure SDKs

Wenn Sie Azure SDKs erweitern oder mitwirken:

  • Folgen Sie Python-Idiome: Verwenden Sie Python-Muster und -Konventionen.
  • Konsistenz beibehalten: Richten Sie sich an vorhandenen SDK-Mustern aus.
  • Schreiben Sie umfassende Tests: Schließen Sie Komponenten- und Integrationstests ein.
  • Dokumentieren Sie gründlich: Stellen Sie Docstrings und Beispiele bereit.
  • Richtlinien überprüfen: Lesen Sie den Azure SDK-Beitragsleitfaden.

Nachfolgend finden Sie ein Beispiel für die Implementierung einer benutzerdefinierten Clientmethode, die den Richtlinien für das Sprachdesign folgt:

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)

Verwandte Inhalte

  • Zuletzt aktualisiert um