SDK de Python

El SDK de Python de Asset Core proporciona un cliente HTTP tipado para interactuar con los demonios de escritura y lectura, además de constructores de operaciones que se mapean directamente a JSON de transacción.

Visión general

El SDK se distribuye como el paquete assetcore-sdk y proporciona:

• AssetCoreClient: Cliente de alto nivel con métodos asíncronos y sincrónicos
• Constructores de operaciones: Funciones tipadas para las 16 operaciones
• Tipos de error: Excepciones estructuradas para el manejo de errores
• Cliente generado: capa HTTP basada en OpenAPI

El SDK es un cliente puro; invoca la API HTTP pública y no puede mutar el estado del lado del servidor directamente.

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

Campos

AssetCoreClient

La clase principal del cliente para interactuar con Asset Core.

from assetcore_sdk import AssetCoreClient

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

Parámetro	Tipo	Predeterminado	Descripción
write_url	str	http://localhost:8080	URL del daemon de escritura
read_url	str	http://localhost:8081	URL del daemon de lectura
timeout	float	30.0	Tiempo de espera de la solicitud en segundos

Métodos de Compromiso

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

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

Parámetro	Tipo	Requerido	Descripción
operations	lista	Sí	Lista de diccionarios de operaciones
idempotency_key	str	No	Clave de deduplicación
metadata	dict	No	Metadatos del usuario

Devuelve CommitResponse con global_seq, batch_seq y minted_instances.

Métodos de Lectura

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

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

Los métodos de lectura devuelven objetos de respuesta tipados con metadatos de frescura.

Constructores de Operaciones

Importar constructores individuales o el módulo completo:

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

Cada función devuelve un diccionario adecuado para la lista de operations:

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

Tipos de Error

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

Los errores incluyen el cuerpo de la respuesta con el código de error y detalles.

Ejemplos

Compromiso Básico

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

Manejo de Errores

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

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

Uso de Sincronización

Para scripts o entornos sin async:

client = AssetCoreClient()

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

Construyendo Transacciones Complejas

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

Referencias relacionadas

• Introducción al SDK de Python

Operaciones por Dominio

Recetas