Automating Magic: The Gathering Card Collection in Notion with Python and the notion-client Library
I've got an interesting post for you today. If you're into Magic: The Gathering, you're in for a treat. But don't worry if Magic isn't your thing – you might still be interested in the Notion API I used to create this script. I made use of this Python library: https://pypi.org/project/notion-client/.
Thanks to my brother, since 1997 I'm into Magic the Gathering, even if I stopped for about 15 years, since 2022 I'm back in the game, so I felt compelled to create a database, inspired by Thomas Frank tweet:
You can find the GitHub repository here: https://github.com/alessandrobelli/mtg-notion-importer. Any suggestion or help is welcome!
First, let's take a look at the Notion Database table structure that you need to create before you run the script. You can get a better understanding of the table from the
|Column Name||Column Type||Description|
|Name||Title||Name of the card|
|Mana Cost||Text||Mana cost of the card|
|Set||Multi-select||Set the card belongs to|
|Rarity||Select||Rarity of the card|
|Text||Text||Oracle text of the card|
|Flavor Text||Text||Flavor text of the card|
|Power||Text||Power of the card (for creatures)|
|Toughness||Text||Toughness of the card (for creatures)|
|Power/Toughness||Text||Combined power/toughness (for creatures)|
|Loyalty||Text||Loyalty of the card (for planeswalkers)|
|Legalities||Multi-select||Legalities in various formats|
|Artist||Text||Name of the card's artist|
|Keywords||Multi-select||Keywords found in the card's oracle text|
|Scryfall ID||Text||Unique identifier for the card from Scryfall database|
To run the script, follow these steps:
- Ensure you have Python installed on your computer. If you don't have it, you can download it from the official Python website.
- Install the required Python libraries by running the following command in your terminal or command prompt:
pip install notion-client requests.
- Clone or download the script from the GitHub repository. If you're not familiar with cloning a GitHub repository, you can simply download the ZIP file and extract it to a folder on your computer.
- Create a
.envfile and set up your Notion API key and database ID.
Open your terminal or command prompt, navigate to the directory where you saved the script, and run the following command:
script_name.py with the actual name of the script file.
This is how it looks when importing:
For more detailed instructions and explanations, please visit the GitHub page of the project.
Now let's break down the main functions of the script:
get_most_recent_card(): Retrieves the most recent card from your Notion database, based on the
updated_atproperty. This is used to ask if you want to restart after a crash, or you want to simply restart the script from the same set after you stopped it.
update_or_create_page(): Updates an existing page or creates a new one with the card information. This function uses exponential backoff to handle HTTP errors and timeouts. I'm not sure why, but while developing the script I encountered a lot of 502 and timeout errors in the Notion Api.
create_table_block(): Creates a table block for the card page, containing preview data, prices, related URIs, and purchase URIs.
format_legalities(): Formats the card's legalities into a more readable form.
get_card_by_scryfall_id(): Retrieves a card from the Notion database by its Scryfall ID, using exponential backoff for error handling.
extract_keywords(): Extracts keywords from a card's oracle text.
import_cards(): Imports cards from the Scryfall API, updating or creating pages for each card in the Notion database.
In conclusion, this script is a great way to import Magic: The Gathering cards into your Notion database. There I created a “self relation” property called “combo”, but you can find in many ways how to build decks or find combos.
However, please be aware that it might take some time to finish since Magic has more than 22,000 cards. I hope you found this article useful or you could be a little inspired by the script.
Thanks a lot for reading, feel free to share if you liked it! See you next time!