O SDK para Python

Um SDK Python totalmente tipado para a API TCGdex que permite acessar dados do Jogo de Cartas Colecionáveis Pokémon com opções assíncronas e síncronas.

from tcgdexsdk import TCGdex, Extension

# Inicializa o SDK
tcgdex = TCGdex("pt-br")

# Busca uma carta em uma linha
card = await tcgdex.card.get("swsh3-136")
# Ou use a versão síncrona
card = tcgdex.card.getSync("swsh3-136")

print(f"Encontrado: {card.name} ({card.localId}/{card.set.cardCount.total})")

Instalação e Configuração Básica

Instale o SDK usando pip:
Terminal window
```
pip install tcgdex-sdk
```

Importe e inicialize:

from tcgdexsdk import TCGdex, Language

tcgdex = TCGdex() # Inicializa com o idioma padrão (Inglês)

# Inicializa com idioma como string
tcgdex = TCGdex("pt-br")

# Ou usando o enum Language
tcgdex = TCGdex(Language.PT_BR)

Comece a fazer requisições:

# Uso assíncrono
card = await tcgdex.card.get("swsh3-136")

# Uso síncrono
card = tcgdex.card.getSync("swsh3-136")

Principais Recursos

Segurança de Tipos: Todos os modelos são completamente tipados para melhor integração com IDEs
API Dual: Interfaces assíncronas e síncronas
Consultas Flexíveis: Poderoso construtor de consultas para filtrar e ordenar resultados
Suporte Multi-idioma: Acesse dados de cartas em vários idiomas
Modelos Abrangentes: Modelos de dados detalhados para cartas, coleções, séries e muito mais
Acesso a Imagens: Acesso direto a imagens de cartas e símbolos de coleções

Endpoints

O SDK fornece endpoints especializados para diferentes tipos de dados:

sdk = TCGdex()

# Endpoint base de cartas
sdk.card          # Informação completa da carta

# Endpoints de coleções
sdk.set            # Coleções de cartas (ex: "Darkness Ablaze")
sdk.serie          # Séries de cartas (ex: "Sword & Shield")

# Endpoints de dados de cartas
sdk.rarity        # Raridades de cartas
sdk.hp            # Valores de HP
sdk.illustrator   # Ilustradores de cartas

# Endpoints de mecânicas de jogo
sdk.type          # Tipos de Pokémon
sdk.energyType    # Tipos de energia
sdk.retreat       # Custos de recuo
sdk.stage         # Estágios de evolução

# Endpoints de detalhes de cartas
sdk.variant        # Variantes de cartas (holo, reverse, etc.)
sdk.suffix         # Sufixos de cartas
sdk.regulationMark # Marcas de regulamentação
sdk.dexId          # IDs da Pokédex

Exemplos de Consultas

O SDK inclui um poderoso construtor de consultas para filtrar e ordenar resultados:

from tcgdexsdk import TCGdex, Query

sdk = TCGdex()

# Encontrar todas as cartas com um nome específico
furrets = await sdk.card.list(Query().equal("name", "Furret"))

# Encontrar cartas com 'ban' no nome do ilustrador (sem distinção entre maiúsculas/minúsculas)
ban_cards = await sdk.card.list(Query().contains("illustrator", "ban"))

# Encontrar Pokémon com HP alto, ordenados por HP
tanks = await sdk.card.list(
        Query()
                .greaterThan("hp", 200)
                .sort("hp", "desc")
)

# Encontrar cartas sem ataques mas com habilidades
basics = await sdk.card.list(
        Query()
                .isNull("attacks")
                .notNull("abilities")
)

# Suporte à paginação
page2 = await sdk.card.list(
        Query().paginate(page=2, itemsPerPage=20)
)

Suporte a Idiomas

O SDK suporta múltiplos idiomas para dados de cartas:

from tcgdexsdk import TCGdex, Language

# Usando códigos de string
en_sdk = TCGdex("en")  # Inglês
fr_sdk = TCGdex("fr")  # Francês
pt_br_sdk = TCGdex("pt-br")  # Alemão

# Usando enum para segurança de tipos
en_sdk = TCGdex(Language.EN) # padrão para inglês se não estiver definido

# Mudando o idioma em uma instância existente
sdk = TCGdex()
sdk.setLanguage(Language.PT_BR)

Lista completa de códigos de idiomas

Trabalhando com Imagens

Cartas, coleções e séries frequentemente incluem imagens que podem ser acessadas:

from tcgdexsdk.enums import Quality, Extension

# Obtém uma carta
card = await sdk.card.get("swsh3-136")

# Obtém a URL da imagem com qualidade e formato
image_url = card.get_image_url(quality="high", extension="png")
# Ou usando enums
image_url = card.get_image_url(Quality.HIGH, Extension.PNG)

# Baixa a imagem diretamente
image_data = card.get_image(Quality.HIGH, Extension.PNG)

# Coleções e séries também têm métodos de imagem
set_data = await sdk.set.get("swsh3")

logo_url = set_data.get_logo_url(Extension.PNG)
logo = set_data.get_logo(Extension.PNG)

symbol_url = set_data.get_symbol_url(Extension.WEBP)
symbol = set_data.get_symbol(Extension.WEBP)