Python SDK

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

نظرة عامة

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

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

SDK هو عميل خالص؛ يقوم باستدعاء واجهة برمجة التطبيقات العامة HTTP ولا يمكنه تعديل حالة الخادم مباشرة.

الهيكل

إرشادات إضافية:

النبرة: رسمية
السجل: تقني

السياق:

• المجال: بنية تحتية للبلوكشين
• الجمهور: مهندسو الأمن وقادة البنية التحتية
• الغرض: وثائق تقنية
• اللغة: ar
• الاتجاه: RTL

القيود:

• استخدام لغة محايدة للجنس
• الحفاظ على أسماء العلامات التجارية
• الحفاظ على الدقة التقنية
• ضمان أن تظل علامات الترقيم والترقيم مناسبة للاتجاه RTL
• الحفاظ على أسماء العلامات التجارية والمصطلحات في القاموس دون ترجمة

الحفاظ على دون ترجمة:

• code_blocks
• inline_code
• الروابط
• glossary_terms
• الملاحظات الرياضية

إرشادات القاموس:

الحفاظ على هذه المصطلحات بالضبط (لا تترجم): Asset Core، Asset‑Core، CSP، API، Docker، ECS، daemon، L1، L2، L3، OpenGraph، GitHub، Astro، TypeScript، JavaScript، ℤ، ℤ²، ℤ³، ℝ²، ℝ³، 0D، 1D، 2D، 3D

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

الحقول

AssetCoreClient

الفئة الرئيسية للعميل للتفاعل مع Asset Core.

from assetcore_sdk import AssetCoreClient

client = AssetCoreClient(
    write_url="http://localhost:8080",
    read_url="http://localhost:8081",
    timeout=30.0
)

المعامل	النوع	الافتراضي	الوصف
write_url	str	http://localhost:8080	عنوان URL لكتابة الـ daemon
read_url	str	http://localhost:8081	عنوان URL لقراءة الـ daemon
timeout	float	30.0	مهلة الطلب بالثواني

طرق الالتزام

# Async
result = await client.commit(
    operations=[...],
    idempotency_key="unique-key"
)

# Sync
result = client.commit_sync(
    operations=[...],
    idempotency_key="unique-key"
)

المعامل	النوع	مطلوب	الوصف
operations	قائمة	نعم	قائمة بقواميس العمليات
idempotency_key	نص	لا	مفتاح إزالة التكرار
metadata	قاموس	لا	بيانات تعريف المستخدم

ترجع CommitResponse مع global_seq، batch_seq، و minted_instances.

طرق القراءة

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

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

تُعيد طرق القراءة كائنات استجابة مُعينة مع بيانات تعريف النضارة.

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

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

from assetcore_sdk.operations import (
    create_container,
    add_fungible,
    remove_fungible,
    transfer_fungible,
    mint_instance,
    place_in_slot,
    register_class
)

ترجع كل دالة قاموسًا مناسبًا لقائمة operations:

op = create_container(
    container_id=1001,
    kind="Standard"
)
# Returns: {"op": "CreateContainer", "args": {...}}

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

from assetcore_sdk.errors import (
    AssetCoreError,      # Base exception
    ValidationError,     # 422 errors
    NotFoundError,       # 404 errors
    ConflictError,       # 409 errors
    ConnectionError,     # Network failures
    ServiceUnavailable   # 503 errors
)

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

أمثلة

إرشادات إضافية:

النبرة: رسمية السجل: تقني

السياق:

• المجال: بنية تحتية للبلوك تشين
• الجمهور: مهندسو الأمان وقادة البنية التحتية
• الغرض: وثائق تقنية
• اللغة: ar
• الاتجاه: من اليمين إلى اليسار

القيود:

• استخدام لغة محايدة للجنس
• الحفاظ على أسماء العلامات التجارية
• الحفاظ على الدقة التقنية
• ضمان أن تظل علامات الترقيم والترقيم مناسبة من حيث الاتجاه
• الحفاظ على أسماء العلامات التجارية والمصطلحات غير مترجمة

الحفاظ على دون ترجمة:

• code_blocks
• inline_code
• links
• glossary_terms
• mathematical_notation

إرشادات المصطلحات:

الحفاظ على هذه المصطلحات بالضبط (لا تترجم): Asset Core, Asset‑Core, CSP, API, Docker, ECS, daemon, L1, L2, L3, OpenGraph, GitHub, Astro, TypeScript, JavaScript, ℤ, ℤ², ℤ³, ℝ², ℝ³, 0D, 1D, 2D, 3D

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

from assetcore_sdk import AssetCoreClient
from assetcore_sdk.operations import create_container, add_fungible

client = AssetCoreClient()

operations = [
    create_container(container_id=1001, kind="Standard"),
    add_fungible(
        container_id=1001,
        class_id=100,
        key=1,
        quantity=500
    )
]

result = await client.commit(
    operations=operations,
    idempotency_key="init-container-1001"
)

print(f"Committed at sequence {result.global_seq}")

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

from assetcore_sdk.errors import ValidationError, ConflictError

try:
    result = await client.commit(operations)
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 client.get_container_balances(1001)
for balance in balances.balances:
    print(f"Class {balance.class_id}: {balance.quantity}")

# Check freshness
print(f"Data as of sequence {balances.freshness.checkpoint_seq}")

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

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

إرشادات إضافية:

client = AssetCoreClient()

# All async methods have _sync variants
result = client.commit_sync(operations)
balances = client.get_container_balances_sync(1001)

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

from assetcore_sdk.operations import (
    register_class,
    register_class_shape,
    mint_instance,
    place_in_slot
)

operations = [
    register_class(
        class_id=200,
        name="Sample Tube",
        fungible=False
    ),
    register_class_shape(
        class_id=200,
        shape_id=1,
        width=1,
        height=3
    ),
    mint_instance(class_id=200, key=1),
    place_in_slot(
        container_id=1001,
        instance_id=9001,  # Known from allocation
        slot_index=0
    )
]

result = await client.commit(operations)
print(f"Minted instances: {result.minted_instances}")

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

• البدء باستخدام Python SDK

العمليات حسب المجال

وصفات