### Example: Listing Items Synchronously with Queries

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Demonstrates fetching lists of items synchronously using the `listSync` method. Examples include listing all types and filtering cards by name and local ID.

```python
sdk = TCGdex()

# Synchronous list
all_types = sdk.type.listSync()
print(f"Types: {all_types}")

# With query
from tcgdexsdk import Query
query = Query().equal("name", "Pikachu").gte("localId", 1)
results = sdk.card.listSync(query)
```

--------------------------------

### API URL Construction Examples

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Illustrates the base format for constructing API URLs, including examples for specific endpoints and query parameter usage.

```text
https://api.tcgdex.net/v2/en/cards/swsh3-136
https://api.tcgdex.net/v2/fr/sets/Sword%20&%20Shield
https://api.tcgdex.net/v2/en/illustrators/5ban%20Graphics
```

```text
https://api.tcgdex.net/v2/en/cards?name=Pikachu&name=eq:Pikachu&sort:field=localId&sort:order=asc
```

--------------------------------

### Example: Listing Items with Queries and Pagination Asynchronously

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Illustrates fetching lists of items using various query parameters asynchronously. Examples include listing all rarities, filtering cards by name, applying multiple filters (name and HP), and paginating results.

```python
from tcgdexsdk import TCGdex, Query

sdk = TCGdex()

# List all rarities
rarities = await sdk.rarity.list()
print(f"Available rarities: {rarities}")

# List cards with filter
query = Query().equal("name", "Pikachu")
pikachus = await sdk.card.list(query)
for card in pikachus:
    print(f"{card.name} - {card.localId}")

# List with multiple filters
query = Query().equal("name", "Charizard").gte("hp", 100)
high_hp_charizards = await sdk.card.list(query)

# List with pagination
query = Query().paginate(1, 50)
first_50_cards = await sdk.card.list(query)
```

--------------------------------

### API Endpoint Examples

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Examples of constructing API endpoints for different languages and paths.

```text
https://api.tcgdex.net/v2/en/cards/swsh3-136
https://api.tcgdex.net/v2/fr/sets/Darkness%20Ablaze
https://api.tcgdex.net/v2/ja/series/swsh
```

--------------------------------

### Example: Fetching and Processing Items Asynchronously

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Demonstrates fetching a card, a set, and an illustrator's cards by their IDs using the asynchronous `get` method. Includes checks for successful retrieval and prints relevant information.

```python
from tcgdexsdk import TCGdex

sdk = TCGdex()

# Fetch a card by ID
card = await sdk.card.get("swsh3-136")
if card:
    print(f"{card.name}: {card.localId}/{card.set.cardCount.total}")

# Fetch a set
set_data = await sdk.set.get("Sword & Shield")
if set_data:
    print(f"Set has {set_data.cardCount.total} cards")

# Fetch illustrator endpoint (returns StringEndpoint with cards list)
illustrator = await sdk.illustrator.get("5ban Graphics")
if illustrator:
    for card in illustrator.cards:
        print(card.name)
```

--------------------------------

### Install TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Command to install the TCGdex Python SDK using pip.

```bash
pip install tcgdex-sdk
```

--------------------------------

### Get Series Logo URL and Data

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/serie-model.md

Demonstrates how to get the logo URL for a series in a specified extension (e.g., PNG) and how to download the logo data in a different format (e.g., WebP). Requires the series to have a logo.

```python
from tcgdexsdk import Extension

sdk = TCGdex()
serie = await sdk.serie.get("swsh")

if serie and serie.logo:
    logo_url = serie.get_logo_url(Extension.PNG)
    print(f"Logo URL: {logo_url}")
    
    response = serie.get_logo("webp")
    if response:
        with open(f"{serie.id}_logo.webp", "wb") as f:
            f.write(response.read())
```

--------------------------------

### Multi-Language SDK Setup

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Instantiate the SDK for different languages or switch the language of a single instance. This allows fetching data in English, French, and Japanese.

```python
from tcgdexsdk import TCGdex, Language

# Create instances for different languages
en_sdk = TCGdex(Language.EN)
fr_sdk = TCGdex(Language.FR)
ja_sdk = TCGdex(Language.JA)

# Or use a single instance and switch
sdk = TCGdex(Language.EN)

# Get card in English
card = await sdk.card.get("swsh3-136")
en_name = card.stage

# Switch language
sdk.setLanguage(Language.FR)
card = await sdk.card.get("swsh3-136")
fr_name = card.stage

# Switch again
sdk.setLanguage(Language.JA)
card = await sdk.card.get("swsh3-136")
ja_name = card.stage
```

--------------------------------

### Initialize Query Object

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Create a new, empty query object to start building API requests.

```python
from tcgdexsdk import Query

query = Query()
```

--------------------------------

### Usage Examples

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Demonstrates various ways to use the Query class for filtering, sorting, and pagination in API requests.

```APIDOC
## Usage Examples

### Simple Filter

```python
from tcgdexsdk import TCGdex, Query

sdk = TCGdex()

# Find all Pikachu cards
query = Query().equal("name", "Pikachu")
pikachus = await sdk.card.list(query)
```

### Multiple Filters (AND logic)

```python
# High HP fire type cards
query = Query().gte("hp", 100).equal("types", "Fire")
cards = await sdk.card.list(query)

# Cards with no illustrator
query = Query().isNull("illustrator")
mystery_cards = await sdk.card.list(query)
```

### Range Queries

```python
# Cards with HP between 80 and 120
query = Query().gte("hp", 80).lte("hp", 120)
mid_range = await sdk.card.list(query)

# Cards with localId < 50
query = Query().lesserThan("localId", 50)
early_cards = await sdk.card.list(query)
```

### Sorting and Pagination

```python
# Get first 50 cards sorted by local ID
query = Query().sort("localId", "asc").paginate(1, 50)
first_batch = await sdk.card.list(query)

# Get second 50 cards
query = Query().sort("localId", "asc").paginate(2, 50)
second_batch = await sdk.card.list(query)
```

### Complex Query

```python
# All non-EX Water-type Pokémon with HP >= 90, sorted by name descending
query = (
    Query()
    .notContains("name", "EX")
    .equal("types", "Water")
    .gte("hp", 90)
    .sort("name", "desc")
)
cards = await sdk.card.list(query)
```

### Chaining Pattern

```python
# Queries are built step-by-step with full chainability
query = (
    Query()
    .contains("name", "Pikachu")
    .gte("localId", 1)
    .lt("localId", 100)
    .notNull("image")
    .sort("localId", "asc")
    .paginate(1, 25)
)

results = await sdk.card.list(query)
```
```

--------------------------------

### Combine Multiple Query Options

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Example of combining multiple query configurations including filtering, sorting, and pagination.

```python
# Combine multiple options
query = (
    Query()
    .equal("name", "Pikachu")
    .gte("hp", 50)
    .sort("localId", "asc")
    .paginate(1, 25)
)

results = await sdk.card.list(query)
```

--------------------------------

### Get Card Image URL with Options

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Demonstrates how to obtain image URLs for a card with specified quality and format.

```python
card = await sdk.card.get("swsh3-136")

# High quality PNG
url_hq = card.get_image_url(Quality.HIGH, Extension.PNG)

# Low quality WebP for bandwidth efficiency
url_lq = card.get_image_url(Quality.LOW, Extension.WEBP)

# String values also work
url = card.get_image_url("high", "jpg")
```

--------------------------------

### Fetch and Filter Cards

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Example of fetching all cards and then filtering them client-side based on a condition (HP >= 100).

```python
# Get all cards and process
all_cards = await sdk.card.list()
high_hp = [c for c in all_cards if c.hp and c.hp >= 100]
```

--------------------------------

### API Endpoint Structure Example

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/index.md

Illustrates the base URL and the format for constructing API requests, including language, endpoint, and optional query parameters.

```text
https://api.tcgdex.net/v2/en/cards/swsh3-136
```

```text
https://api.tcgdex.net/v2/fr/sets/Darkness%20Ablaze?name=eq:Charizard
```

--------------------------------

### Example: Fetching Items Synchronously

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Demonstrates fetching a card and a series by their IDs using the synchronous `getSync` method. Includes checks for successful retrieval and prints relevant information.

```python
sdk = TCGdex()

# Synchronous fetch
card = sdk.card.getSync("swsh3-136")
if card:
    print(f"Card: {card.name}")

# Get a series
serie = sdk.serie.getSync("swsh")
if serie:
    print(f"Series: {serie.name} with {len(serie.sets)} sets")
```

--------------------------------

### Query Constructor

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Initializes a new, empty Query object. This is the starting point for building API queries.

```APIDOC
## Constructor

```python
Query() -> Query
```

Creates a new empty query object.

**Example:**
```python
from tcgdexsdk import Query

query = Query()
```
```

--------------------------------

### Simple Filter Example

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Demonstrates how to find cards matching a single criterion, such as a specific name. Requires importing TCGdex and Query.

```python
from tcgdexsdk import TCGdex, Query

sdk = TCGdex()

# Find all Pikachu cards
query = Query().equal("name", "Pikachu")
pikachus = await sdk.card.list(query)
```

--------------------------------

### Multiple Filters (AND Logic)

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Shows how to combine multiple filters using AND logic for more specific searches. Includes examples for numeric ranges and checking for null values.

```python
# High HP fire type cards
query = Query().gte("hp", 100).equal("types", "Fire")
cards = await sdk.card.list(query)

# Cards with no illustrator
query = Query().isNull("illustrator")
mystery_cards = await sdk.card.list(query)
```

--------------------------------

### Get Set Logo URL from Series with TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/setresume-model.md

Fetches the logo URL for each set within a series. It checks if a logo exists before attempting to get the URL. Requires initializing the TCGdex SDK and fetching a series.

```python
from tcgdexsdk import Extension

sdk = TCGdex()
serie = await sdk.serie.get("swsh")

if serie:
    for set_resume in serie.sets:
        if set_resume.logo:
            logo_url = set_resume.get_logo_url(Extension.PNG)
            print(f"{set_resume.name}: {logo_url}")
```

--------------------------------

### Working with Sets and Series Data

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Demonstrates fetching details for a specific card set and retrieving information about a series. Includes examples for both async and sync operations.

```python
# Get set details
darkness_ablaze = await sdk.set.get("Darkness Ablaze")
# darkness_ablaze = sdk.set.getSync("Darkness Ablaze")
print(f"Set: {darkness_ablaze.name} ({darkness_ablaze.cardCount.total} cards)")

# Get series info
swsh = await sdk.serie.get("swsh")
# swsh = sdk.serie.getSync("swsh")
print(f"Series: {swsh.name} ({len(swsh.sets)} sets)")
```

--------------------------------

### Error Handling

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Provides an example of how to handle potential exceptions that may occur during API requests.

```APIDOC
## Error Handling

### Description
Implement try-except blocks to gracefully handle potential errors during API interactions, such as network issues or invalid requests.

### Code Example
```python
try:
    card = await sdk.card.get("nonexistent-id")
    if card:
        print(f"Found: {card.name}")
    else:
        print("Card not found")
except Exception as e:
    print(f"API error: {e}")
```
```

--------------------------------

### Change Language Mid-Session (Async)

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Illustrates how to change the SDK's language setting dynamically without needing to create a new instance. This example fetches a card in English and then in French.

```python
sdk = TCGdex("en")
card = await sdk.card.get("swsh3-136")
print(f"English: {card.name}")

sdk.setLanguage("fr")
french_card = await sdk.card.get("swsh3-136")
print(f"French: {french_card.name}")
```

--------------------------------

### Instantiate TCGdex SDK Once

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Create a single TCGdex instance for a given language and reuse it throughout your application. Avoid creating new instances repeatedly, as shown in the 'Avoid' example.

```python
# Good
_SDK = TCGdex("en")

async def fetch_card(card_id):
    return await _SDK.card.get(card_id)

# Avoid
async def fetch_card(card_id):
    sdk = TCGdex("en")  # Creates new instance every time
    return await sdk.card.get(card_id)
```

--------------------------------

### Get Set Logo URL

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/set-model.md

Constructs the full URL for a set's logo. Specify the desired image format (PNG, JPG, or WEBP).

```python
from tcgdexsdk import TCGdex, Extension

sdk = TCGdex()
set_data = await sdk.set.get("Darkness Ablaze")

logo_url = set_data.get_logo_url(Extension.PNG)
print(f"Download logo: {logo_url}")
```

--------------------------------

### Fetch a Card by ID (Async and Sync)

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Demonstrates how to retrieve a specific card using its ID. Supports both asynchronous and synchronous methods. Ensure the `tcgdexsdk` library is installed.

```python
from tcgdexsdk import TCGdex

sdk = TCGdex()

# Async method
card = await sdk.card.get("swsh3-136")
print(f"Card: {card.name}")

# Synchronous method
card = sdk.card.getSync("swsh3-136")
print(f"HP: {card.hp}")
```

--------------------------------

### Migrate from Deprecated URI Property

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/errors.md

Shows the old method of accessing the URI property and the new recommended methods for setting and getting the endpoint.

```python
# Old (deprecated)
sdk.URI = "https://api.tcgdex.net/v2"
url = sdk.URI

# New
sdk.setEndpoint("https://api.tcgdex.net/v2")
url = sdk.getEndpoint()
```

--------------------------------

### Explore Series Structure from Card

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/serieresume-model.md

Navigate the relationship from a card to its series and then fetch the full series details. This example demonstrates how to traverse from a card to its set, then to its series, and finally retrieve all sets within that series.

```python
sdk = TCGdex()

# Get a card
card = await sdk.card.get("swsh3-136")

if card:
    # Navigate: Card -> Set -> Serie
    set_data = card.set
    serie_resume = set_data.serie
    
    # Fetch full serie
    full_serie = await serie_resume.get_full_serie()
    if full_serie:
        print(f"Card {card.name} is in:")
        print(f"  Set: {set_data.name}")
        print(f"  Series: {full_serie.name}")
        print(f"  Series has {len(full_serie.sets)} sets:")
        for s in full_serie.sets:
            print(f"    - {s.name}")
```

--------------------------------

### Get Set Symbol URL

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/set-model.md

Constructs the full URL for a set's symbol. Specify the desired image format (png, jpg, or webp).

```python
symbol_url = set_data.get_symbol_url("png")
```

--------------------------------

### Range Queries

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Illustrates how to perform range queries for numeric fields using greater than or equal to (gte) and less than or equal to (lte) operators. Also shows a less than (lt) example.

```python
# Cards with HP between 80 and 120
query = Query().gte("hp", 80).lte("hp", 120)
mid_range = await sdk.card.list(query)

# Cards with localId < 50
query = Query().lesserThan("localId", 50)
early_cards = await sdk.card.list(query)
```

--------------------------------

### Find Cards by Illustrator, Series, HP, and Rarity

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Examples of querying cards based on illustrator, series ID, HP, and listing all available rarities. Also shows how to list cards by name using a query.

```python
sdk = TCGdex("en")

# Get the cards made by the illustrator
cards = await sdk.illustrator.get("5ban Graphics")
cards = sdk.illustrator.getSync("5ban Graphics")

# Get the data about the Sword & Shield serie by ID
series = await sdk.serie.get("swsh")
series = sdk.serie.getSync("swsh")

# Get all cards with 110 HP
hp_cards = await sdk.hp.get("110")
hp_cards = sdk.hp.getSync("110")

# List all available rarities
rarities = await sdk.rarity.list()
rarities = sdk.rarity.listSync()

# List all cards with the name being "Furret"
rarities = await sdk.card.list(Query().equal("name", "Furret"))
rarities = sdk.card.listSync(Query().equal("name", "Furret"))
```

--------------------------------

### Basic Usage and Type Hinting

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/index.md

Demonstrates how to initialize the SDK and fetch card data using type hints for improved IDE support and code clarity.

```APIDOC
## Basic Usage and Type Hinting

The SDK provides full type hints for IDE integration:

```python
from tcgdexsdk import TCGdex, Card, CardResume, Query

# Initialize the SDK
sdk: TCGdex = TCGdex()

# Fetch a single card by ID
card: Card = await sdk.card.get("swsh3-136")

# Fetch a list of cards
cards: list[CardResume] = await sdk.card.list()

# Create a query object
query: Query = Query().equal("name", "Pikachu")
```
```

--------------------------------

### Iterate Set Cards with TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/cardresume-model.md

Demonstrates how to get a specific set and iterate through its card summaries, printing card names and local IDs. It also shows how to retrieve the image URL for each card.

```python
from tcgdexsdk import TCGdex


sdk = TCGdex()

# Get a set
darkness_ablaze = await sdk.set.get("Darkness Ablaze")

if darkness_ablaze:
    # Iterate card summaries
    for card_resume in darkness_ablaze.cards:
        print(f"{card_resume.name} ({card_resume.localId})")
        
        # Get image URL
        image_url = card_resume.get_image_url("high", "png")
        if image_url:
            print(f"  Image: {image_url}")
```

--------------------------------

### StringEndpoint Usage Example

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Demonstrates how StringEndpoint objects are returned when performing attribute lookups, such as fetching rarity information. The returned object provides access to attributes like name and associated cards.

```python
rarity = await sdk.rarity.get("Rare Holo")  # Returns StringEndpoint
# rarity.name == "Rare Holo"
# rarity.cards == [CardResume, CardResume, ...]
```

--------------------------------

### Initialize Query for Range and Pagination

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Shows how to set up queries for numerical ranges and pagination.

```python
# Range queries
query = Query().gte("hp", 100).lte("hp", 150)

# Pagination
query = Query().paginate(1, 50)
```

--------------------------------

### Get Card Image URL

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/card-model.md

Demonstrates how to obtain image URLs for a card in different qualities and formats (PNG, WebP). Use the `Quality` enum or string values for quality, and string values for extension.

```python
from tcgdexsdk import Quality, Extension

card = await sdk.card.get("swsh3-136")

# Get high quality PNG URL
png_url = card.get_image_url(Quality.HIGH, Extension.PNG)
print(f"Download: {png_url}")

# Get low quality WebP URL
webp_url = card.get_image_url("low", "webp")
```

--------------------------------

### Access Card from Set Details with TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/setresume-model.md

Fetches the full details of the first card within a specific set. This involves getting the full set details first, then accessing and retrieving the full card information. Requires initializing the TCGdex SDK.

```python
sdk = TCGdex()
serie = await sdk.serie.get("swsh")

if serie and serie.sets:
    full_set = await serie.sets[0].get_full_set()
    if full_set and full_set.cards:
        # Get first card in set
        card_resume = full_set.cards[0]
        full_card = await card_resume.get_full_card()
        if full_card:
            print(f"Card: {full_card.name}")
```

--------------------------------

### Initialize SDK and List Cards with Query

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/index.md

Shows how to initialize the TCGdex SDK and list cards based on a query. This is useful for searching and filtering cards, such as finding all cards named 'Pikachu'.

```python
from tcgdexsdk import Query
query = Query().equal("name", "Pikachu")
pikachus = await sdk.card.list(query)
```

--------------------------------

### SDK Initialization and Basic Usage

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Demonstrates how to initialize the TCGdex SDK and perform basic operations like fetching a single card or a list of cards.

```APIDOC
## SDK Initialization and Basic Usage

### Description
Initialize the TCGdex SDK and perform basic operations such as fetching a single card by its ID or retrieving a list of all cards.

### Code Example
```python
from tcgdexsdk import TCGdex

# Initialize the SDK
sdk = TCGdex()

# Fetch a single card by ID (static type checker knows this is Card)
card = await sdk.card.get("swsh3-136")

# Fetch a list of all cards (static type checker knows this is List[CardResume])
cards = await sdk.card.list()

# Fetch a specific rarity (static type checker knows this is StringEndpoint)
rarity = await sdk.rarity.get("Rare")
```
```

--------------------------------

### Get Current API Language

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Retrieve the current language setting for API requests.

```python
current_lang = sdk.getLanguage()
```

--------------------------------

### Initialize SDK and Fetch a Card

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/index.md

Demonstrates how to initialize the TCGdex SDK and fetch a specific card by its ID. This is useful for retrieving detailed information about a single card.

```python
from tcgdexsdk import TCGdex


sdk = TCGdex()

# Fetch a card
card = await sdk.card.get("swsh3-136")
print(f"Card: {card.name} ({card.localId}/{card.set.cardCount.total})")
```

--------------------------------

### Get Series Logo URL

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/serie-model.md

Generates a URL for the series logo in a specified format.

```APIDOC
## Get Series Logo URL

### Description
Generates a URL for the series logo in a specified format.

### Method
`Serie.get_logo_url(extension: Extension)`

### Parameters
#### Path Parameters
- **extension** (Extension) - Required - The desired file extension for the logo (e.g., Extension.PNG).

### Response
- `str` - The URL of the series logo.

### Example
```python
from tcgdexsdk import Extension, TCGdex

async def main():
    sdk = TCGdex()
    serie = await sdk.serie.get("swsh")

    if serie and serie.logo:
        logo_url = serie.get_logo_url(Extension.PNG)
        print(f"Logo URL: {logo_url}")
```
```

--------------------------------

### Initialize Query for Sorting

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Illustrates how to configure sorting for query results.

```python
# Sorting
query = Query().sort("localId", "asc")
```

--------------------------------

### Get Current API Endpoint

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Retrieve the currently configured API endpoint URL.

```python
sdk = TCGdex()
print(sdk.getEndpoint())  # "https://api.tcgdex.net/v2"
```

--------------------------------

### Get Set Details

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Retrieves detailed information about a specific Pokémon TCG set.

```APIDOC
## Get Set Details

### Description
Fetches detailed information about a specific card set.

### Method
`get(set_name: str)` (async)
`getSync(set_name: str)` (sync)

### Parameters
#### Path Parameters
- **set_name** (str) - Required - The name of the set (e.g., "Darkness Ablaze").

### Request Example
```python
from tcgdexsdk import TCGdex

# Async
darkness_ablaze = await TCGdex().set.get("Darkness Ablaze")

# Sync
darkness_ablaze = TCGdex().set.getSync("Darkness Ablaze")
print(f"Set: {darkness_ablaze.name} ({darkness_ablaze.cardCount.total} cards)")
```

### Response
#### Success Response (200)
- **set** (object) - Detailed information about the set, including its name and card count.
```

--------------------------------

### Initialize SDK with Language

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Demonstrates how to initialize the TCGdex SDK and set the desired language for API responses.

```APIDOC
## Initialize SDK with Language

### Description
Initializes the TCGdex SDK, specifying the language for the data.

### Method
`TCGdex(language: str | Language)`
`setLanguage(language: str | Language)`

### Parameters
#### Constructor Parameters
- **language** (str | Language) - Optional - The desired language code (e.g., "en", "fr") or `Language` enum value.

#### Method Parameters
- **language** (str | Language) - The language code or enum value to set.

### Request Example
```python
from tcgdexsdk import TCGdex, Language

# Initialize with language string
sdk_en = TCGdex("en")
sdk_fr = TCGdex("fr")

# Initialize with Language enum
sdk_en_enum = TCGdex(Language.EN)

# Change language after initialization
sdk = TCGdex("en")
sdk.setLanguage(Language.FR)
print(f"Current language set to: {sdk.language}")
```

### Response
#### Success Response
- **sdk** (TCGdex) - An instance of the TCGdex SDK configured with the specified language.
```

--------------------------------

### Query Cards with Filters (Async)

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Demonstrates how to query for cards using specific filters, such as matching a name or meeting a minimum HP requirement. Requires importing the `Query` class. These are asynchronous operations.

```python
from tcgdexsdk import TCGdex, Query

sdk = TCGdex()

# Find all cards named "Furret"
query = Query().equal("name", "Furret")
cards = await sdk.card.list(query)

# Find cards with HP >= 100
query = Query().gte("hp", 100)
high_hp_cards = await sdk.card.list(query)
```

--------------------------------

### Get Serie by ID

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Retrieves information about a specific Pokémon TCG series using its ID.

```APIDOC
## Get Serie by ID

### Description
Fetches details about a specific series (e.g., Sword & Shield).

### Method
`get(serie_id: str)` (async)
`getSync(serie_id: str)` (sync)

### Parameters
#### Path Parameters
- **serie_id** (str) - Required - The identifier for the series (e.g., "swsh").

### Request Example
```python
from tcgdexsdk import TCGdex

# Async
series = await TCGdex().serie.get("swsh")

# Sync
series = TCGdex().serie.getSync("swsh")
print(f"Series: {series.name} ({len(series.sets)} sets)")
```

### Response
#### Success Response (200)
- **series** (object) - Information about the series, including its name and associated sets.
```

--------------------------------

### Initialize Query for Filtering

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Demonstrates how to initialize a Query object for filtering by an exact match.

```python
from tcgdexsdk import Query

# Filtering
query = Query().equal("name", "Pikachu")
```

--------------------------------

### Get Trainer Type Breakdown

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Lists all available trainer types. Requires initializing the TCGdex SDK.

```python
sdk = TCGdex()

# Get all trainer types
trainer_types = await sdk.trainerType.list()
print("Available trainer types:")
for type_str in trainer_types:
    print(f"  - {type_str}")
```

--------------------------------

### Build a Card Catalog from a Set

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/cardresume-model.md

Shows how to create a catalog of cards from a specific set, storing card ID, name, local ID, and a low-quality image URL for each card.

```python
sdk = TCGdex()

# Collect cards from a set
set_data = await sdk.set.get("Darkness Ablaze")
catalog = {}

if set_data:
    for card_resume in set_data.cards:
        catalog[card_resume.id] = {
            "name": card_resume.name,
            "localId": card_resume.localId,
            "image": card_resume.get_image_url("low", "webp")
        }

# Print summary
for card_id, info in catalog.items():
    print(f"{info['localId']:3d} {info['name']:30s} {info['image']}")
```

--------------------------------

### Get Current Language

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Retrieve the currently configured language. Returns the language enum value or string.

```python
sdk = TCGdex("fr")
lang = sdk.getLanguage()  # "fr" or Language.FR (depending on how it was set)
```

--------------------------------

### Get Current API Endpoint

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Retrieve the currently configured API endpoint URL. Defaults to https://api.tcgdex.net/v2.

```python
api_url = sdk.getEndpoint()
print(api_url)  # https://api.tcgdex.net/v2
```

--------------------------------

### Get Trainer Type Breakdown

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Lists all available trainer types. This is useful for filtering or understanding cards with the 'Trainer' type.

```APIDOC
## List Trainer Types

### Description
Retrieves a list of all available trainer types.

### Method
`sdk.trainerType.list()`

### Response
#### Success Response (200)
- (list) - A list of strings, where each string is an available trainer type.

### Request Example
```python
trainer_types = await sdk.trainerType.list()
print("Available trainer types:")
for type_str in trainer_types:
    print(f"  - {type_str}")
```
```

--------------------------------

### Get All Cards of a Specific Rarity

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Fetches and displays all cards belonging to a specified rarity. Requires initializing the TCGdex SDK.

```python
from tcgdexsdk import TCGdex

sdk = TCGdex()

# Get all Rare Holo cards
rarity_endpoint = await sdk.rarity.get("Rare Holo")
if rarity_endpoint:
    print(f"Rarity: {rarity_endpoint.name}")
    print(f"Cards: {len(rarity_endpoint.cards)}")
    
    for card in rarity_endpoint.cards:
        print(f"  {card.name} ({card.id})")
```

--------------------------------

### get(id: str)

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Fetches a single item by its ID asynchronously. Returns an Item object or None if not found or invalid.

```APIDOC
## get(id: str)

### Description
Fetch a single item by its ID asynchronously.

### Parameters
#### Path Parameters
- **id** (str) - Required - The item's unique identifier. Spaces are automatically URL-encoded to `%20`

### Returns
- Optional[Item] - An instance of `Item` type, or `None` if not found or the response is invalid

### Throws/Rejects
- Raises `URLError` if the HTTP request fails
- Returns `None` if the response cannot be deserialized to the expected type

### Example
```python
from tcgdexsdk import TCGdex

async def example_get():
    sdk = TCGdex()
    card = await sdk.card.get("swsh3-136")
    if card:
        print(f"{card.name}: {card.localId}/{card.set.cardCount.total}")

    set_data = await sdk.set.get("Sword & Shield")
    if set_data:
        print(f"Set has {set_data.cardCount.total} cards")

    illustrator = await sdk.illustrator.get("5ban Graphics")
    if illustrator:
        for card in illustrator.cards:
            print(card.name)
```
```

--------------------------------

### Build Set Catalog with TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/setresume-model.md

Constructs a catalog of all series and their sets, including the number of cards in each set. It fetches all series, then iterates through each series to gather set information. Requires initializing the TCGdex SDK.

```python
sdk = TCGdex()
all_series = await sdk.serie.list()

catalog = {}
for serie_resume in all_series:
    full_serie = await serie_resume.get_full_serie()
    if full_serie:
        catalog[full_serie.name] = []
        for set_resume in full_serie.sets:
            catalog[full_serie.name].append({
                "name": set_resume.name,
                "cards": set_resume.cardCount.total,
                "id": set_resume.id
            })

# Display
for serie_name, sets in catalog.items():
    print(f"\n{serie_name}")
    for s in sets:
        print(f"  {s['name']:30s} - {s['cards']:3d} cards")
```

--------------------------------

### Fetch a Card by ID

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/index.md

Retrieve a specific card using its unique ID. This is useful for getting detailed information about a single card.

```python
from tcgdexsdk import TCGdex

sdk = TCGdex()
card = await sdk.card.get("swsh3-136")

if card:
    print(f"Card: {card.name}")
    print(f"HP: {card.hp}")
    print(f"Rarity: {card.rarity}")
```

--------------------------------

### Fetch and Filter Pattern

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/endpoint-class.md

Demonstrates how to fetch all items and then filter them client-side based on specific criteria.

```APIDOC
## Fetch and Filter

### Description
This pattern involves fetching all available items from an endpoint and then applying client-side filtering based on specific conditions.

### Code Example
```python
# Get all cards and process
all_cards = await sdk.card.list()
high_hp = [c for c in all_cards if c.hp and c.hp >= 100]
```
```

--------------------------------

### Fetch Full Card Details from Summary

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/cardresume-model.md

Shows how to obtain a card summary from a set and then upgrade it to fetch full card details, including rarity, HP, and attack information.

```python
sdk = TCGdex()

# Get first card from a set
set_data = await sdk.set.get("Base Set")
if set_data and set_data.cards:
    card_resume = set_data.cards[0]
    print(f"Resume: {card_resume.name} - {card_resume.id}")
    
    # Upgrade to full card
    full_card = await card_resume.get_full_card()
    if full_card:
        print(f"Full details: {full_card.rarity}, {full_card.hp} HP")
        if full_card.attacks:
            for attack in full_card.attacks:
                print(f"  Attack: {attack.name}")
```

--------------------------------

### Build Query String

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Constructs the query string for API requests. Called internally by Endpoint.list(). Returns a query string starting with '?'.

```python
def build(self) -> str
```

```python
query = Query().equal("name", "Pikachu").gte("hp", 100)
query_string = query.build()
# Result: "?name=eq:Pikachu&hp=gte:100"
```

--------------------------------

### Complex Query Example

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Combines multiple filtering conditions (notContains, equal, gte) with sorting in descending order to create a sophisticated query.

```python
# All non-EX Water-type Pokémon with HP >= 90, sorted by name descending
query = (
    Query()
    .notContains("name", "EX")
    .equal("types", "Water")
    .gte("hp", 90)
    .sort("name", "desc")
)
cards = await sdk.card.list(query)
```

--------------------------------

### Get All Cards from a Set

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/setresume-model.md

Fetches a series, then retrieves the full set details and all associated cards. Requires an initialized TCGdex SDK instance.

```python
sdk = TCGdex()
serie = await sdk.serie.get("swsh")

if serie:
    full_set = await serie.sets[0].get_full_set()
    if full_set:
        all_cards = full_set.cards
        print(f"All {len(all_cards)} cards in {full_set.name}")
```

--------------------------------

### Get Cards by Illustrator

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Retrieves all cards illustrated by a specific artist. The result contains the illustrator's name and a list of their illustrated cards.

```APIDOC
## Get Illustrator Endpoint

### Description
Retrieves all cards illustrated by a specific illustrator.

### Method
`sdk.illustrator.get(illustrator_name: str)`

### Parameters
#### Path Parameters
- **illustrator_name** (string) - Required - The name of the illustrator (e.g., "5ban Graphics").

### Response
#### Success Response (200)
- **name** (string) - The name of the illustrator.
- **cards** (list) - A list of card objects illustrated by this artist.

### Request Example
```python
illustrator = await sdk.illustrator.get("5ban Graphics")
if illustrator:
    print(f"Illustrator: {illustrator.name}")
    print(f"Cards illustrated: {len(illustrator.cards)}")
```
```

--------------------------------

### TCGdex SDK Language Support

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Illustrates how to initialize the TCGdex SDK with a specific language, using either string codes or the Language enum. Also shows how to change the language after instantiation.

```python
from tcgdexsdk import TCGdex, Language

# Using string
 sdk = TCGdex("en")  # English
 sdk = TCGdex("fr")  # French

# Using enum (type-safe)
 sdk = TCGdex(Language.EN)
 sdk = TCGdex(Language.FR)

# After creating the instance you can change at any time the language
 sdk.setLanguage(Language.FR)
# or
 sdk.setLanguage("fr")
```

--------------------------------

### Configurable SDK Factory Pattern

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/configuration.md

Implement a factory pattern to create SDK instances with configurable environments (production, staging, testing) and languages. This centralizes SDK creation logic.

```python
from tcgdexsdk import TCGdex, Language

class SDKFactory:
    def __init__(self, env="production", language="en"):
        self.env = env
        self.language = language
        self.sdk = None
    
    def create(self):
        if self.env == "production":
            endpoint = "https://api.tcgdex.net/v2"
        elif self.env == "staging":
            endpoint = "https://staging.api.tcgdex.net/v2"
        else:
            endpoint = "http://localhost:3000/v2"
        
        self.sdk = TCGdex(self.language)
        self.sdk.setEndpoint(endpoint)
        return self.sdk

# Usage
factory = SDKFactory(env="testing", language="fr")
sdk = factory.create()
```

--------------------------------

### Get Cards by Illustrator

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Fetches cards illustrated by a specific artist and prints their names and local IDs. Requires initializing the TCGdex SDK.

```python
sdk = TCGdex()

illustrator = await sdk.illustrator.get("5ban Graphics")
if illustrator:
    print(f"Illustrator: {illustrator.name}")
    print(f"Cards illustrated: {len(illustrator.cards)}")
    
    for card in illustrator.cards:
        print(f"  {card.name} - {card.localId}")
```

--------------------------------

### Download Card Image using TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/cardresume-model.md

Demonstrates how to download a card image in a specified quality and extension, then save it to a local file. Requires the `Quality` and `Extension` enums.

```python
from tcgdexsdk import Quality, Extension

sdk = TCGdex()
set_data = await sdk.set.get("Sword & Shield")

if set_data and set_data.cards:
    card_resume = set_data.cards[0]
    
    # Download
    response = card_resume.get_image(Quality.HIGH, Extension.PNG)
    if response:
        with open(f"{card_resume.id}.png", "wb") as f:
            f.write(response.read())
```

--------------------------------

### Get Series from a Set

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/serieresume-model.md

Fetch the series details directly from a given set. This is useful when you already have the set information and need to find its parent series.

```python
sdk = TCGdex()
set_data = await sdk.set.get("Darkness Ablaze")

if set_data:
    serie_resume = set_data.serie
    print(f"Set: {set_data.name}")
    print(f"Series: {serie_resume.name} ({serie_resume.id})")
```

--------------------------------

### Async and Synchronous Operations

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/index.md

Illustrates how to perform operations using both asynchronous (async/await) and synchronous methods provided by the SDK.

```APIDOC
## Async and Sync Support

All endpoints support both async and synchronous operations:

```python
# Async operations
card = await sdk.card.get("swsh3-136")
cards = await sdk.card.list()

# Synchronous operations
card = sdk.card.getSync("swsh3-136")
cards = sdk.card.listSync()
```
```

--------------------------------

### Get Series from a Card

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/serieresume-model.md

Retrieve the series information associated with a specific card. This requires fetching the card first, then accessing its set and subsequently its series.

```python
from tcgdexsdk import TCGdex


sdk = TCGdex()
card = await sdk.card.get("swsh3-136")

if card:
    set_data = card.set
    serie_resume = set_data.serie
    
    print(f"Card: {card.name}")
    print(f"Set: {set_data.name}")
    print(f"Series: {serie_resume.name}")
```

--------------------------------

### Initialize TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Instantiate the TCGdex SDK. You can specify the language for API responses using language codes or enum values. Defaults to English.

```python
from tcgdexsdk import TCGdex, Language

# Using default English
sdk = TCGdex()

# Using French
sdk = TCGdex("fr")
sdk = TCGdex(Language.FR)
```

--------------------------------

### TCGdex Constructor

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/tcgdex-class.md

Initializes the TCGdex SDK client. You can specify the desired language for API responses.

```APIDOC
## TCGdex Constructor

### Description
Initializes the TCGdex SDK client. You can specify the desired language for API responses.

### Signature
```python
TCGdex(language: Union[str, Language] = Language.EN) -> TCGdex
```

### Parameters
#### Path Parameters
* **language** (Union[str, Language]) - Optional - The language for API responses. Accepts language enum values (EN, FR, ES, etc.) or language code strings ("en", "fr", "es", etc.). Defaults to `Language.EN`.

### Returns
- TCGdex instance

### Example
```python
from tcgdexsdk import TCGdex, Language

# Using default English
sdk = TCGdex()

# Using French
sdk = TCGdex("fr")
sdk = TCGdex(Language.FR)
```
```

--------------------------------

### Fetch Card Data with TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/README.md

Demonstrates how to fetch a specific card by its ID using both asynchronous and synchronous methods. Requires the card ID as input.

```python
from tcgdexsdk import TCGdex

# Fetch a card in one line
card = await TCGdex().card.get("swsh3-136")
card = TCGdex().card.getSync("swsh3-136")
print(f"Found: {card.name} ({card.localId}/{card.set.cardCount.total})")
```

--------------------------------

### Find All Fire Type Cards

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/stringendpoint-model.md

Retrieves and lists cards of a specific type, with an example of accessing the first 10 cards. Requires initializing the TCGdex SDK.

```python
sdk = TCGdex()

fire_type = await sdk.type.get("Fire")
if fire_type:
    print(f"Type: {fire_type.name}")
    print(f"Total fire type cards: {len(fire_type.cards)}")
    
    # Get first 10
    for card in fire_type.cards[:10]:
        print(f"  {card.name}")
```

--------------------------------

### Sorting and Pagination

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/query-class.md

Demonstrates how to sort query results by a specified field and direction, and how to paginate through results by specifying page number and items per page.

```python
# Get first 50 cards sorted by local ID
query = Query().sort("localId", "asc").paginate(1, 50)
first_batch = await sdk.card.list(query)

# Get second 50 cards
query = Query().sort("localId", "asc").paginate(2, 50)
second_batch = await sdk.card.list(query)
```

--------------------------------

### Language Enum for API Localization

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/types.md

Use the Language enum to specify multi-language API support. It is used during SDK initialization and for setting or getting the current language.

```python
class Language(Enum):
    EN = "en"        # English
    FR = "fr"        # French
    ES = "es"        # Spanish
    ES_MX = "es-mx"  # Spanish (Mexico)
    IT = "it"        # Italian
    PT_BR = "pt-br"  # Brazilian Portuguese
    PT_PT = "pt-pt"  # Portugal Portuguese
    DE = "de"        # German
    NL = "nl"        # Dutch
    PL = "pl"        # Polish
    RU = "ru"        # Russian
    JA = "ja"        # Japanese
    KO = "ko"        # Korean
    zh_TW = "zh-tw"  # Chinese (Taiwan)
    ID = "id"        # Indonesian
    TH = "th"        # Thai
    ZH_CN = "zh-cn"  # Chinese (China)
```

```python
from tcgdexsdk import Language, TCGdex

sdk = TCGdex(Language.EN)
sdk.setLanguage(Language.FR)
```

--------------------------------

### Fetch Full Set Details with TCGdex SDK

Source: https://github.com/tcgdex/python-sdk/blob/master/_autodocs/setresume-model.md

Retrieves the complete details for the first set in a series. This includes release date, legalities, and total card count. Requires initializing the TCGdex SDK and fetching a series.

```python
sdk = TCGdex()
serie = await sdk.serie.get("swsh")

if serie:
    # Get first set's full details
    full_set = await serie.sets[0].get_full_set()
    if full_set:
        print(f"Set: {full_set.name}")
        print(f"Release date: {full_set.releaseDate}")
        print(f"Standard legal: {full_set.legal.standard}")
        print(f"Cards: {full_set.cardCount.total}")
```