API Reference

EDHREC

EDHREC is a reference database for EDH and cEDH. It provides a small REST-like, and a lot of static json files that were reverse engineered in order to provide a pydantic model.

Static API

There are two distinct API:

EdhRecStatic direct static access from https://json.edhrec.com/page, faster but incomplete support
EdhRecProxiedStatic proxified static access from https://edhrec.com/_next/data, slower but similar to frontend users

Feature	Support
Top Cards (by color, by salt, by type)	✅
Combos	✅
Card in set	✅
Themes	✅
Typals (tribes)	✅
Card Migrations	✅
Decks (average, listing)	✅
Invidivual decks	🔸(only in proxified mode)

class mightstone.services.edhrec.EdhRecStatic(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None)

HTTP client for static JSON data hosted at https://json.edhrec.com

This client is faster than EdhRecProxiedStatic but will not support all features since Mightstone failed to reverse engineer some stored information on json.edhrec.com

average_deck(commander, theme: str | None = None, cost: EnumCost | None = None) → PageAverageDeck: Universal (async or sync) version of average_deck_async(), same behavior but wrapped by universalasync().

async average_deck_async(commander, theme: str | None = None, cost: EnumCost | None = None) → PageAverageDeck

Obtain a representation of an average deck for a given commander. Optionally, filter result by a price range (cheap or expansive)

Parameters:

commander – The commander name
theme – Optional, the theme or tribe (ex: elves, sacrifice)
cost – Optional, the price range of the deck

Returns:

Page representation

background(name: str) → PageBackground: Universal (async or sync) version of background_async(), same behavior but wrapped by universalasync().

async background_async(name: str) → PageBackground

Obtain a representation of a background card

Parameters:: name – The card name
Returns:: Page representation

backgrounds() → PageBackgrounds: Universal (async or sync) version of backgrounds_async(), same behavior but wrapped by universalasync().

async backgrounds_async() → PageBackgrounds

Obtain a representation of all background cards.

Returns:: Page representation

backgrounds_stream(collection: str | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]: Universal (async or sync) version of backgrounds_stream_async(), same behavior but wrapped by universalasync().

async backgrounds_stream_async(collection: str | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]

Streams backgrounds pages as an async generator

Parameters:

collection – Optional. Use the named collection. Either: Commanders or Backgrounds
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

base_url: str = 'https://json.edhrec.com/pages': Base url of the service (must be a root path such as https://example.com)

card(name: str): Universal (async or sync) version of card_async(), same behavior but wrapped by universalasync().

async card_async(name: str)

Obtain a complete representation of a card as a deck member

Use commander_async, partner_async, background_async for commander, partner and background context. Companions are described as a theme, and provided with companion_async

Parameters:: name – The card name
Returns:: Page representation

combo(combo_id: str, identity: EnumIdentity) → PageCombo: Universal (async or sync) version of combo_async(), same behavior but wrapped by universalasync().

async combo_async(combo_id: str, identity: EnumIdentity) → PageCombo

Obtain a representation of a combo (recursive behavior that can win a game). Is requires both color identity and unique identifier due to API limitation

Parameters:

combo_id – The combo unique id (ex: 1478-3293)
identity – The color identity of the combo

Returns:

Page representation

combos(identity: EnumIdentity | None = None) → PageCombos: Universal (async or sync) version of combos_async(), same behavior but wrapped by universalasync().

async combos_async(identity: EnumIdentity | None = None) → PageCombos

Obtain a representation of a list of combos for a given color

Parameters:: identity – The color identity of the combos
Returns:: Page representation

combos_stream(identity: EnumIdentity | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCombo, None]: Universal (async or sync) version of combos_stream_async(), same behavior but wrapped by universalasync().

async combos_stream_async(identity: EnumIdentity | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCombo, None]

Streams commanders pages as an async generator

Parameters:

identity – The color identity of the commanders
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

commander(name: str, background: str | None = None, partner: str | None = None, subtype: str | None = None, cost: EnumCost | None = None) → PageCommander: Universal (async or sync) version of commander_async(), same behavior but wrapped by universalasync().

async commander_async(name: str, background: str | None = None, partner: str | None = None, subtype: str | None = None, cost: EnumCost | None = None) → PageCommander

Obtain a complete representation of a card as a deck commander

Use card_async, partner_async, background_async for deck card, partner and background context. Companions are described as a theme, and provided with companion_async

Parameters:

name – The card name
background – Optional, specify a background as partner (ex: Raised by Giants)
partner – Optional, specify a partner (ex: Rograkh, Son of Rohgahh)
subtype – Optional, filter by theme or typal (ex: elves, sacrifice)
cost – Optional, the price range of the deck

Returns:

Page representation

commanders(identity: EnumIdentity | None = None, period: EnumPeriod | None = None) → PageCommanders: Universal (async or sync) version of commanders_async(), same behavior but wrapped by universalasync().

async commanders_async(identity: EnumIdentity | None = None, period: EnumPeriod | None = None) → PageCommanders

Obtain a list of commanders for a period or a color identity.

Parameters:

period – The period observed (last week, last month, last 2 years)
identity – The color identity of the commanders

Returns:

Page representation

commanders_stream(identity: EnumIdentity | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCommander, None]: Universal (async or sync) version of commanders_stream_async(), same behavior but wrapped by universalasync().

async commanders_stream_async(identity: EnumIdentity | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCommander, None]

Streams commanders pages as an async generator

Parameters:

period – The period observed (last week, last month, last 2 years)
identity – The color identity of the commanders
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

companion(name: str) → PageTheme: Universal (async or sync) version of companion_async(), same behavior but wrapped by universalasync().

async companion_async(name: str) → PageTheme

Obtain a complete representation of a card as a deck companion EDHREC describes a companion as a theme.

Use card_async, commander_async, background_async, partner_async for deck card, commander, background and partner context.

Parameters:: name – The card name
Returns:: Page representation

companions() → PageCompanions: Universal (async or sync) version of companions_async(), same behavior but wrapped by universalasync().

async companions_async() → PageCompanions

Obtain a list of companions

Returns:: Page representation

companions_stream(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]: Universal (async or sync) version of companions_stream_async(), same behavior but wrapped by universalasync().

async companions_stream_async(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]

Streams companion pages as an async generator

Parameters:

matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

decks(commander, theme: str | None = None, cost: EnumCost | None = None) → PageDecks: Universal (async or sync) version of decks_async(), same behavior but wrapped by universalasync().

async decks_async(commander, theme: str | None = None, cost: EnumCost | None = None) → PageDecks

Obtain a list of decks references for a given commander Optionally, filter result by a price range (cheap or expansive)

Parameters:

commander – The commander name
theme – Optional, the theme or tribe (ex: elves, sacrifice)
cost – Optional, the price range of the deck

Returns:

Page representation

mana_staples(identity: EnumIdentity): Universal (async or sync) version of mana_staples_async(), same behavior but wrapped by universalasync().

async mana_staples_async(identity: EnumIdentity)

Obtain a list of staple mana card references for a color identity

Parameters:: identity – The color identity
Returns:: Page representation

mana_staples_stream(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of mana_staples_stream_async(), same behavior but wrapped by universalasync().

async mana_staples_stream_async(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams staples pages as an async generator

Parameters:

identity – The color identity
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching staple pages

page(path: str, cls: Type[P]) → P: Universal (async or sync) version of page_async(), same behavior but wrapped by universalasync().

async page_async(path: str, cls: Type[P]) → P

Parameters:

cls – The class to use (must extend EdhRecPage)
path – The page path

Returns:

A page instance with un-paginated items

partner() → PagePartners: Universal (async or sync) version of partners_async(), same behavior but wrapped by universalasync().

async partner_async(name: str) → PagePartner

Obtain a complete representation of a card as a deck partner

Use card_async, commander_async, background_async for deck card, commander and background context. Companions are described as a theme, and provided with companion_async

Parameters:: name – The card name
Returns:: Page representation

partners() → PagePartners: Universal (async or sync) version of partners_async(), same behavior but wrapped by universalasync().

async partners_async() → PagePartners

Obtain a list of partners

Returns:: Page representation

async partners_stream_async(collection: str | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PagePartner, None]

Streams partners pages as an async generator

Parameters:

collection – Optional. Use the named collection. Either: Doctors`, ``Friends Forever or Partners
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

salt(year: int | None = None) → PageSalts: Universal (async or sync) version of salt_async(), same behavior but wrapped by universalasync().

async salt_async(year: int | None = None) → PageSalts

Obtain a representation of top salt cards by year

Parameters:: year – Optional, the year of the salt
Returns:: Page representation

salt_stream(year: int | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of salt_stream_async(), same behavior but wrapped by universalasync().

async salt_stream_async(year: int | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams salt pages as an async generator

Parameters:

year – Optional. The year to observe
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

set(code) → PageSet: Universal (async or sync) version of set_async(), same behavior but wrapped by universalasync().

async set_async(code) → PageSet

Obtain a representation of cards in a given set

Parameters:: code – The set code (ex: RNA for Ravnica Allegiance)
Returns:: Page representation

staples(identity: EnumIdentity) → PageStaples: Universal (async or sync) version of staples_async(), same behavior but wrapped by universalasync().

async staples_async(identity: EnumIdentity) → PageStaples

Obtain a list of staple card references for a color identity

Parameters:: identity – The color identity
Returns:: Page representation

staples_stream(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of staples_stream_async(), same behavior but wrapped by universalasync().

async staples_stream_async(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams staples pages as an async generator

Parameters:

identity – The color identity
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching staple pages

async stream_page_items(page: Page, collection: str | None = None, cls=typing.Type[~P], matcher=typing.Type[typing.Optional[typing.Callable[[~P], bool]]], start=0, stop=None, step=1, parallel=5) → AsyncGenerator[P, None]

An async generator that return each item from a page as a page (for instance each PageCommander from a PageCommanders)

start, stop, step parameters works as a standard python slice. matcher function is applied after slicing through start, stop, step parameters

Parameters:

page – The page to scan
collection – Use the named collection located in page.container.iterable.collections instead of page.items
cls – The collection item type (must inherit from Page)
matcher – Optional. A matcher function that validates collection item, useful for filtering
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

An async generator of item_class

theme(name, identity: EnumIdentity | None = None) → PageTheme: Universal (async or sync) version of theme_async(), same behavior but wrapped by universalasync().

async theme_async(name, identity: EnumIdentity | None = None) → PageTheme

Obtain a representation of a deck theme (sacrifice, lifegain…)

Parameters:

name – The name of the theme
identity – Optional, include only cards for a given color identity

Returns:

Page representation

themes() → PageThemes: Universal (async or sync) version of themes_async(), same behavior but wrapped by universalasync().

async themes_async() → PageThemes

Obtain a representation of all deck themes

Returns:: Page representation

themes_stream(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]: Universal (async or sync) version of themes_stream_async(), same behavior but wrapped by universalasync().

async themes_stream_async(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]

Streams theme pages as an async generator

Parameters:

matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

top_cards(color: EnumColor | None = None, period: EnumPeriod | None = None, type: EnumType | None = None) → PageTopCards: Universal (async or sync) version of top_cards_async(), same behavior but wrapped by universalasync().

async top_cards_async(color: EnumColor | None = None, period: EnumPeriod | None = None, type: EnumType | None = None) → PageTopCards

Obtain a representation of a list of card matching one of the following selector:

color
period
type

Parameters:

color – The color of the card (ex: w, u, multi…)
period – The period of observation (week, month, years)
type – The type of card (ex: sorcery, instant…)

Returns:

Page representation

top_cards_stream(color: EnumColor | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, type: EnumType | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of top_cards_stream_async(), same behavior but wrapped by universalasync().

async top_cards_stream_async(color: EnumColor | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, type: EnumType | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams salt pages as an async generator

Parameters:

color – The color of the card (ex: w, u, multi…)
period – The period of observation (week, month, years)
type – The type of card (ex: sorcery, instant…)
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

typal(name, identity: EnumIdentity | None = None): Universal (async or sync) version of typal_async(), same behavior but wrapped by universalasync().

async typal_async(name, identity: EnumIdentity | None = None)

Obtain a representation of a typal (previously known as tribe) for example: elves, zombies

Parameters:

name – The name of the typal
identity – Optional, include only cards for a given color identity

Returns:

Page representation

typals() → Page: Universal (async or sync) version of typals_async(), same behavior but wrapped by universalasync().

async typals_async() → Page

Obtain a representation of all deck typals (previously known as tribes)

Returns:: Page representation

typals_stream(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]: Universal (async or sync) version of typals_stream_async(), same behavior but wrapped by universalasync().

async typals_stream_async(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]

Streams typal pages as an async generator

Parameters:

matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching typal pages

class mightstone.services.edhrec.EdhRecProxiedStatic(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None)

HTTP client for static JSON data hosted at https://edhrec.com/_next/data

Please prefer the EdhRecStatic instead if you need better performances and don’t need to scrap individual decks

average_deck(commander, theme: str | None = None, cost: EnumCost | None = None) → PageAverageDeck: Universal (async or sync) version of average_deck_async(), same behavior but wrapped by universalasync().

async average_deck_async(commander, theme: str | None = None, cost: EnumCost | None = None) → PageAverageDeck

Obtain a representation of an average deck for a given commander. Optionally, filter result by a price range (cheap or expansive)

Parameters:

commander – The commander name
theme – Optional, the theme or tribe (ex: elves, sacrifice)
cost – Optional, the price range of the deck

Returns:

Page representation

background(name: str) → PageBackground: Universal (async or sync) version of background_async(), same behavior but wrapped by universalasync().

async background_async(name: str) → PageBackground

Obtain a representation of a background card

Parameters:: name – The card name
Returns:: Page representation

backgrounds() → PageBackgrounds: Universal (async or sync) version of backgrounds_async(), same behavior but wrapped by universalasync().

async backgrounds_async() → PageBackgrounds

Obtain a representation of all background cards.

Returns:: Page representation

backgrounds_stream(collection: str | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]: Universal (async or sync) version of backgrounds_stream_async(), same behavior but wrapped by universalasync().

async backgrounds_stream_async(collection: str | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]

Streams backgrounds pages as an async generator

Parameters:

collection – Optional. Use the named collection. Either: Commanders or Backgrounds
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

property base_url

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

card(name: str): Universal (async or sync) version of card_async(), same behavior but wrapped by universalasync().

async card_async(name: str)

Obtain a complete representation of a card as a deck member

Use commander_async, partner_async, background_async for commander, partner and background context. Companions are described as a theme, and provided with companion_async

Parameters:: name – The card name
Returns:: Page representation

combo(combo_id: str, identity: EnumIdentity) → PageCombo: Universal (async or sync) version of combo_async(), same behavior but wrapped by universalasync().

async combo_async(combo_id: str, identity: EnumIdentity) → PageCombo

Obtain a representation of a combo (recursive behavior that can win a game). Is requires both color identity and unique identifier due to API limitation

Parameters:

combo_id – The combo unique id (ex: 1478-3293)
identity – The color identity of the combo

Returns:

Page representation

combos(identity: EnumIdentity | None = None) → PageCombos: Universal (async or sync) version of combos_async(), same behavior but wrapped by universalasync().

async combos_async(identity: EnumIdentity | None = None) → PageCombos

Obtain a representation of a list of combos for a given color

Parameters:: identity – The color identity of the combos
Returns:: Page representation

combos_stream(identity: EnumIdentity | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCombo, None]: Universal (async or sync) version of combos_stream_async(), same behavior but wrapped by universalasync().

async combos_stream_async(identity: EnumIdentity | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCombo, None]

Streams commanders pages as an async generator

Parameters:

identity – The color identity of the commanders
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

commander(name: str, background: str | None = None, partner: str | None = None, subtype: str | None = None, cost: EnumCost | None = None) → PageCommander: Universal (async or sync) version of commander_async(), same behavior but wrapped by universalasync().

async commander_async(name: str, background: str | None = None, partner: str | None = None, subtype: str | None = None, cost: EnumCost | None = None) → PageCommander

Obtain a complete representation of a card as a deck commander

Use card_async, partner_async, background_async for deck card, partner and background context. Companions are described as a theme, and provided with companion_async

Parameters:

name – The card name
background – Optional, specify a background as partner (ex: Raised by Giants)
partner – Optional, specify a partner (ex: Rograkh, Son of Rohgahh)
subtype – Optional, filter by theme or typal (ex: elves, sacrifice)
cost – Optional, the price range of the deck

Returns:

Page representation

commanders(identity: EnumIdentity | None = None, period: EnumPeriod | None = None) → PageCommanders: Universal (async or sync) version of commanders_async(), same behavior but wrapped by universalasync().

async commanders_async(identity: EnumIdentity | None = None, period: EnumPeriod | None = None) → PageCommanders

Obtain a list of commanders for a period or a color identity.

Parameters:

period – The period observed (last week, last month, last 2 years)
identity – The color identity of the commanders

Returns:

Page representation

commanders_stream(identity: EnumIdentity | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCommander, None]: Universal (async or sync) version of commanders_stream_async(), same behavior but wrapped by universalasync().

async commanders_stream_async(identity: EnumIdentity | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCommander, None]

Streams commanders pages as an async generator

Parameters:

period – The period observed (last week, last month, last 2 years)
identity – The color identity of the commanders
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

companion(name: str) → PageTheme: Universal (async or sync) version of companion_async(), same behavior but wrapped by universalasync().

async companion_async(name: str) → PageTheme

Obtain a complete representation of a card as a deck companion EDHREC describes a companion as a theme.

Use card_async, commander_async, background_async, partner_async for deck card, commander, background and partner context.

Parameters:: name – The card name
Returns:: Page representation

companions() → PageCompanions: Universal (async or sync) version of companions_async(), same behavior but wrapped by universalasync().

async companions_async() → PageCompanions

Obtain a list of companions

Returns:: Page representation

companions_stream(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]: Universal (async or sync) version of companions_stream_async(), same behavior but wrapped by universalasync().

async companions_stream_async(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]

Streams companion pages as an async generator

Parameters:

matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

deck(deck_id: str) → PageDeck: Universal (async or sync) version of deck_async(), same behavior but wrapped by universalasync().

decks(commander, theme: str | None = None, cost: EnumCost | None = None) → PageDecks: Universal (async or sync) version of decks_async(), same behavior but wrapped by universalasync().

async decks_async(commander, theme: str | None = None, cost: EnumCost | None = None) → PageDecks

Obtain a list of decks references for a given commander Optionally, filter result by a price range (cheap or expansive)

Parameters:

commander – The commander name
theme – Optional, the theme or tribe (ex: elves, sacrifice)
cost – Optional, the price range of the deck

Returns:

Page representation

decks_stream(commander, theme: str | None = None, cost: EnumCost | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]: Universal (async or sync) version of decks_stream_async(), same behavior but wrapped by universalasync().

async decks_stream_async(commander, theme: str | None = None, cost: EnumCost | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]

Streams backgrounds pages as an async generator

Parameters:

commander – The commander name
theme – Optional, the theme or tribe (ex: elves, sacrifice)
cost – Optional, the price range of the deck
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching commander pages

delay = 0: Induced delay in second between each API call

mana_staples(identity: EnumIdentity): Universal (async or sync) version of mana_staples_async(), same behavior but wrapped by universalasync().

async mana_staples_async(identity: EnumIdentity)

Obtain a list of staple mana card references for a color identity

Parameters:: identity – The color identity
Returns:: Page representation

mana_staples_stream(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of mana_staples_stream_async(), same behavior but wrapped by universalasync().

async mana_staples_stream_async(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams staples pages as an async generator

Parameters:

identity – The color identity
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching staple pages

page(path: str, cls: Type[P]) → P: Universal (async or sync) version of page_async(), same behavior but wrapped by universalasync().

async page_async(path: str, cls: Type[P]) → P

Parameters:

cls – The class to use (must extend EdhRecPage)
path – The page path

Returns:

A page instance with un-paginated items

partner() → PagePartners: Universal (async or sync) version of partners_async(), same behavior but wrapped by universalasync().

async partner_async(name: str) → PagePartner

Obtain a complete representation of a card as a deck partner

Use card_async, commander_async, background_async for deck card, commander and background context. Companions are described as a theme, and provided with companion_async

Parameters:: name – The card name
Returns:: Page representation

partners() → PagePartners: Universal (async or sync) version of partners_async(), same behavior but wrapped by universalasync().

async partners_async() → PagePartners

Obtain a list of partners

Returns:: Page representation

async partners_stream_async(collection: str | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PagePartner, None]

Streams partners pages as an async generator

Parameters:

collection – Optional. Use the named collection. Either: Doctors`, ``Friends Forever or Partners
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

salt(year: int | None = None) → PageSalts: Universal (async or sync) version of salt_async(), same behavior but wrapped by universalasync().

async salt_async(year: int | None = None) → PageSalts

Obtain a representation of top salt cards by year

Parameters:: year – Optional, the year of the salt
Returns:: Page representation

salt_stream(year: int | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of salt_stream_async(), same behavior but wrapped by universalasync().

async salt_stream_async(year: int | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams salt pages as an async generator

Parameters:

year – Optional. The year to observe
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

set(code) → PageSet: Universal (async or sync) version of set_async(), same behavior but wrapped by universalasync().

async set_async(code) → PageSet

Obtain a representation of cards in a given set

Parameters:: code – The set code (ex: RNA for Ravnica Allegiance)
Returns:: Page representation

staples(identity: EnumIdentity) → PageStaples: Universal (async or sync) version of staples_async(), same behavior but wrapped by universalasync().

async staples_async(identity: EnumIdentity) → PageStaples

Obtain a list of staple card references for a color identity

Parameters:: identity – The color identity
Returns:: Page representation

staples_stream(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of staples_stream_async(), same behavior but wrapped by universalasync().

async staples_stream_async(identity: EnumIdentity, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams staples pages as an async generator

Parameters:

identity – The color identity
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching staple pages

async stream_page_items(page: Page, collection: str | None = None, cls=typing.Type[~P], matcher=typing.Type[typing.Optional[typing.Callable[[~P], bool]]], start=0, stop=None, step=1, parallel=5) → AsyncGenerator[P, None]

An async generator that return each item from a page as a page (for instance each PageCommander from a PageCommanders)

start, stop, step parameters works as a standard python slice. matcher function is applied after slicing through start, stop, step parameters

Parameters:

page – The page to scan
collection – Use the named collection located in page.container.iterable.collections instead of page.items
cls – The collection item type (must inherit from Page)
matcher – Optional. A matcher function that validates collection item, useful for filtering
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

An async generator of item_class

theme(name, identity: EnumIdentity | None = None) → PageTheme: Universal (async or sync) version of theme_async(), same behavior but wrapped by universalasync().

async theme_async(name, identity: EnumIdentity | None = None) → PageTheme

Obtain a representation of a deck theme (sacrifice, lifegain…)

Parameters:

name – The name of the theme
identity – Optional, include only cards for a given color identity

Returns:

Page representation

themes() → PageThemes: Universal (async or sync) version of themes_async(), same behavior but wrapped by universalasync().

async themes_async() → PageThemes

Obtain a representation of all deck themes

Returns:: Page representation

themes_stream(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]: Universal (async or sync) version of themes_stream_async(), same behavior but wrapped by universalasync().

async themes_stream_async(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTheme, None]

Streams theme pages as an async generator

Parameters:

matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

top_cards(color: EnumColor | None = None, period: EnumPeriod | None = None, type: EnumType | None = None) → PageTopCards: Universal (async or sync) version of top_cards_async(), same behavior but wrapped by universalasync().

async top_cards_async(color: EnumColor | None = None, period: EnumPeriod | None = None, type: EnumType | None = None) → PageTopCards

Obtain a representation of a list of card matching one of the following selector:

color
period
type

Parameters:

color – The color of the card (ex: w, u, multi…)
period – The period of observation (week, month, years)
type – The type of card (ex: sorcery, instant…)

Returns:

Page representation

top_cards_stream(color: EnumColor | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, type: EnumType | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]: Universal (async or sync) version of top_cards_stream_async(), same behavior but wrapped by universalasync().

async top_cards_stream_async(color: EnumColor | None = None, period: EnumPeriod | None = EnumPeriod.PAST_WEEK, type: EnumType | None = None, matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageCard, None]

Streams salt pages as an async generator

Parameters:

color – The color of the card (ex: w, u, multi…)
period – The period of observation (week, month, years)
type – The type of card (ex: sorcery, instant…)
matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching theme pages

typal(name, identity: EnumIdentity | None = None): Universal (async or sync) version of typal_async(), same behavior but wrapped by universalasync().

async typal_async(name, identity: EnumIdentity | None = None)

Obtain a representation of a typal (previously known as tribe) for example: elves, zombies

Parameters:

name – The name of the typal
identity – Optional, include only cards for a given color identity

Returns:

Page representation

typals() → Page: Universal (async or sync) version of typals_async(), same behavior but wrapped by universalasync().

async typals_async() → Page

Obtain a representation of all deck typals (previously known as tribes)

Returns:: Page representation

typals_stream(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]: Universal (async or sync) version of typals_stream_async(), same behavior but wrapped by universalasync().

async typals_stream_async(matcher: Callable[[P], bool] | None = None, start=0, stop=None, step=1, parallel=5) → AsyncGenerator[PageTypal, None]

Streams typal pages as an async generator

Parameters:

matcher – Optional. A matcher function that validates collection item, useful for filtering. Applied after slicing.
start – Optional. An integer number specifying at which position to start the slicing. Default is 0
stop – Optional. An integer number specifying at which position to end the slicing
step – Optional. An integer number specifying the step of the slicing. Default is 1
parallel – Allow X parallel HTTP calls at once

Returns:

All matching typal pages

Dynamic API

class mightstone.services.edhrec.EdhRecApi(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None)

HTTP client for dynamic data hosted at https://edhrec.com/api/

base_url: str = 'https://edhrec.com': Base url of the service (must be a root path such as https://example.com)

filter(commander: str, query: FilterQuery) → PageCommander: Universal (async or sync) version of filter_async(), same behavior but wrapped by universalasync().

async filter_async(commander: str, query: FilterQuery) → PageCommander

Read Commander related information, and return an EdhRecCommander object

Parameters:

commander – Commander name or slug
query – An EdhRecFilterQuery object describing the request

Returns:

An EdhRecCommander representing answer

recommendations(commanders: List[str], cards: List[str]) → Recommendations: Universal (async or sync) version of recommendations_async(), same behavior but wrapped by universalasync().

async recommendations_async(commanders: List[str], cards: List[str]) → Recommendations

Obtain EDHREC recommendations for a given commander (or partners duo) for a given set of cards in the deck.

Returns a list of 99 suggested cards not contained in the list :param commanders: A list of one or two commander card name :param cards: A list of card name :exception ClientResponseError :returns An EdhRecRecs object

Scryfall

Scryfall is a search engine for magic cards. It provides a REST-like API for ingesting our card data programatically. The API exposes information available on the regular site in easy-to-consume formats.

Feature	Support
Cards	✅
Sets	✅
Rulings	✅
Card Symbols	✅
Bulk Data	✅ (fully async)
Card Migrations	✅
Application	❌

Scryfall Client

class mightstone.services.scryfall.Scryfall(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None)

Scryfall API client

autocomplete(q: str, include_extras=False) → Catalog: Universal (async or sync) version of autocomplete_async(), same behavior but wrapped by universalasync().

async autocomplete_async(q: str, include_extras=False) → Catalog

Returns a Catalog object containing up to 20 full English card names that could be autocompletions of the given string parameter.

This method is designed for creating assistive UI elements that allow users to free-type card names. The names are sorted with the nearest match first, highly favoring results that begin with your given string.

Spaces, punctuation, and capitalization are ignored.

If q is less than 2 characters long, or if no names match, the Catalog will contain 0 items (instead of returning any errors).

Parameters:

q – The string to autocomplete.
include_extras – If true, extra cards (tokens, planes, vanguards, etc) will be included.

Returns:

A scryfall Card instance async generator

base_url: str = 'https://api.scryfall.com': Base url of the service (must be a root path such as https://example.com)

card(id: str, type: CardIdentifierPath = CardIdentifierPath.SCRYFALL) → Card: Universal (async or sync) version of card_async(), same behavior but wrapped by universalasync().

async card_async(id: str, type: CardIdentifierPath = CardIdentifierPath.SCRYFALL) → Card

Returns a single card with a given ID, or by its code set / collector number

Depending on the type value, one of the following endpoint will be reached:

/cards/:id
/cards/tcgplayer/:id
/cards/multiverse/:id
/cards/mtgo/:id
/cards/arena/:id
/cards/cardmarket/:id
/cards/:code/:number

Parameters:

id – The requested Card identifier string, for code-number, please use / as separator (dmu/123)
type – The card identifier, please refer to CardIdentifierPath enum
type – Type of id researched

Returns:

A scryfall Card instance

catalog(type: CatalogType) → Catalog: Universal (async or sync) version of catalog_async(), same behavior but wrapped by universalasync().

async catalog_async(type: CatalogType) → Catalog

A Catalog object contains an array of Magic datapoints (words, card values, etc). Catalog objects are provided by the API as aids for building other Magic software and understanding possible values for a field on Card objects.

Parameters:: type – See CatalogType for more informations
Returns:: A Catalog instance

collection(identifiers: List[IdentifierId | IdentifierName | IdentifierNameSet | IdentifierMtgId | IdentifierOracleId | IdentifierMultiverseId | IdentifierCollectorNumberSet | IdentifierIllustrationId]) → AsyncGenerator[Card, None]: Universal (async or sync) version of collection_async(), same behavior but wrapped by universalasync().

Accepts a JSON array of card identifiers, and returns a List object with the collection of requested cards. A maximum of 75 card references may be submitted per request.

Parameters:: identifiers – Each submitted card identifier must be a JSON object with one or more of the keys id, mtgo_id, multiverse_id, oracle_id, illustration_id, name, set, and collector_number
Returns:: A scryfall Card instance async generator

get_bulk_data(bulk_type: str) → AsyncGenerator[Card, None]: Universal (async or sync) version of get_bulk_data_async(), same behavior but wrapped by universalasync().

async get_bulk_data_async(bulk_type: str) → AsyncGenerator[Card, None]

Access the bulk cards This script uses ijson and should stream data on the fly

See https://scryfall.com/docs/api/bulk-data for more informations

Parameters:: bulk_type – A string describing the bulk export name
Returns:: An async iterator of Card

get_bulk_tags(tag_type: BulkTagType) → AsyncGenerator[Tag, None]: Universal (async or sync) version of get_bulk_tags_async(), same behavior but wrapped by universalasync().

async get_bulk_tags_async(tag_type: BulkTagType) → AsyncGenerator[Tag, None]

Access the private tag repository

This is an alpha feature, and could be removed later.

Parameters:: tag_type – The tag type either oracle or illustration
Returns:: A scryfall Tag instance async generator

migration(id: str) → Migration: Universal (async or sync) version of migration_async(), same behavior but wrapped by universalasync().

async migration_async(id: str) → Migration

Returns a single Card Migration with the given :id

Returns:: A Migration instance

migrations(limit: int | None = None) → AsyncGenerator[Migration, None]: Universal (async or sync) version of migrations_async(), same behavior but wrapped by universalasync().

async migrations_async(limit: int | None = None) → AsyncGenerator[Migration, None]

For the vast majority of Scryfall’s database, Magic card entries are additive. We add new and upcoming cards as we learn about them and obtain images.

In rare instances, Scryfall may discover that a card in our database does not really exist, or it has been deleted from a digital game permanently. In these situations, we provide endpoints to help you reconcile downstream data you may have synced or imported from Scryfall.

Each migration has a provided migration_strategy:

merge You should update your records to replace the given old Scryfall ID with the new ID. The old ID is being discarded, and an existing record should be used to replace all instances of it.

delete The given UUID is being discarded, and no replacement data is being provided. This likely means the old records are fully invalid. This migration exists to provide evidence that cards were removed from Scryfall’s database.

Parameters:: limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
Returns:: A Migration instance async generator

named(q: str, set: str | None = None, exact=True) → Card: Universal (async or sync) version of named_async(), same behavior but wrapped by universalasync().

async named_async(q: str, set: str | None = None, exact=True) → Card

Returns a Card based on a name search string. This method is designed for building chatbots, forum bots, and other services that need card details quickly.

If exact mode is on, a card with that exact name is returned. Otherwise, an Exception is raised because no card matches. If exact mode is off and a card name matches that string, then that card is returned. If not, a fuzzy search is executed for your card name. The server allows misspellings and partial words to be provided. For example: jac bele will match Jace Beleren. When fuzzy searching, a card is returned if the server is confident that you unambiguously identified a unique name with your string. Otherwise, an exception will be raised describing the problem: either more than 1 one card matched your search, or zero cards matched.

Card names are case-insensitive and punctuation is optional (you can drop apostrophes and periods etc). For example: fIReBALL is the same as Fireball and smugglers copter is the same as Smuggler’s Copter.

Parameters:

q – The searched card name
exact – Run a strict text research instead of a fuzzy search
set – You may also provide a set code in the set parameter, in which case the name search and the returned card print will be limited to the specified set.

Returns:

A scryfall Card instance

parse_mana(cost: str) → ManaCost: Universal (async or sync) version of parse_mana_async(), same behavior but wrapped by universalasync().

async parse_mana_async(cost: str) → ManaCost

Parses the given mana cost parameter and returns Scryfall’s interpretation.

The server understands most community shorthand for mana costs (such as 2WW for {2}{W}{W}). Symbols can also be out of order, lowercase, or have multiple colorless costs (such as 2{g}2 for {4}{G}).

If part of the string could not be understood, the server will raise an Error object describing the problem.

Parameters:: cost – A mana cost string
Returns:: A ManaCost instance

random(q: str | None = None) → Card: Universal (async or sync) version of random_async(), same behavior but wrapped by universalasync().

async random_async(q: str | None = None) → Card

Returns a single random Card object.

This method will use: - /cards/random

Parameters:: q – The optional parameter q supports the same fulltext search system that the main site uses. Providing q will filter the pool of cards before returning a random entry.
Returns:: A scryfall Card instance

rulings(id: str, type: RulingIdentifierPath = RulingIdentifierPath.SCRYFALL, limit: int | None = None) → AsyncGenerator[Ruling, None]: Universal (async or sync) version of rulings_async(), same behavior but wrapped by universalasync().

async rulings_async(id: str, type: RulingIdentifierPath = RulingIdentifierPath.SCRYFALL, limit: int | None = None) → AsyncGenerator[Ruling, None]

Returns a single card with the given ID.

Depending on the type value, one of the following endpoint will be reached:

/cards/:id/rulings
/cards/multiverse/:id/rulings
/cards/mtgo/:id/rulings
/cards/arena/:id/rulings

Parameters:

id – The requested Card identifier string. In the case of card-number, use set/number (separated by a slash, for instance dmu/123)
type – The card identifier, please refer to RulingIdentifierPath enum

Returns:

A scryfall Ruling instance async generator

search(q: str, unique: UniqueStrategy = UniqueStrategy.CARDS, order: SortStrategy = SortStrategy.NAME, dir: DirectionStrategy = DirectionStrategy.AUTO, include_extras=False, include_multilingual=False, include_variations=False, limit: int = 100) → AsyncGenerator[Card, None]: Universal (async or sync) version of search_async(), same behavior but wrapped by universalasync().

async search_async(q: str, unique: UniqueStrategy = UniqueStrategy.CARDS, order: SortStrategy = SortStrategy.NAME, dir: DirectionStrategy = DirectionStrategy.AUTO, include_extras=False, include_multilingual=False, include_variations=False, limit: int = 100) → AsyncGenerator[Card, None]

Returns a List object containing Cards found using a fulltext search string. This string supports the same fulltext search system that the main site uses.

Parameters:

unique – The strategy for omitting similar cards.
order – The method to sort returned cards.
dir – The direction to sort cards.
include_extras – If true, extra cards (tokens, planes, etc) will be included. Equivalent to adding include:extras to the fulltext search.
include_multilingual – If true, cards in every language supported by Scryfall will be included.
include_variations – If true, rare care variants will be included, like the Hairy Runesword.
q – A fulltext search query.
limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results

Returns:

A scryfall Card instance async generator

set(limit: int | None = None) → AsyncGenerator[Set, None]: Universal (async or sync) version of sets_async(), same behavior but wrapped by universalasync().

async set_async(id_or_code: str | None = None) → Set

Returns a Set with the given set code.

Parameters:: id_or_code – The code can be either the code or the mtgo_code or the scryfall UUID for the set.
Returns:: A Set instance

sets(limit: int | None = None) → AsyncGenerator[Set, None]: Universal (async or sync) version of sets_async(), same behavior but wrapped by universalasync().

async sets_async(limit: int | None = None) → AsyncGenerator[Set, None]

Returns a List object of all Sets on Scryfall.

Parameters:: limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
Returns:: A Set instance async generator

symbols(limit: int | None = None) → AsyncGenerator[Symbol, None]: Universal (async or sync) version of symbols_async(), same behavior but wrapped by universalasync().

async symbols_async(limit: int | None = None) → AsyncGenerator[Symbol, None]

Returns a List of all Card Symbols.

Parameters:: limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
Returns:: A scryfall Symbol instance async generator

Scryfall Query Builder

Scryfall queries can be parsed and recomposed using binary operators. The Query objects can be assembled using this operators:

Operation	Operator	Example	Result
AND	`&`	`Query("emrakul") & Query("ulamog")`	`emrakul AND ulamog`
OR	`\|`	`Query("emrakul") \| Query("ulamog")`	`emrakul OR ulamog`
CONCAT	`+`	`Query("emrakul") + Query("ulamog")`	`emrakul AND ulamog`
EXCLUDE	`-`	`Query("emrakul") - Query("ulamog")`	`emrakul AND NOT(ulamog)`
NEGATE	`not`	`not Query("ulamog")`	`NOT(ulamog)`
XOR	`^`	`Query("emrakul") ^ Query("ulamog")`	`(emrakul OR ulamog) AND NOT (emrakul AND ulamog)`

from mightstone.services.scryfall.query import Query, Term

q = Query("f:modern order:rarity direction:asc") & Query("lang:japanese")

print("Recomposed (all explicit)")
print(q.to_string())

print("Recomposed (simplified)")
print(q.to_string(True))

assert isinstance(q[0], Term)
assert q[0].keyword.value == "format"
assert q[0].comparator.value == ":"
assert q[0].value == "modern"

assert isinstance(q[1], Term)
assert isinstance(q[2], Term)

xor = Query("t:creature") ^ Query("t:enchantment")

print("Recomposed (all explicit)")
print(xor.to_string())

print("Recomposed (simplified)")
print(xor.to_string(True))

class mightstone.services.scryfall.Query(operand: OpNode | str)

static parse(expression: str) → OpNode: Parse a string and return the root object (BinOp, UnOp, Term) :param expression: The string to parse :return:

to_string(shorten=False)

Recompose the query as a string

Parameters:: shorten – If true, the query will be simplified and shorten using less explicit statements
Returns:: The recomposed query

Models

`BulkTagType`(value)	An enumeration.
`Card`
`CardFace`
`Catalog`
`ManaCost`
`Migration`
`Preview`
`Ruling`	Rulings represent Oracle rulings, Wizards of the Coast set release notes, or Scryfall notes for a particular card.
`Set`	A Set object represents a group of related Magic cards. All Card objects on Scryfall
`Symbol`	A Card Symbol object represents an illustrated symbol that may appear in card’s mana cost or Oracle text.
`Tag`

MTGJSON

MTGJSON is an open-source project that catalogs all Magic: The Gathering data in portable formats. Using an aggregation process we fetch information between multiple resources and approved partners, and combine all that data in to various downloadable formats.

Feature	Support
JSON data	✅
Compressed JSON data	✅ (except zip)
SQLite data	❌
CSV data	❌
GraphQL API	❌

MtgJson Client

class mightstone.services.mtgjson.MtgJson(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None, compression: MtgJsonCompression | None = MtgJsonCompression.GZIP, version: int = 5)

MTGJSON client

Supports compression and will get gzip versions by default.

all_identifiers() → AsyncGenerator[Card, None]: Universal (async or sync) version of all_identifiers_async(), same behavior but wrapped by universalasync().

async all_identifiers_async() → AsyncGenerator[Card, None]

all Card (Set) cards organized by card UUID.

Returns:: An async iterator of Card object (either CardToken, or CardSet)

all_prices() → AsyncGenerator[CardPrices, None]: Universal (async or sync) version of all_prices_async(), same behavior but wrapped by universalasync().

async all_prices_async() → AsyncGenerator[CardPrices, None]

all prices of cards in various formats.

Returns:: An async iterator of CardPrices

all_printings() → AsyncGenerator[Set, None]: Universal (async or sync) version of all_printings_async(), same behavior but wrapped by universalasync().

async all_printings_async() → AsyncGenerator[Set, None]

all Card (Set) cards, including all printings and variations, categorized by set.

Returns:: An async iterator of CardSet

atomic_cards() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of atomic_cards_async(), same behavior but wrapped by universalasync().

async atomic_cards_async() → AsyncGenerator[CardAtomic, None]

every Card (Atomic) card.

Returns:: An async iterator of CardAtomic

base_url: str = 'https://mtgjson.com': Base url of the service (must be a root path such as https://example.com)

card_types() → CardTypes: Universal (async or sync) version of card_types_async(), same behavior but wrapped by universalasync().

async card_types_async() → CardTypes

every card type of any type of card.

Returns:: A CardTypes object

compiled_list() → List[str]: Universal (async or sync) version of compiled_list_async(), same behavior but wrapped by universalasync().

async compiled_list_async() → List[str]

all individual outputs from MTGJSON, such as AllPrintings, CardTypes, etc.

Returns:: A list of string

deck(file_name: str) → Deck: Universal (async or sync) version of deck_async(), same behavior but wrapped by universalasync().

async deck_async(file_name: str) → Deck

Recovers a deck data

Parameters:: file_name – the deck file_name
Returns:: A Deck object

deck_list() → AsyncGenerator[DeckList, None]: Universal (async or sync) version of deck_list_async(), same behavior but wrapped by universalasync().

async deck_list_async() → AsyncGenerator[DeckList, None]

all individual Deck data.

Returns:: An async iterator of DeckList

enum_values() → dict: Universal (async or sync) version of enum_values_async(), same behavior but wrapped by universalasync().

async enum_values_async() → dict

All known property values for various Data Models.

Returns:: a dict object

keywords() → Keywords: Universal (async or sync) version of keywords_async(), same behavior but wrapped by universalasync().

async keywords_async() → Keywords

a list of possible all keywords used on all cards.

Returns:: A Keywords object

legacy() → AsyncGenerator[Set, None]: Universal (async or sync) version of legacy_async(), same behavior but wrapped by universalasync().

async legacy_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Legacy format.

Returns:: An async iterator of Set

legacy_atomic() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of legacy_atomic_async(), same behavior but wrapped by universalasync().

async legacy_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Legacy format.

Returns:: An async iterator of CardAtomic

meta() → Meta: Universal (async or sync) version of meta_async(), same behavior but wrapped by universalasync().

async meta_async() → Meta

the metadata object with ISO 8601 dates for latest build and SemVer specifications of the MTGJSON release.

Returns:: A Meta object

modern() → AsyncGenerator[Set, None]: Universal (async or sync) version of modern_async(), same behavior but wrapped by universalasync().

async modern_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Modern format.

Returns:: An async iterator of Set

modern_atomic() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of modern_atomic_async(), same behavior but wrapped by universalasync().

async modern_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Modern format.

Returns:: An async iterator of CardAtomic

pauper_atomic() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of pauper_atomic_async(), same behavior but wrapped by universalasync().

async pauper_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Pauper format.

Returns:: An async iterator of CardAtomic

pioneer() → AsyncGenerator[Set, None]: Universal (async or sync) version of pioneer_async(), same behavior but wrapped by universalasync().

async pioneer_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to cards legal in the Pioneer format.

Returns:: An async iterator of Set

pioneer_atomic() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of pioneer_atomic_async(), same behavior but wrapped by universalasync().

async pioneer_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Pioneer format.

Returns:: An async iterator of CardAtomic

set(code: str) → SetList: Universal (async or sync) version of set_async(), same behavior but wrapped by universalasync().

async set_async(code: str) → SetList

Get a Set data

Parameters:: code – The set identifier, such as “IKO” for “Ikoria, lair of the monsters”
Returns:: The set representation

set_list() → AsyncGenerator[SetList, None]: Universal (async or sync) version of set_list_async(), same behavior but wrapped by universalasync().

async set_list_async() → AsyncGenerator[SetList, None]

a list of meta data for all Set data.

Returns:: An async iterator of SetList

standard() → AsyncGenerator[Set, None]: Universal (async or sync) version of standard_async(), same behavior but wrapped by universalasync().

async standard_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to cards legal in the Standard format.

Returns:: An async iterator of Set

standard_atomic() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of standard_atomic_async(), same behavior but wrapped by universalasync().

async standard_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to cards legal in the Standard format.

Returns:: An async iterator of CardAtomic

tcg_player_skus() → AsyncGenerator[TcgPlayerSKUs, None]: Universal (async or sync) version of tcg_player_skus_async(), same behavior but wrapped by universalasync().

async tcg_player_skus_async() → AsyncGenerator[TcgPlayerSKUs, None]

TCGplayer SKU information based on card UUIDs.

Returns:: an async iterator of TcgPlayerSKUs

vintage() → AsyncGenerator[Set, None]: Universal (async or sync) version of vintage_async(), same behavior but wrapped by universalasync().

async vintage_async() → AsyncGenerator[Set, None]

all Card (Set) cards organized by Set, restricted to sets legal in the Vintage format.

Returns:: An async iterator of Set

vintage_atomic() → AsyncGenerator[CardAtomic, None]: Universal (async or sync) version of vintage_atomic_async(), same behavior but wrapped by universalasync().

async vintage_atomic_async() → AsyncGenerator[CardAtomic, None]

all Card (Atomic) cards, restricted to sets legal in the Vintage format.

Returns:: An async iterator of CardAtomic

Models

`Card`	A card either a Card from a set, or a token
`Set`
`SetList`	The Set List Data Model describes a metadata-like properties and values for an individual Set.
`Meta`
`Keywords`
`Deck`	The Deck Data Model describes a complete deck reference.
`DeckList`	The Deck List Data Model describes a metadata-like model for a Deck.
`CardTypes`	The Card Types Data Model describes card types that a card may have.

Card Conjurer

Card Conjurer is a card editor service that provides a unique file format to describe a card image. Each card is described in a JSON file that extends a template. Template may vary from MTG copycat to brand new card frame.

Feature	Support
Template	✅ (read-only)
Card	✅ (read-only)
Card Generation	🟠 Working for the most part, but inline symbols are not supported

../_images/cardconjurer.sample.png — Fig 1. Card Conjurer generated image

../_images/cardconjurer.mightstone.png — Fig 2. Mightstone generated image

CardConjurer Client

class mightstone.services.cardconjurer.CardConjurer(default_font: str | None = None, **kwargs)

Card Conjurer client

base_url: str: Base url of the service (must be a root path such as https://example.com)

card(url_or_path) → Card: Universal (async or sync) version of card_async(), same behavior but wrapped by universalasync().

async card_async(url_or_path) → Card

Open a Card, local or through HTTP

Parameters:: url_or_path – A path or an url
Returns:: Card instance

render(card: Card, output=None) → Image: Universal (async or sync) version of render_async(), same behavior but wrapped by universalasync().

async render_async(card: Card, output=None) → Image

Render a card object into a PIL Image

Parameters:

card – Card model from Card Conjurer
output – A path or a file like object for writing

Returns:

A PIL Image object

template(url_or_path) → Template: Universal (async or sync) version of template_async(), same behavior but wrapped by universalasync().

async template_async(url_or_path) → Template

Open a Template, local or through HTTP

Parameters:: url_or_path – A path or an url
Returns:: Template instance

Models

`Card`	A Card as described in Card Conjurer JSON
`Template`	A Template as described in Card Conjurer JSON
`Image`	A layer composed of an image (One of the 3 possible layer types)
`Text`	A layer composed of a text (One of the 3 possible layer types)
`Group`	A layer composed of a list of other layers (One of the 3 possible layer types)

Wizards Of The Coast

RuleExplorer Client

class mightstone.services.wotc.RuleExplorer(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None)

explore(after: date, before: date | None = None, concurrency=3) → List[str]: Universal (async or sync) version of explore_async(), same behavior but wrapped by universalasync().

async explore_async(after: date, before: date | None = None, concurrency=3) → List[str]

Explore the wizards of the coast website to find any rule between two timestamp.

Wizards don’t support an historic index of previous rules, this method tries to compensate by providing a brute force attempt to pull magic rule history. This method will brute force every possible rule using the current format:

https://media.wizards.com/YYYY/downloads/MagicComp%20Rules%20{YYYY}{MM}{DD}.txt

Parameters:

after – The min date to scan
before – The max date to scan (defaults to today)
concurrency – The max number of concurrent HTTP requests

Returns:

A list of existing rules url

latest() → str: Universal (async or sync) version of latest_async(), same behavior but wrapped by universalasync().

async latest_async() → str

Resolves wizard latest published ruleset

Returns:: The url of the latest ruleset to date

open(path: str | None = None) → ComprehensiveRules: Universal (async or sync) version of open_async(), same behavior but wrapped by universalasync().

async open_async(path: str | None = None) → ComprehensiveRules

Open a local or remote comprehensive rule document, if no path is provided then the latest rules from Wizards of the Coast website is pulled.

Parameters:: path – A local path, or an URL to the rule document
Returns:: A ComprehensiveRules instance

Models

`ComprehensiveRules`
`Ruleset`
`Glossary`

Fandom Wiki

**MTG Wiki** at fandom is a great source of information with great details and references.

Feature	Support
Export page	✅
Export category	✅
Explore pages (based on Special:AllPages)	✅
Wiki parser (bold, italic, links, lists, titles, paragraphs, templates, html tags…)	✅

Wiki Client

class mightstone.services.wiki.Wiki(transport: AsyncCacheTransport | None = None, ijson: MightstoneIjsonBackend | None = None)

Scryfall API client

base_url: str = 'https://mtg.fandom.com': Base url of the service (must be a root path such as https://example.com)

async explore_pages(redirect=False) → AsyncGenerator[str, None]

Explore the Special:AllPages pages to generate a full list of available pages

You can optionally request pages that are redirects to others.

export_category(category) → bytes: Universal (async or sync) version of export_category_async(), same behavior but wrapped by universalasync().

async export_category_async(category) → bytes

Requests wiki on Special:Export page for a given category

Returns the raw output from the export

export_pages(pages: list[str]) → bytes: Universal (async or sync) version of export_pages_async(), same behavior but wrapped by universalasync().

async export_pages_async(pages: list[str]) → bytes

Requests wiki on Special:Export page for a given set of pages

Returns the raw output from the export

scrape_abilities() → AbilityList: Universal (async or sync) version of scrape_abilities_async(), same behavior but wrapped by universalasync().

async scrape_abilities_async() → AbilityList

Build an AbilityList object from the content of all Keywords categories

This is used to build mightstone.rule.data.ability content

class mightstone.services.wiki.WikiExportParser(base_url: str, content: bytes)

Raw page parser

abilities() → Generator[Ability, None, None]: A generator that extract all Abilities from a Wiki dump

page(name) → WikiPage | None: Tries to recover a named page (case sensitive) from the export Returns None if not available

pages() → Generator[WikiPage, None, None]: A generator that extract all WikiPage from a Wiki dump

Wiki Parser

class mightstone.services.wiki.WikiParser(page: WikiPage, enable_packrat=True)

A generic Wiki parser

get_wiki_html(tags: list[str] | None = None, max_matches=100, recurse=False) → Generator[WikiHtml, None, None]

Extract all wiki HTML tags

It is possible to limit result to a specific list of tags. If recurse option is activated, the method will instead resolve all nested tags.

get_wiki_links(max_matches=100, recurse=False) → Generator[WikiLink, None, None]

Extract all wiki links

If recurse option is activated, the method will instead resolve all nested tags.

get_wiki_templates(templates: list[str], max_matches=100, recurse=False) → Generator[WikiTemplate, None, None]

Extract all wiki templates ({{template | foo | bar}}) from a WikiPage at root level

It is possible to filter results by template names.

If recurse option is activated, the method will instead resolve all nested templates.

parse() → Generator[WikiElement, None, None]: Parse the wiki page and return a generator of WikiElements

class mightstone.services.wiki.MtgWikiParser(page: WikiPage, enable_packrat=True)

An Wiki syntax parser suitable for MTG Wiki needs

get_cards() → Generator[str | None, None, None]: Extract all cards references from WikiPage

get_glossaries() → Generator[str | None, None, None]: Extract all glossary references from WikiPage

get_infobox() → WikiTemplate | None: Get the infobox of the current page

get_rules() → Generator[str | None, None, None]: Extract all rule references from WikiPage

get_stats() → Generator[WikiTemplate, None, None]: Get all stats template

Models

`WikiElement`
`WikiPage`	A wiki dump page
`SerializableWikiPage`
`WikiTextStyle`(value)	An enumeration.
`WikiListStyle`(value)	An enumeration.
`WikiListItemStyle`(value)	An enumeration.
`WikiString`	Representation of a string in the wiki
`WikiStyledText`	Representation of a styled text content
`WikiLink`	Representation of a WikiLink
`WikiRevision`	A Revision description in the Wiki dump
`WikiTemplate`	Representation of a wiki template
`WikiFlow`	A representation of a wiki flow
`WikiParagraph`	Representation of a wiki paragraph
`WikiTitle`	Representation of a wiki title
`WikiListBullet`
`WikiListItem`	Representation of a list item
`WikiList`	Representation of a Wiki List
`WikiHtml`	Representation of an HTML tag

`PageAverageDeck`
`PageBackground`
`PageBackgrounds`
`PageCard`
`PageCombo`
`PageCombos`
`PageCommander`
`PageCommanders`
`PageCompanions`
`PageDeck`
`PageDecks`
`PageManaStaples`
`PagePartner`
`PagePartners`
`PageSalts`
`PageSet`
`PageSets`
`PageStaples`
`PageTheme`
`PageThemes`
`PageTopCards`
`PageTypal`
`PageTypals`