Wskazówki dotyczące projektowania języka zestawu Azure SDK dla języka Python

Wytyczne dotyczące projektowania języka zestawu Azure SDK to kompleksowe standardy, które zapewniają spójność, przewidywalność i łatwość użycia we wszystkich zestawach SDK platformy Azure. Te wytyczne ułatwiają deweloperom wydajną pracę z usługami platformy Azure, zapewniając znane wzorce i zachowania w różnych usługach i językach programowania.

Wytyczne składają się z dwóch kategorii:

• Ogólne wytyczne: podstawowe zasady dotyczące wszystkich zestawów SDK platformy Azure niezależnie od języka programowania.
• Wytyczne specyficzne dla języka: szczegóły implementacji zoptymalizowane pod kątem każdego obsługiwanego języka, w tym Python, .NET, Java, TypeScript i wiele innych. Aby uzyskać więcej informacji, zobacz spis treści rozpoczynający się na stronie Ogólne wskazówki: wprowadzenie .

Te wytyczne są opracowywane w sposób otwarty na platformie GitHub, co umożliwia przegląd i wkład społeczności.

Ogólne zasady projektowania

Wszystkie zestawy SDK platformy Azure są zgodne z następującymi podstawowymi zasadami:

Wytyczne specyficzne dla języka Python

Pozostała część tego dokumentu koncentruje się na wytycznych dotyczących języka Python.

Konwencje nazewnictwa

Zestawy AZURE SDK dla języka Python są zgodne ze standardowymi konwencjami nazewnictwa języka Python:

• Metody: użyj snake_case.

  list_containers()
  get_secret()
  create_database()
  

• Zmienne: użyj snake_case.

  connection_string = "..."
  retry_count = 3
  

• Klasy: użyj polecenia PascalCase.

  BlobServiceClient
  SecretClient
  CosmosClient
  

• Stałe: użyj UPPER_CASE.

  DEFAULT_CHUNK_SIZE
  MAX_RETRIES
  

Struktura pakietu

Pakiety zestawu Azure SDK mają spójną strukturę:

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

Tworzenie wystąpienia klienta

Klienci udostępniają wiele metod tworzenia wystąpień:

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

Zestawy SDK platformy Azure używają spójnych wzorców uwierzytelniania:

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

Menedżerowie kontekstu

Większość klientów zestawu Azure SDK implementuje protokoły menedżera kontekstu na potrzeby automatycznego czyszczenia zasobów:

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

Operacje asynchroniczne

Klienci asynchroniczny są udostępniani w oddzielnych .aio modułach:

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

Długotrwałe operacje

Długotrwałe operacje używają prefiksu begin_ i zwracania obiektów poller:

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

Paginacja

Operacje listy zwracają iterables, które automatycznie obsługują stronicowanie:

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)

Typy zwracane

Metody zwracają silnie typizowane obiekty modelu, a nie słowniki:

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)

Obsługa błędów

pl-PL: Wyjątki zestawu Azure SDK dziedziczą z AzureError oraz udostępniają określone typy wyjątków:

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

Opcje konfiguracji

Klienci akceptują konfigurację za pomocą argumentów słów kluczowych:

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
)

Typowe wzorce zestawu SDK

Hierarchia klienta usługi

Zestawy SDK platformy Azure zwykle są zgodne z hierarchią trzy poziomów:

• Klient usługi: punkt wejścia dla operacji usługi:

  service_client = BlobServiceClient(...)
  

• Klient zasobów: Operacje na określonych zasobach:

  container_client = service_client.get_container_client("container")
  

• Metody operacji: Akcje dotyczące zasobów:

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

Spójne nazewnictwo metod

Nazwy metod są zgodne z przewidywalnymi wzorcami:

Praca z zestawami SDK platformy Azure

W poniższym przykładzie pokazano, jak wytyczne dotyczące projektowania tworzą spójność w różnych usługach platformy 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}")

Współtworzenie zestawów SDK platformy Azure

Po rozszerzeniu lub współtworzeniu zestawów SDK platformy Azure:

• Postępuj zgodnie z idiomami języka Python: Używanie wzorców i konwencji języka Python.
• Zachowaj spójność: Dopasowanie do istniejących wzorców zestawu SDK.
• Pisanie kompleksowych testów: Uwzględnij testy jednostkowe i integracyjne.
• Dokument dokładnie: Podaj docstrings i przykłady.
• Zapoznaj się z wytycznymi: Skorzystaj z przewodnika współtworzenia Azure SDK.

Oto przykład implementacji niestandardowej metody klienta zgodnej z wytycznymi dotyczącymi projektowania języka:

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)

Treści powiązane

• Zapoznaj się z pełnymi wytycznymi dotyczącymi projektowania zestawu Azure SDK.
• Przeczytaj stronę Wydania zestawu Azure SDK.