Pokyny k návrhu jazyka Azure SDK pro Python

Pokyny pro návrh jazyka Azure SDK jsou komplexní standardy, které zajišťují konzistenci, předvídatelnost a snadné použití ve všech sadách Azure SDK. Tyto pokyny pomáhají vývojářům efektivně pracovat se službami Azure tím, že poskytují známé vzory a chování v různých službách a programovacích jazycích.

Pokyny se skládají ze dvou kategorií:

  • Obecné pokyny: Základní principy, které platí pro všechny sady SDK Azure bez ohledu na programovací jazyk.
  • Pokyny pro jednotlivé jazyky: Podrobnosti implementace optimalizované pro každý podporovaný jazyk, včetně Pythonu, .NET, Javy, TypeScriptu a mnoho dalších. Další informace najdete v obsahu začínajícím na stránce Obecné pokyny: Úvod .

Tyto pokyny jsou vyvíjeny otevřeně na GitHubu, což umožňuje komunitu kontrolovat a přispívat.

Obecné principy návrhu

Všechny sady Azure SDK se řídí těmito základními principy:

Princip Description
Idiotické využití Sady SDK dodržují konvence a vzory specifické pro jazyk.
Consistency Chování jsou jednotná napříč různými službami Azure.
Jednoduchost Běžné úlohy vyžadují minimální kód.
Progresivní zveřejnění Pokročilé funkce jsou dostupné, ale nekomplikují základní použití.
Robustnost Zpracování je integrované pro chyby, opakování a časové limity.

Pokyny specifické pro Python

Zbytek tohoto dokumentu se zaměřuje na pokyny Pythonu.

Názvoslovné konvence

Sady Azure SDK pro Python se řídí standardními zásadami vytváření názvů Pythonu:

  • Metody: Použijte snake_case.

    list_containers()
get_secret()
create_database()

  • Proměnné: Použijte snake_case.

    connection_string = "..."
retry_count = 3

  • Třídy: Použití PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Konstanty: Použijte UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Struktura balíčku

Balíčky Sady Azure SDK se řídí konzistentní strukturou:

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

Instance klienta

Klienti poskytují více metod vytváření instancí:

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)

Autentizace

Sady Azure SDK používají konzistentní vzory ověřování:

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

Kontextoví manažeři

Většina klientů Sady Azure SDK implementuje protokoly správce kontextu pro automatické vyčištění prostředků:

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

Poznámka:

Přestože většina klientů podporuje správce kontextu, ověřte dostupnost konkrétní klientské dokumentace.

Asynchronní operace

Asynchronní klienti jsou k dispozici v samostatných .aio modulech:

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

Dlouhotrvající operace

Dlouhotrvající operace používají předponu begin_ a vrací objektyller:

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

Stránkování

Operace výpisu vrací iterables, které zpracovávají stránkování automaticky:

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)

Návratové typy

Metody vracejí objekty modelu silného typu místo slovníků:

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)

Zpracování chyb

Výjimky sady Azure SDK dědí z AzureError a poskytují konkrétní typy výjimek:

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

Možnosti konfigurace

Klienti přijímají konfiguraci prostřednictvím argumentů klíčových slov:

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
)

Běžné vzory sady SDK

Hierarchie klienta služby

Sady Azure SDK se obvykle řídí tříúrovňovou hierarchií:

  • Klient služby: Vstupní bod pro operace služby:

    service_client = BlobServiceClient(...)

  • Klient prostředků: Operace s konkrétními prostředky:

    container_client = service_client.get_container_client("container")

  • Metody operací: Akce na prostředcích:

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

Konzistentní pojmenování metod

Názvy metod se řídí předvídatelnými vzory:

Operation Model metody Example
Create create_<resource> create_container()
Čti get_<resource> get_blob()
Update update_<resource> update_secret()
Delete delete_<resource> delete_container()
List list_<resources> list_blobs()
Exists exists() blob_client.exists()

Práce se sadami Azure SDK

Následující příklad ukazuje, jak pokyny pro návrh vytvářejí konzistenci napříč různými službami 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}")

Přispějte do Azure SDKs

Pokud rozšiřujete nebo přispíváte k sadám Azure SDK:

  • Postupujte podle idiomů Pythonu: Používejte vzory a konvence Pythonu.
  • Udržovat konzistenci: Zarovnejte se s existujícími vzory sady SDK.
  • Napište komplexní testy: Zahrňte testy jednotek a integrace.
  • Důkladně dokumentujte: Uveďte dokumentační řetězce a příklady.
  • Přečtěte si pokyny: Projděte si průvodce přispívání k sadě Azure SDK.

Tady je příklad implementace vlastní metody klienta, která se řídí pokyny pro návrh jazyka:

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)

Související obsah

  • Poslední aktualizace v