Ontwerprichtlijnen voor Taalontwerp voor Azure SDK voor Python

Azure SDK Language Design Guidelines zijn uitgebreide standaarden die consistentie, voorspelbaarheid en gebruiksgemak garanderen voor alle Azure SDK's. Deze richtlijnen helpen ontwikkelaars efficiënt te werken met Azure-services door vertrouwde patronen en gedragingen te bieden in verschillende services en programmeertalen.

De richtlijnen bestaan uit twee categorieën:

  • Algemene richtlijnen: kernprincipes die van toepassing zijn op alle Azure-SDK's, ongeacht de programmeertaal.
  • Language-Specific richtlijnen: implementatiedetails die zijn geoptimaliseerd voor elke ondersteunde taal, waaronder Python, .NET, Java, TypeScript en nog veel meer. Zie de inhoudsopgave die begint op de pagina Algemene richtlijnen: Inleiding voor meer informatie.

Deze richtlijnen worden open ontwikkeld op GitHub, waardoor communitybeoordeling en bijdrage mogelijk zijn.

Algemene ontwerpprincipes

Alle Azure SDK's volgen de volgende basisprincipes:

Principe Description
Idiomatisch gebruik SDK's volgen taalspecifieke conventies en patronen.
Consistency Gedrag is uniform in verschillende Azure-services.
Eenvoud Voor veelvoorkomende taken is minimale code vereist.
Progressieve openbaarmaking Er zijn geavanceerde functies beschikbaar, maar maak het basisgebruik niet ingewikkeld.
Robuustheid Afhandeling is ingebouwd voor fouten, nieuwe pogingen en time-outs.

Python-specifieke richtlijnen

De rest van dit document is gericht op de Python-richtlijnen.

Naamgevingsconventies

Azure SDK's voor Python volgen standaard naamconventies voor Python:

  • Methoden: Gebruik snake_case.

    list_containers()
get_secret()
create_database()

  • Variabelen: Gebruiken snake_case.

    connection_string = "..."
retry_count = 3

  • Klassen: Gebruik PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Constanten: Gebruik UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Pakketstructuur

Azure SDK-pakketten volgen een consistente structuur:

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

Client instantiëring

Clients bieden meerdere instantiëringsmethoden:

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)

Authenticatie

Azure SDK's gebruiken consistente verificatiepatronen:

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

Contextbeheerders

De meeste Azure SDK-clients implementeren contextbeheerprotocollen voor het automatisch opschonen van resources:

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

Opmerking

Hoewel de meeste clients contextbeheerders ondersteunen, controleert u specifieke clientdocumentatie voor beschikbaarheid.

Asynchrone bewerkingen

Asynchrone clients worden geleverd in afzonderlijke .aio modules:

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

Langlopende bewerkingen

Langlopende bewerkingen gebruiken het begin_ voorvoegsel en retourneren pollerobjecten:

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

Pagina-indeling

Lijstbewerkingen retourneren iterables die automatisch paginering verwerken:

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)

Retourtypen

Methoden retourneren sterk getypte modelobjecten in plaats van woordenlijsten:

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)

Foutafhandeling

Azure SDK-uitzonderingen nemen over van AzureError en bieden specifieke uitzonderingstypen:

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

Configuratieopties

Clients accepteren configuratie via trefwoordargumenten:

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
)

Algemene SDK-patronen

Serviceclienthiërarchie

Azure SDK's volgen doorgaans een hiërarchie met drie niveaus:

  • Serviceclient: toegangspunt voor servicebewerkingen:

    service_client = BlobServiceClient(...)

  • Resourceclient: bewerkingen voor specifieke resources:

    container_client = service_client.get_container_client("container")

  • Bewerkingsmethoden: Acties voor resources:

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

Naamgeving van consistente methoden

Methodenamen volgen voorspelbare patronen:

Operation Methodepatroon Example
Create create_<resource> create_container()
Lezen get_<resource> get_blob()
bijwerken update_<resource> update_secret()
Delete delete_<resource> delete_container()
List list_<resources> list_blobs()
Exists exists() blob_client.exists()

Werken met Azure SDK's

In het volgende voorbeeld ziet u hoe ontwerprichtlijnen consistentie creëren in verschillende Azure-services:

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

Bijdragen aan Azure SDK's

Wanneer u Azure SDK's uitbreidt of hieraan bijdraagt:

  • Volg Python-idioms: Pythonische patronen en conventies gebruiken.
  • Consistentie behouden: Afstemmen op bestaande SDK-patronen.
  • Uitgebreide tests schrijven: Module- en integratietests opnemen.
  • Document grondig: Geef docstrings en voorbeelden op.
  • Richtlijnen bekijken: Raadpleeg de handleiding voor de bijdrage van de Azure SDK.

Hier volgt een voorbeeld van het implementeren van een aangepaste clientmethode die volgt op de richtlijnen voor taalontwerp:

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)

Verwante inhoud

  • Laatst bijgewerkt om