Python SDK

يوفر SDK Python الخاص بـ Asset Core عميل HTTP مُحدد للتفاعل مع خدمات الكتابة والقراءة، بالإضافة إلى مُنشئي العمليات الذين يتوافقون مباشرة مع JSON المعاملات. إنه غلاف رقيق فوق العقدة العامة لـ HTTP، لذا يمكن القيام بأي شيء يمكنك القيام به في SDK عبر HTTP الخام أيضًا.

نظرة عامة

يتم توزيع SDK كحزمة assetcore-sdk ويوفر:

• AssetCoreClient: عميل عالي المستوى مع طرق غير متزامنة ومتزامنة
• بناة العمليات: فئات بيانات مكتوبة لجميع العمليات الـ 24
• أنواع الأخطاء: استثناءات منظمة لمعالجة الأخطاء
• العميل المُولد: طبقة HTTP المعتمدة على OpenAPI

SDK هو عميل خالص؛ يستدعي واجهة برمجة التطبيقات العامة HTTP ولا يمكنه تعديل الحالة على جانب الخادم مباشرة. هذا يحافظ على نموذج الأمان متسقًا عبر جميع التكاملات.

الهيكل

assetcore_sdk/
  __init__.py          # Package exports
  client.py            # AssetCoreClient facade
  operations.py        # Operation builder dataclasses
  errors.py            # Exception types
  models/              # Typed data classes
  utils/               # HTTP and serialization helpers
  _generated/          # OpenAPI codegen output

حقول

AssetCoreClient

الفئة الرئيسية للعميل للتفاعل مع Asset Core. استخدم مثيلات عميل منفصلة لكتابة وقراءة الرموز للحفاظ على الوصول بأقل امتياز.

import os
from assetcore_sdk import AssetCoreClient

write_client = AssetCoreClient(
    base_url="http://localhost:8080",
    api_key=os.environ["ASSETCORE_WRITE_TOKEN"],
    timeout=30.0,
)

read_client = AssetCoreClient(
    base_url="http://localhost:8081",
    api_key=os.environ["ASSETCORE_READ_TOKEN"],
    timeout=30.0,
)

المعامل	النوع	الافتراضي	الوصف
base_url	str	مطلوب	عنوان URL الأساسي إما لعملية الكتابة أو القراءة
api_key	str	مطلوب	رمز الحامل المستخدم لـ Authorization
timeout	float	10.0	مهلة الطلب بالثواني
headers	dict	لا شيء	رؤوس إضافية لإرسالها مع كل طلب
refresh_token	callable	لا شيء	مزود رمز التحديث المتزامن الاختياري
refresh_token_async	callable	لا شيء	مزود رمز التحديث غير المتزامن الاختياري

طرق الالتزام

# Async
result = await write_client.commit_operations(
    operations=[...],
    idempotency_key="unique-key-2026-01-15",
    namespace_id=5001
)

# Sync
result = write_client.commit_operations_sync(
    operations=[...],
    idempotency_key="unique-key-2026-01-15",
    namespace_id=5001
)

المعامل	النوع	مطلوب	الوصف
operations	قائمة	نعم	قائمة بالعمليات أو الأظرف المخصصة
namespace_id	عدد صحيح	لا	معرف النطاق (يكون الافتراضي 1)
idempotency_key	سلسلة	لا	مفتاح إزالة التكرار
metadata	قاموس	لا	بيانات تعريف المستخدم
actor_id	سلسلة	لا	معرف الممثل لتتبع التدقيق
policy_id	سلسلة	لا	معرف السياسة (للاستخدام المستقبلي)
origin	قاموس	لا	بيانات تعريف الأصل الاختيارية

يعيد CommitResponse مع world_seq_start، world_seq_end، event_count، وبيانات التعريف المتعلقة بالتوافق.

طرق القراءة

# Get container balances
balances = await read_client.get_container_balances(1001)

# Get container (sync)
container = read_client.get_container_sync(1001)

تُعيد طرق القراءة كائنات استجابة ذات نوع مع بيانات تعريف عن الحداثة. يمكنك استخدام الحداثة لفرض دلالات “اقرأ ما تكتبه” في كود العميل.

بناة العمليات

استيراد البناة الفرديين أو الوحدة بالكامل:

from assetcore_sdk.operations import (
    CreateContainer,
    AddFungible,
    RemoveFungible,
    TransferFungible,
    AddInstance,
    PlaceInSlot,
    RegisterClass,
)

كل باني ينشئ فئة بيانات يمكن تحويلها إلى غلاف العملية:

op = CreateContainer(
    container_id=1001,
    kind={"type": "balance"},
    owner=None,
    policies=None,
)
# op.to_envelope() -> {"op": "CreateContainer", "args": {...}}

أنواع الأخطاء

from assetcore_sdk.errors import (
    AssetCoreError,        # Base exception
    HttpError,             # Transport failures
    ValidationError,       # 422 errors
    ConflictError,         # 409 errors
    NotFoundError,         # 404 errors
    SDKUnauthorizedError,  # 401 errors
    SDKForbiddenError,     # 403 errors
    SDKQuotaError,         # 429 errors
    TokenRefreshError      # Refresh hook failures
)

تتضمن الأخطاء جسم الاستجابة مع رمز الخطأ والتفاصيل.

أمثلة

الالتزام الأساسي

from assetcore_sdk import AssetCoreClient
from assetcore_sdk.operations import CreateContainer, AddFungible

write_client = AssetCoreClient(
    base_url="http://localhost:8080",
    api_key=os.environ["ASSETCORE_WRITE_TOKEN"],
)

operations = [
    CreateContainer(
        container_id=1001,
        kind={"type": "balance"},
        owner=None,
        policies=None,
    ),
    AddFungible(
        class_id=100,
        key=1,
        quantity=500,
        location={"container_id": 1001, "kind": "balance"},
    ),
]

result = await write_client.commit_operations(
    operations,
    idempotency_key="init-container-2026-01-15-1001",
    namespace_id=5001,
)

print(f"Committed at world seq {result.world_seq_start}")

التعامل مع الأخطاء

from assetcore_sdk.errors import ValidationError, ConflictError

try:
    result = await write_client.commit_operations(operations, namespace_id=5001)
except ValidationError as e:
    print(f"Validation failed: {e.error_code}")
    print(f"Details: {e.details}")
except ConflictError as e:
    print(f"Conflict: {e.message}")

حالة القراءة

# Get balances
balances = await read_client.get_container_balances(1001, namespace_id=5001)
for balance in balances.balances:
    print(f"Class {balance.class_id}: {balance.quantity}")

# Check freshness
print(f"Data as of world seq {balances.freshness.world_seq}")

استخدام المزامنة

للنصوص أو البيئات التي لا تحتوي على async:

import os
from assetcore_sdk import AssetCoreClient

write_client = AssetCoreClient(
    base_url="http://localhost:8080",
    api_key=os.environ["ASSETCORE_WRITE_TOKEN"],
)

read_client = AssetCoreClient(
    base_url="http://localhost:8081",
    api_key=os.environ["ASSETCORE_READ_TOKEN"],
)

# All async methods have _sync variants
result = write_client.commit_operations_sync(operations, namespace_id=5001)
balances = read_client.get_container_balances_sync(1001, namespace_id=5001)

بناء المعاملات المعقدة

from assetcore_sdk.operations import (
    RegisterClass,
    RegisterClassShape,
    AddInstance,
)

operations = [
    RegisterClass(
        request={
            "class_id": 200,
            "flags": 2,
            "name": "Sample Tube",
        }
    ),
    RegisterClassShape(
        request={
            "class_id": 200,
            "stack_key": None,
            "shape": {"width": 1, "height": 3},
        }
    ),
    AddInstance(
        class_id=200,
        key=1,
        location={"container_id": 1001, "kind": "slot", "slot_index": 1},
    ),
]

result = await write_client.commit_operations(operations, namespace_id=5001)
print(f"Committed transaction {result.commit_id}")

المراجع ذات الصلة

• البدء باستخدام Python SDK
• مرجع الإجراء
• وصفات