استفاده از SDKهای Python تولیدشده در Postman

این راهنما روش استفاده از SDKهای Python تولیدشده با Postman SDK Generator را توضیح می‌دهد. SDK پایتون برای model validation، type safety و serialization از Pydantic استفاده می‌کند و برای نصب محلی، توسعه و انتشار در PyPI آماده است.

ساختار SDK Python

• your_sdk/: package اصلی SDK.
• services/: کلاس‌ها یا moduleهای service برای endpointها.
• models/: مدل‌های Pydantic برای request و response.
• http/: HTTP client، errorها، retry و transport.
• pyproject.toml: metadata و dependencyهای package.

Type safety با Pydantic

مدل‌های تولیدشده قبل از ارسال request و بعد از دریافت response، داده را validation می‌کنند. اگر مقدار نامعتبر باشد، خطای validation می‌گیرید و قبل از رسیدن خطا به API می‌توانید آن را اصلاح کنید.

from your_sdk.models import User

user = User(id="123", email="user@example.com")
print(user.model_dump())

Optional و nullable fieldها

در Python هم تفاوت بین field حذف‌شده، مقدار None و مقدار واقعی مهم است. SDK این تفاوت را در serialization حفظ می‌کند.

Serialization و extra fields

برای تبدیل model به dict یا JSON از قابلیت‌های Pydantic مثل model_dump() استفاده کنید. رفتار extra fieldها به تنظیمات model تولیدشده از specification بستگی دارد.

اجرای نمونه SDK

هر SDK تولیدشده پوشه examples/ دارد. ابتدا همان را اجرا کنید.

cd examples
pip install -r requirements.txt
python main.py

from your_sdk import YourSdk

sdk = YourSdk(
    api_key="your-api-key",
    base_url="https://api.example.com"
)

try:
    user = sdk.users.get_user(user_id="123")
    print("User:", user)
except Exception as exc:
    print("Error:", exc)

Import کردن SDK Python به صورت local

editable install

برای توسعه، نصب editable بهترین گزینه است؛ تغییرات SDK بدون نصب دوباره در پروژه دیده می‌شود.

cd path/to/your-sdk
pip install -e .

نصب با file path

pip install ../path/to/your-sdk

افزودن به PYTHONPATH

export PYTHONPATH="../path/to/your-sdk:$PYTHONPATH"

استفاده با Poetry

poetry add ../path/to/your-sdk

انتشار در PyPI

برای انتشار SDK Python به حساب PyPI، نصب ابزارهای build/twine و یک نام package یکتا نیاز دارید. metadata اصلی را در pyproject.toml تنظیم کنید.

[project]
name = "your-sdk"
version = "1.0.0"
description = "SDK for Your API"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
  "pydantic",
  "httpx"
]

سپس build و upload را انجام دهید. بهتر است ابتدا TestPyPI را امتحان کنید.

python -m pip install --upgrade build twine
python -m build
twine check dist/*
twine upload --repository testpypi dist/*
twine upload dist/*

برای نسخه جدید، version را افزایش دهید و دوباره build/upload کنید.

python -m build
twine upload dist/*

بهترین کارها برای انتشار Python SDK

• README.md و نمونه کد واضح داشته باشید.
• از semantic versioning استفاده کنید.
• dependencyها را دقیق و سازگار نگه دارید.
• قبل از انتشار، package را در یک virtual environment تمیز نصب و تست کنید.
• برای انتشار خودکار از CI/CD و tokenهای PyPI استفاده کنید.

Authentication

SDK بر اساس security schemeهای API شما ورودی‌های authentication را تولید می‌کند.

sdk = YourSdk(api_key="your-api-key")

sdk = YourSdk(access_token="your-bearer-token")

sdk = YourSdk(username="your-username", password="your-password")

sdk = YourSdk(client_id="your-client-id", client_secret="your-client-secret")

Environment management

from your_sdk import YourSdk, Environment

sdk = YourSdk(
    environment=Environment.PRODUCTION,
    api_key="your-api-key"
)

custom_sdk = YourSdk(
    base_url="https://custom.api.example.com",
    api_key="your-api-key"
)

Error handling

SDK برای خطاهای API و validation exceptionهای مشخص تولید می‌کند. خطاهای HTTP معمولا status code، message و response raw را همراه دارند.

from your_sdk import YourSdk
from your_sdk.errors import ApiError, ValidationError

sdk = YourSdk(api_key="your-api-key")

try:
    user = sdk.users.get_user(user_id="123")
    print(user)
except ValidationError as exc:
    print("Validation failed:", exc)
except ApiError as exc:
    print("API error:", exc)
    print("Status code:", exc.status_code)
    print("Response:", exc.response)
except Exception as exc:
    print("Unexpected error:", exc)

Timeout و retry

sdk = YourSdk(
    api_key="your-api-key",
    timeout=10.0,
    retry={
        "attempts": 3,
        "delay": 1.0,
        "max_delay": 30.0,
        "backoff_factor": 2,
        "status_codes_to_retry": [408, 429, 500, 502, 503, 504]
    }
)

برای بعضی SDKها می‌توانید timeout را در سطح request هم override کنید.

منابع داخل SDK

• پوشه documentation/ برای مستندات serviceها و modelها.
• پوشه examples/ برای نمونه‌های قابل اجرا.
• مدل‌های Pydantic برای validation و serialization.
• وابستگی‌های HTTP مثل httpx یا کتابخانه مشابه، بسته به خروجی generator.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.