Рекомендации по проектированию языков пакета SDK для Azure для Python

Рекомендации по проектированию языков azure SDK — это комплексные стандарты, обеспечивающие согласованность, прогнозируемость и простоту использования во всех пакетах SDK Azure. Эти рекомендации помогают разработчикам эффективно работать со службами Azure, предоставляя знакомые шаблоны и поведение в разных службах и языках программирования.

Рекомендации состоят из двух категорий:

  • Общие рекомендации. Основные принципы, которые применяются ко всем пакетам SDK Azure независимо от языка программирования.
  • Руководства, специфичные для языков: Детали реализации оптимизированы для каждого поддерживаемого языка, включая Python, .NET, Java, TypeScript и многое другое. Дополнительные сведения см. в статье "Оглавление" на странице "Общие рекомендации: введение ".

Эти рекомендации разработаны открыто на сайте GitHub, что позволяет просматривать и внести вклад сообщества.

Общие принципы проектирования

Все пакеты SDK Azure следуют этим основным принципам:

Принцип Description
Идиоматическая использование Пакеты SDK соответствуют соглашениям и шаблонам, зависящим от языка.
Согласованность Поведение единообразно в разных службах Azure.
Простота Для распространенных задач требуется минимальный код.
Прогрессивное раскрытие информации Дополнительные функции доступны, но не усложняют базовое использование.
Робастность Встроена поддержка для обработки ошибок, повторных попыток и тайм-аутов.

Рекомендации, относящиеся к Python

Остальная часть этого документа посвящена рекомендациям Python.

Соглашения об именах

Пакеты SDK Azure для Python соответствуют стандартным соглашениям об именовании Python:

  • Методы: использование snake_case.

    list_containers()
get_secret()
create_database()

  • Переменные: используйте snake_case.

    connection_string = "..."
retry_count = 3

  • Классы: Используйте PascalCase.

    BlobServiceClient
SecretClient
CosmosClient

  • Константы: используйте UPPER_CASE.

    DEFAULT_CHUNK_SIZE
MAX_RETRIES

Структура пакета

Пакеты ПАКЕТА SDK Azure соответствуют согласованной структуре:

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

Создание экземпляра клиента

Клиенты предоставляют несколько методов создания экземпляров:

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

Пакеты SDK Azure используют согласованные шаблоны проверки подлинности:

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

Диспетчеры контекстов

Большинство клиентов Пакета SDK Azure реализуют протоколы диспетчера контекстов для автоматической очистки ресурсов:

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

Замечание

Хотя большинство клиентов поддерживают диспетчеры контекстов, проверьте документацию конкретного клиента на наличие.

Асинхронные операции

Асинхронные клиенты предоставляются в отдельных .aio модулях:

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

Длительные операции

Длительные операции используют begin_ префикс и объекты опросчика:

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

Постраничная разбивка

Операции списка возвращают итерации, которые автоматически обрабатывают разбиение на страницы:

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)

Типы возвращаемых данных

Методы возвращают строго типизированные объекты модели, а не словари:

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)

Обработка ошибок

Исключения SDK Azure наследуются от AzureError и предоставляют определенные типы исключений:

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

Параметры конфигурации

Клиенты принимают конфигурацию с помощью аргументов ключевых слов:

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
)

Общие шаблоны пакета SDK

Иерархия клиента службы

Пакеты SDK Azure обычно следуют трехуровневой иерархии:

  • Клиент службы: точка входа для операций службы:

    service_client = BlobServiceClient(...)

  • Клиент ресурсов: операции с определенными ресурсами:

    container_client = service_client.get_container_client("container")

  • Методы операций: действия по ресурсам:

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

Согласованное именование методов

Имена методов соответствуют прогнозируемым шаблонам:

Операция Паттерн метода Example
Create create_<resource> create_container()
Читайте get_<resource> get_blob()
Update update_<resource> update_secret()
Delete delete_<resource> delete_container()
List list_<resources> list_blobs()
Exists exists() blob_client.exists()

Работа с SDK Azure

В следующем примере показано, как рекомендации по проектированию создают согласованность между различными службами 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}")

Внесите вклад в пакеты SDK для Azure

Когда вы расширяете или вносите свой вклад в пакеты SDK Azure, выполните следующие действия.

  • Следуйте идиомам Python: Используйте шаблоны и соглашения Python.
  • Обеспечение согласованности: Выравнивайте существующие шаблоны пакета SDK.
  • Написание комплексных тестов: Включите модульные тесты и тесты интеграции.
  • Документируйте тщательно: Предоставьте docstring-и и примеры.
  • Руководство по работе: Ознакомьтесь с Руководством по внесению изменений в SDK Azure.

Ниже приведен пример реализации пользовательского метода клиента, следующего рекомендациям по проектированию языка.

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)

Связанный контент

  • Последнее обновление: