SDK de Python

El SDK de Python d’Asset Core proporciona un client HTTP tipat per interactuar amb els daemons d’escriptura i lectura, a més de constructors d’operacions que es mapegen directament a JSON de transacció.

Visió general

El SDK es distribueix com el paquet assetcore-sdk i proporciona:

• AssetCoreClient: Client d’alt nivell amb mètodes asíncrons i sincrons
• Constructors d’operacions: Funcions tipades per a les 16 operacions
• Tipus d’error: Excepcions estructurades per al maneig d’errors
• Client generat: capa HTTP basada en OpenAPI

El SDK és un client pur; invoca l’API HTTP pública i no pot mutar l’estat del servidor directament.

Estructura

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

Camps

AssetCoreClient

La classe principal del client per interactuar amb Asset Core.

from assetcore_sdk import AssetCoreClient

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

Paràmetre	Tipus	Per defecte	Descripció
write_url	str	http://localhost:8080	URL del daemon d’escriptura
read_url	str	http://localhost:8081	URL del daemon de lectura
timeout	float	30.0	Temps d’espera de la sol·licitud en segons

Mètodes de Compromís

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

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

Paràmetre	Tipus	Requerit	Descripció
operations	llista	Sí	Llista de diccionaris d’operació
idempotency_key	str	No	Clau de deduplicació
metadata	dict	No	Metadades de l’usuari

Retorna CommitResponse amb global_seq, batch_seq i minted_instances.

Llegir Mètodes

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

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

Els mètodes de lectura retornen objectes de resposta tipats amb metadades de frescor.

Constructors d’Operacions

Importa constructors individuals o tot el mòdul:

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

Cada funció retorna un diccionari adequat per a la llista operations:

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

Tipus d’Error

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

Els errors inclouen el cos de resposta amb el codi d’error i detalls.

Exemples

Compromís Bàsic

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

Gestió d’Errors

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

Estat de lectura

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

Ús de la sincronització

Per a scripts o entorns sense async:

client = AssetCoreClient()

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

Construcció de Transaccions Complexes

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

Referències relacionades

• Introducció al SDK de Python

Operacions per Domini

Receptes