Riktlinjer för språkdesign i Azure SDK för Python

Riktlinjer för språkdesign i Azure SDK är omfattande standarder som säkerställer konsekvens, förutsägbarhet och användarvänlighet för alla Azure SDK:er. De här riktlinjerna hjälper utvecklare att arbeta effektivt med Azure-tjänster genom att tillhandahålla välbekanta mönster och beteenden i olika tjänster och programmeringsspråk.

Riktlinjerna består av två kategorier:

  • Allmänna riktlinjer: Grundläggande principer som gäller för alla Azure SDK:er oavsett programmeringsspråk.
  • Language-Specific Riktlinjer: Implementeringsinformation optimerad för varje språk som stöds, inklusive Python, .NET, Java, TypeScript och många fler. Mer information finns i innehållsförteckningen som börjar på sidan Allmänna riktlinjer: Introduktion .

Dessa riktlinjer utvecklas öppet på GitHub, vilket möjliggör communitygranskning och bidrag.

Allmänna designprinciper

Alla Azure SDK:er följer dessa grundläggande principer:

Princip Description
Idiomatisk användning SDK:er följer språkspecifika konventioner och mönster.
Consistency Beteenden är enhetliga för olika Azure-tjänster.
Enkelhet Vanliga uppgifter kräver minimal kod.
Progressivt avslöjande Avancerade funktioner är tillgängliga men komplicerar inte grundläggande användning.
Robusthet Hantering är inbyggd för fel, återförsök och tidsbegränsningar.

Python-specifika riktlinjer

Resten av det här dokumentet fokuserar på Python-riktlinjerna.

Namngivningskonventioner

Azure SDK:er för Python följer vanliga Namngivningskonventioner för Python:

  • Metoder: Använd snake_case.

    list_containers()
get_secret()
create_database()

  • Variabler: Använd snake_case.

    connection_string = "..."
retry_count = 3

  • Klasser: Använd PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Konstanter: Använd UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Paketstruktur

Azure SDK-paket följer en konsekvent struktur:

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

Klient-instansiering

Klienter tillhandahåller flera instansieringsmetoder:

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

Azure SDK:er använder konsekventa autentiseringsmönster:

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

Kontexthanterare

De flesta Azure SDK-klienter implementerar context manager-protokoll för automatisk resursrensning:

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

Anmärkning

Även om de flesta klienter har stöd för kontexthanterare kontrollerar du specifik klientdokumentation för tillgänglighet.

Asynkrona åtgärder

Asynkrona klienter tillhandahålls i separata .aio moduler:

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

Tidskrävande åtgärder

Långvariga åtgärder använder prefixet begin_ och returnerar pollerobjekt:

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

Paginering

Liståtgärder returnerar iterabler som hanterar sidnumrering automatiskt:

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)

Returtyper

Metoder returnerar starkt typerade modellobjekt i stället för ordlistor:

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)

Felhantering

Azure SDK-undantag ärver från AzureError och tillhandahåller specifika undantagstyper:

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

Konfigurationsalternativ

Klienter accepterar konfiguration via nyckelordsargument:

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
)

Vanliga SDK-mönster

Tjänstklienthierarki

Azure SDK:er följer vanligtvis en hierarki på tre nivåer:

  • Tjänstklient: Startpunkt för tjänståtgärder:

    service_client = BlobServiceClient(...)

  • Resursklient: Åtgärder för specifika resurser:

    container_client = service_client.get_container_client("container")

  • Åtgärdsmetoder: Åtgärder för resurser:

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

Namngivning av konsekvent metod

Metodnamn följer förutsägbara mönster:

Verksamhet Metodmönster Example
Create create_<resource> create_container()
Läs get_<resource> get_blob()
Update update_<resource> update_secret()
Ta bort delete_<resource> delete_container()
List list_<resources> list_blobs()
Exists exists() blob_client.exists()

Arbeta med Azure SDK:er

I följande exempel visas hur designriktlinjer skapar konsekvens mellan olika Azure-tjänster:

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

Bidra till Azure SDK:er

När du utökar eller bidrar till Azure SDK:er:

  • Följ Python-idiom: Använd Python-mönster och -konventioner.
  • Bibehåll konsekvens: Justera med befintliga SDK-mönster.
  • Skriva omfattande tester: Inkludera enhets- och integreringstester.
  • Dokumentera noggrant: Tillhandahåll docstrings och ge exempel.
  • Granska riktlinjer: Läs bidragsguiden för Azure SDK.

Här är ett exempel på hur du implementerar en anpassad klientmetod som följer riktlinjerna för språkdesign:

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)

Relaterat innehåll

  • Uppdaterades senast