Python için Azure SDK Dil Tasarımı Yönergeleri

Azure SDK Dil Tasarımı Yönergeleri, tüm Azure SDK'larında tutarlılık, öngörülebilirlik ve kullanım kolaylığı sağlayan kapsamlı standartlardır. Bu yönergeler, geliştiricilerin farklı hizmetler ve programlama dillerinde tanıdık desenler ve davranışlar sağlayarak Azure hizmetleriyle verimli bir şekilde çalışmasına yardımcı olur.

Yönergeler iki kategoriden oluşur:

• Genel Yönergeler: Programlama dilinden bağımsız olarak tüm Azure SDK'ları için geçerli olan temel ilkeler.
• Language-Specific Yönergeleri: Python, .NET, Java, TypeScript ve daha birçok desteklenen dil için iyileştirilmiş uygulama ayrıntıları. Daha fazla bilgi için Genel Yönergeler: Giriş sayfasından başlayarak İçindekiler Tablosu'na bakın.

Bu yönergeler GitHub'da topluluk incelemesine ve katkıda bulunmaya olanak tanıyan açık bir şekilde geliştirilmiştir.

Genel tasarım ilkeleri

Tüm Azure SDK'ları şu temel ilkeleri izler:

Python'a özgü yönergeler

Bu belgenin geri kalanında Python yönergelerine odaklanılmıştır.

Adlandırma kuralları

Python için Azure SDK'ları standart Python adlandırma kurallarına uyar:

• Yöntemler: kullanın snake_case.

  list_containers()
  get_secret()
  create_database()
  

• Değişkenler: kullanın snake_case.

  connection_string = "..."
  retry_count = 3
  

• Sınıflar: kullanın PascalCase.

  BlobServiceClient
  SecretClient
  CosmosClient
  

• Sabitler: kullanın UPPER_CASE.

  DEFAULT_CHUNK_SIZE
  MAX_RETRIES
  

Paket yapısı

Azure SDK paketleri tutarlı bir yapıyı izler:

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

İstemci örneği oluşturma

İstemciler birden çok örnekleme yöntemi sağlar:

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'ları tutarlı kimlik doğrulama desenleri kullanır:

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

Bağlam yöneticileri

Çoğu Azure SDK istemcisi, otomatik kaynak temizleme için bağlam yöneticisi protokolleri uygular:

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

Zaman uyumsuz işlemler

Zaman uyumsuz istemciler ayrı .aio modüllerde sağlanır:

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

Uzun süre çalışan işlemler

Uzun süre çalışan işlemler ön ekini begin_ kullanır ve poller nesneleri döndürür:

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

Sayfalandırma

Liste işlemleri, sayfalandırmayı otomatik olarak işleyen yinelenebilir öğeler döndürür:

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)

Dönüş türleri

Yöntemler, sözlükler yerine kesin olarak yazılan model nesneleri döndürür:

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)

Hata yönetimi

Azure SDK özel durumları AzureError sınıfından devralınır ve belirli özel durum türleri sağlar.

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

Yapılandırma seçenekleri

İstemciler anahtar sözcük bağımsız değişkenleri aracılığıyla yapılandırmayı kabul eder:

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
)

Yaygın SDK desenleri

Hizmet istemci hiyerarşisi

Azure SDK'ları genellikle üç düzeyli hiyerarşiyi izler:

• Hizmet istemcisi: Hizmet işlemleri için giriş noktası:

  service_client = BlobServiceClient(...)
  

• Kaynak istemcisi: Belirli kaynaklardaki işlemler:

  container_client = service_client.get_container_client("container")
  

• İşlem yöntemleri: Kaynaklardaki eylemler:

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

Tutarlı yöntem adlandırma

Yöntem adları tahmin edilebilir desenleri izler:

Azure SDK'ları ile çalışma

Aşağıdaki örnek, tasarım yönergelerinin farklı Azure hizmetlerinde nasıl tutarlılık oluşturduğunu gösterir:

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

Azure SDK'larına katkıda bulunma

Azure SDK'lerini genişlettiğinizde veya katkıda bulunduğunuzda:

• Python deyimlerini izleyin: Pythonik desenleri ve kuralları kullanın.
• Tutarlılığı koruyun: Mevcut SDK desenleriyle hizalayın.
• Kapsamlı testler yazın: Birim ve tümleştirme testlerini dahil edin.
• Ayrıntılı bir şekilde belgele: Docstrings ve örnekler sağlayın.
• Yönergeleri gözden geçirin: Azure SDK Katkı Kılavuzu'na başvurun.

Aşağıda, Dil Tasarımı Yönergeleri'ni izleyen özel bir istemci yöntemi uygulama örneği verilmiştir:

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)

İlgili içerik

• Azure SDK Tasarım Yönergeleri'nin tamamını gözden geçirin.
• Azure SDK Yayınları sayfasını okuyun.