API Subpackage

This subpackage provides low-level client calls and high-level wrapper functions.

Client Module

yugiquery.api.client.URLS: SimpleNamespace

A mapping of yugipedia API URLs with HTTP headers dinamically loaded from the headers.json file in the assets directory.

yugiquery.api.client.check_status() → bool

Checks if the API is running and reachable by making a query to retrieve site information. If the API is up and running, returns True. If the API is down or unreachable, returns False and prints an error message with details.

Returns:: True if the API is up and running, False otherwise.
Return type:: bool

async yugiquery.api.client.download_media(*file_names: str, output_path: str | Path = 'media', max_tasks: int = 10) → List[Dict[str, str | bool]]

Download media files from yugipedia media storage.

Parameters:

file_names (str) – Media file names to download.
output_path (str | Path, optional) – Destination directory. Defaults to “media”.
max_tasks (int, optional) – Maximum concurrent downloads. Defaults to 10.

Returns:

Download status entries per file.

Return type:

List[Dict[str, str | bool]]

yugiquery.api.client.fetch_backlinks(*titles: str) → Dict[str, str]

Fetches backlinks for a list of page titles.

Parameters:

titles (str) – Multiple title strings.

Returns:

A dictionary mapping backlink titles to their corresponding target titles.

Return type:

Dict[str, str]

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.

yugiquery.api.client.fetch_categorymembers(category: str, namespace: int | None = None, step: int = 500, iterator: tqdm_asyncio | None = None) → DataFrame

Fetches members of a category from the API by making iterative requests with a specified step size until all members are retrieved.

Parameters:

category (str) – The category to retrieve members for.
namespace (int| None, optional) – The namespace ID to filter the members by. Defaults to None (no namespace).
step (int, optional) – The number of members to retrieve in each request. Defaults to 500.
iterator (tqdm.std.tqdm | None, optional) – A tqdm iterator to display progress updates. Defaults to None.

Returns:

A DataFrame containing the members of the category.

Return type:

pandas.DataFrame

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.
KeyboardInterrupt – If the operation is interrupted by the user.
SystemExit – If the operation is interrupted by the system.

yugiquery.api.client.fetch_page_images(*titles: str, featured: bool = False, batch_size: int = 50, imlimit: int = 500) → Dict[str, List[str] | str]

Fetch images from the MediaWiki API for the provided page titles.

Parameters:

titles (str) – Page titles to fetch images for.
featured (bool, optional) – If True, fetch only the featured image of each page. If False, fetch the page image list. Defaults to False.
batch_size (int, optional) – Number of titles per API request. Defaults to 50.
imlimit (int, optional) – Maximum number of images per page when featured=False. Defaults to 500.

Returns:

Mapping of page title to image names.

Return type:

Dict[str, List[str] | str]

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.

yugiquery.api.client.fetch_properties(condition: str, query: str, step: int = 500, limit: int = 5000, iterator: tqdm_asyncio | None = None, unwrap_tuples: bool = True, **format_kwargs) → DataFrame

Fetches properties from the API by making iterative requests with a specified step size until a specified limit is reached.

Parameters:

condition (str) – The query condition to filter the properties by.
query (str) – The query to retrieve the properties.
step (int, optional) – The number of properties to retrieve in each request. Defaults to 500.
limit (int, optional) – The maximum number of properties to retrieve. Defaults to 5000.
iterator (tqdm.std.tqdm | None, optional) – A tqdm iterator to display progress updates. Defaults to None.
unwrap_tuples (bool, optional) – Whether to unwrap single-value tuple columns in the resulting DataFrame. Defaults to True.
**format_kwargs – Keyword arguments to pass to the format_df function for formatting the retrieved properties. Defaults to None.

Returns:

A DataFrame containing the properties matching the query and condition.

Return type:

pandas.DataFrame

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.
KeyboardInterrupt – If the operation is interrupted by the user.
SystemExit – If the operation is interrupted by the system.

yugiquery.api.client.fetch_redirect_dict(codes: str | List[str] = [], names: str | List[str] = [], category: str = '', **kwargs) → Dict[str, str]

Fetches a dictionary mapping rarity codes to their corresponding names by searching for backlinks and redirects.

Parameters:

names (str | List[str], optional) – A list of names, i.e. “Super Rare” to search for a backling.
codes (str | List[str], optional) – A list of codes, i.e. “SR” to search for a redirect.
category (str, optional) – A category to search for backlinks. Defaults to empty.
**kwargs – Additional keyword arguments to pass to the fetch_categorymembers

Returns:

A dictionary mapping codes to their corresponding names.

Return type:

Dict[str, str]

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.

yugiquery.api.client.fetch_redirects(*titles: str) → Dict[str, str]

Fetches redirects for a list of page titles.

Parameters:

titles (str) – Multiple title strings.

Returns:

A dictionary mapping source titles to their corresponding redirect targets.

Return type:

Dict[str, str]

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.

yugiquery.api.client.fetch_set_info(*sets: str, extra_info: List[str] = [], step: int = 15) → DataFrame

Fetches information for a list of sets.

Parameters:

sets (str | List[str]) – Multiple set names to fetch information for.
extra_info (List[str], optional) – A list of additional information to fetch for each set. Defaults to an empty list.
step (int, optional) – The number of sets to fetch information for at once. Defaults to 15.

Returns:

A DataFrame containing information for all sets in the list.

Return type:

pd.DataFrame

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.
KeyboardInterrupt – If the operation is interrupted by the user.
SystemExit – If the operation is interrupted by the system.

yugiquery.api.client.fetch_set_lists(*titles: str) → None | Tuple[DataFrame, int, int]

Fetches card set lists from a list of page titles.

Parameters:

titles (str) – Multiple page titles from which to fetch set lists.

Returns:

A DataFrame containing the parsed card set lists, the number of successful requests, and the number of failed requests.

Return type:

Tuple[pd.DataFrame, int, int]

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.

yugiquery.api.client.fetch_ygoprodeck(misc=True) → List[Dict[str, Any]]

Fetch the card data from ygoprodeck.com.

Returns:

List of card data.

Return type:

(List[Dict[str, Any]])

Raises:

requests.exceptions.RequestException – If an error occurs while making the API request.
APIResponseError – If the API response contains an error or is invalid.

Parsers Module

exception yugiquery.api.parsers.APIResponseError

Bases: Exception

Raised when the API returns an error payload or an invalid response body.

yugiquery.api.parsers.extract_query_field(payload: dict[str, Any], field: str) → Any

Extracts a specific field from the ‘query’ section of the API response payload.

Parameters:

payload (dict) – The parsed JSON response from the API.
field (str) – The specific field to extract from the ‘query’ section.

Returns:

The value of the specified field within the ‘query’ section.

Raises:

APIResponseError – If the specified field is not found in the ‘query’ section of the payload.

yugiquery.api.parsers.format_df(input_df: DataFrame, include_all: bool = False, overrides: dict[str, bool] = {}) → DataFrame

Formats a dataframe containing card information. Returns a new dataframe with specific columns extracted and processed.

Parameters:

input_df (pd.DataFrame) – The input dataframe to format.
include_all (bool, optional) – If True, include all unspecified columns in the output dataframe. Default is False.
overrides (dict[str, bool], optional) – A dictionary specifying whether certain columns should be treated as having multiple values. Default is an empty dictionary.

Returns:

The formatted dataframe.

Return type:

pd.DataFrame

yugiquery.api.parsers.parse_response(response: Response) → dict[str, Any]

Parses the JSON response from the API and checks for errors or warnings.

Parameters:: response (requests.Response) – The response object obtained from making a GET request to the API.
Returns:: The parsed JSON response from the API.
Return type:: dict
Raises:: APIResponseError – If the response contains an error or if the expected data structure is not found in the response.

yugiquery.api.parsers.process_content(content: Dict, rarities: Dict[str, str], columns: List[str]) → Tuple[DataFrame | None, int, int]

Process a single page content for set lists.

Searches for ‘set list’ templates and builds DataFrames.

Parameters:

content – Page content dict with ‘revisions’ key.
rarities – Mapping of rarity codes to full names.
columns – Column names for output DataFrame.

Returns:

Tuple of (combined_df or None, success_count, error_count).

yugiquery.api.parsers.response_to_df(response: Response) → DataFrame

Extracts the relevant data from the response object and returns it as a Pandas DataFrame.

Parameters:: response (requests.Response) – The response object obtained from making a GET request to the Yu-Gi-Oh! Wiki API.
Returns:: A DataFrame containing the relevant data extracted from the response object.
Return type:: pd.DataFrame
Raises:: APIResponseError – If the response contains an error or if the expected data structure is not found in the response.

Wrappers Module

class yugiquery.api.wrappers.CG

Bases: Enum

Enum representing the card game formats.

CG

Both TCG and OCG.

Type:: str

ALL

Alias for CG, representing all card games.

Type:: CG

BOTH

Alias for CG, representing both card games.

Type:: CG

TCG

The ‘trading card game’ type.

Type:: str

OCG

The ‘official card game’ type.

Type:: str

yugiquery.api.wrappers.card_query(*args, **kwargs) → str

Build the query string used for yugipedia card searches.

Parameters:

default (bool, optional) – Include the default core card properties when True.
*args – Extra properties to include.
**kwargs – Property toggles where truthy adds and falsy removes.

Returns:

Query string for the API.

Return type:

str

yugiquery.api.wrappers.fetch_all_set_lists(cg: CG = CG.CG, step: int = 40, **kwargs) → DataFrame

Fetch all set lists from the API.

Parameters:

cg (CG, optional) – The card game to fetch set lists for. Default is CG.ALL.
step (int, optional) – The number of set lists to fetch in each request. Default is 40.
**kwargs – Additional keyword arguments to pass to fetch_set_list_pages and fetch_set_lists.

Returns:

DataFrame containing all set list data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_bandai(bandai_query: str | None = None, limit: int = 200, **kwargs) → DataFrame

Fetch Bandai cards from the API.

Parameters:

bandai_query (str | None, optional) – Custom query string for Bandai cards.
limit (int, optional) – Maximum number of cards to fetch.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Bandai card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_counter(*query: str, cg=CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Counter cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Counter cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Counter card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_errata(errata: str = 'all', step: int = 500, **kwargs) → DataFrame

Fetch cards with errata from the API.

Parameters:

errata (str, optional) – The type of errata to fetch. Default is “all”. Valid options are “name”, “type”, and “all”.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
**kwargs – Additional keyword arguments. Not implemented.

Returns:

DataFrame containing card errata information.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_monster(*query: str, cg: CG = CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Monster cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Monster cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Monster card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_rush(*query: str, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Rush Duel cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Rush Duel cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Rush Duel card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_set_list_pages(cg: CG = CG.CG, step: int = 500, limit=5000, **kwargs) → DataFrame

Fetch the list of ‘Set Card Lists’ pages from the API.

Parameters:

cg (CG, optional) – The card game to fetch set lists for. Default is CG.ALL.
step (int, optional) – The number of pages to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of pages to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing the list of ‘Set Card Lists’ pages.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_skill(*query: str, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Skill cards for Speed Duel from the API. For Rush Duel Skill cards, use fetch_rush.

Parameters:

*query (str) – Variable length argument list of query strings for Skill cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Skill card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_speed(*query: str, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Speed Duel cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Speed Duel cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Speed Duel card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_spell(*query: str, cg=CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Spell cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Spell cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Spell card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_st(st_query: str | None = None, st: str = 'both', cg: CG = CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Spell and Trap cards from the API.

Parameters:

st_query (str | None, optional) – Custom query string for Spell and Trap cards.
st (str, optional) – The type of card to fetch. Default is “both”.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Spell and Trap card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_tc(tc_query: str | None = None, tc: str = 'both', cg: CG = CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Token and Counter cards from the API.

Parameters:

tc_query (str | None, optional) – Custom query string for Token and Counter cards.
tc (str, optional) – The type of card to fetch. Default is “both”.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Token and Counter card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_token(*query: str, cg=CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Token cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Token cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Token card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_trap(*query: str, cg=CG.CG, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Trap cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Trap cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Trap card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.fetch_unusable(*query: str, cg: CG = CG.CG, filter=True, step: int = 500, limit: int = 5000, **kwargs) → DataFrame

Fetch Unusable cards from the API.

Parameters:

*query (str) – Variable length argument list of query strings for Unusable cards.
cg (CG, optional) – The card game to fetch cards from. Default is CG.ALL.
filter (bool, optional) – Whether to filter for only Character, Non-game, and Ticket cards. Default is True.
step (int, optional) – The number of cards to fetch in each request. Default is 500.
limit (int, optional) – The maximum number of cards to fetch. Default is 5000.
**kwargs – Additional keyword arguments to pass to fetch_properties.

Returns:

DataFrame containing Unusable card data.

Return type:

pd.DataFrame

yugiquery.api.wrappers.get_ygoprodeck() → DataFrame

Fetch YGOProDeck data from the API and persist a local cache.

Returns:: YGOProDeck card data indexed by card id.
Return type:: pd.DataFrame
Raises:: Exception – Exceptions raised by client.fetch_ygoprodeck when no cache exists.

yugiquery.api.wrappers.update_rarities(save: bool = True) → Dict[str, str]

Update rarities dictionary with redirects/backlinks fetched from the API.

Parameters:: save (bool, optional) – Whether to persist updates to rarities.json.
Returns:: Updated rarities dictionary.
Return type:: Dict[str, str]

yugiquery.api.wrappers.update_regions(save: bool = True) → Dict[str, str]

Update regions dictionary with redirects/backlinks fetched from the API.

Parameters:: save (bool, optional) – Whether to persist updates to regions.json.
Returns:: Updated regions dictionary.
Return type:: Dict[str, str]