pyMTGJSon

A small python library designged to ease to write scripts/apps that use data from mtgjson.com.

Example use

>>> from mtgjson import CardDb
>>> db = CardDb.from_url()
>>> card = db.find_card_by_name(u'aether vial')
>>> card.name
u'\xc6ther Vial'
>>> print card.name
Æther Vial
>>> card.cmc
1
>>> card.text
u'At the beginning of your upkeep, you may put a charge counter on \xc6ther Vial.\n{T}: You may put a creature card with converted mana cost equal to the number of charge counters on \xc6ther Vial from your hand onto the battlefield.'
>>> card.img_url
'http://mtgimage.com/set/MMA/aether vial.jpg'

See the documentation at http://pythonhosted.org/mtgjson for more.

The database object

Since the actual data files are not included, they either need to be supplied or downloaded upon instantiation. Redownloading them every time the application is started is usually a bad idea, but may be feasible if you expect restarts on every few days.

The quickest way to get started is:

from mtgjson import CardDb
db = CardDb.from_url()

This will download AllSets.json from the http://mtgjson.com website. You can pass in a different address as well:

db = CardDb.from_url(ALL_SETS_X_ZIP_URL)

Here ALL_SETS_X_ZIP_URL is one of the constants that hold the URLs for http://mtgjson.com download links.

If you’ve downloaded the files already, the from_file() function allows you to pass these files to the CardDb.

If your data is stored elsewhere, it is always possible to just pass the data dictionary (i.e. the output of loads()) directly to CardDb.

class mtgjson.CardDb(db_dict)

The central object of the library. Upon instantiation, reads card data into memory and creates various indices to allow easy card retrieval. The data passed in is kept in memory and wrapped in a friendly interface.

Note that usually one of the factory method (from_file() or from_url()) is used to instantiate a db.

Parameters:db_dict – Deserializied mtgjson.com AllSets.json.
cards_by_id

Contains a mapping of card numbers (the multiverse id) to CardProxy instances. Should be used to look up card by their IDs:

card = db.cards_by_id[180607]

Note that the multiverse id (like the name) does not specificy which set a card is from if it has been reprinted. The returned card will always be the most recent printing.

cards_by_name

Like mtgjson.CardProxy.cards_by_id, but indexed by card name:

card = db.cards_by_name['Sen Triplets']
cards_by_ascii_name

Uses a lower-case, ascii-only version of the card name:

card = db.cards_by_ascii_name['jotun grunt']
assert card.name == u'Jötun Grunt'
sets

An OrderedDict of all sets found in the data file. Keys are the three-letter set codes (like ISD for Inistrad), mapped onto SetProxy instances. Ordered by publishing date, i.e. Limited Edition Alpha is the first value of the dict.

classmethod from_file(db_file='/tmp/tmpcqjEjq/mtgjson/AllSets.json')

Reads card data from a JSON-file.

Parameters:db_file – A file-like object or a path.
Returns:A new CardDb instance.
classmethod from_url(db_url='http://mtgjson.com/json/AllSets.json.zip')

Load card data from a URL.

Uses requests.get() to fetch card data. Also handles zipfiles.

Parameters:db_url – URL to fetch.
Returns:A new CardDb instance.

Cards

Cards retrieved are usually CardProxy instances:

class mtgjson.CardProxy(data)

A wrapper for a card dictionary.

Provides additional methods and attributes onto the plain data from mtgjson.com.

Cards support a total ordering that will use the set’s release date or if cards are from the same set, the collector’s number. Cards without a collectors number use the canonical ordering system based on color/type/card name.

ascii_name

Simplified name (ascii characters, lowercase) for card.

gatherer_url

Gatherer link.

img_url

URL where an image of the card can be found.

Sets

Sets, similar to cards are wrapped in SetProxy:

class mtgjson.SetProxy(data)

Wraps set dictionary with additional methods and attributes. Also subject to total ordering based on release date.

cards_by_id

Similar to mtgjson.CardDb.cards_by_id, but will always point to the card instance of this specific set instead of the latest.

cards_by_name

See above.

This is especially important when trying to fetch a card of a specific set:

# get an unlimited black lotus
card = db.cards_by_name('Black Lotus')

# black bordered, please:
beta = db.sets['LEB']
card = beta.cards_by_name('Black Lotus')