Skip to content

Latest commit

 

History

History
274 lines (214 loc) · 13.2 KB

README.md

File metadata and controls

274 lines (214 loc) · 13.2 KB

Analyze and manipulate your Anki collection using pandas!

Documentation Status Gitter License PR welcome

pre-commit.ci status gh actions Coveralls CodeQL gitmoji Black Pypi status

📝 Description

Note This package needs a new maintainer, as I currently do not have enough time to continue development of this package. Writing modifications back into the Anki database is currently disabled, in particular because of issue #137. Please reach out to me if you are interested in getting involved!

Anki is one of the most popular flashcard system for spaced repetition learning, pandas is the most popular python package for data analysis and manipulation. So what could be better than to bring both together?

With AnkiPandas you can use pandas to easily analyze or manipulate your Anki flashcards.

Features:

  • Select: Easily select arbitrary subsets of your cards, notes or reviews using pandas (one of many introductions, official documentation)
  • Visualize: Use pandas' powerful built in tools or switch to the even more versatile seaborn (statistical analysis) or matplotlib libraries
  • Manipulate: Apply fast bulk operations to the table (e.g. add tags, change decks, set field contents, suspend cards, ...) or iterate over the table and perform these manipulations step by step. ⚠️ This functionality is currently disabled until #137 has been resolved! ⚠️
  • Import and Export: Pandas can export to (and import from) csv, MS Excel, HTML, JSON, ... (io documentation)

Pros:

  • Easy installation: Install via python package manager (independent of your Anki installation)
  • Simple: Just one line of code to get started
  • Convenient: Bring together information about cards, notes, models, decks and more in just one table!
  • Fully documented: Documentation on readthedocs
  • Well tested: More than 100 unit tests to keep everything in check

Alternatives: If your main goal is to add new cards, models and more, you can also take a look at the genanki project.

📦 Installation

AnkiPandas is available as pypi package and can be installed or upgrade with the python package manager:

pip3 install --user --upgrade ankipandas

Development installation

For the latest development version you can also work from a cloned version of this repository:

git clone https://github.com/klieret/ankipandas/
cd ankipandas
pip3 install --user --upgrade --editable .

If you want to help develop this package further, please also install the pre-commit hooks and use gitmoji:

pre-commit install
gitmoji -i

🔥 Let's get started!

Starting up is as easy as this:

from ankipandas import Collection

col = Collection()

And col.notes will be dataframe containing all notes, with additional methods that make many things easy. Similarly, you can access cards or reviews using col.cards or col.revs.

If called without any argument Collection() tries to find your Anki database by itself. However this might take some time. To make it easier, simply supply (part of) the path to the database and (if you have more than one user) your Anki user name, e.g. Collection(".local/share/Anki2/", user="User 1") on many Linux installations.

To get information about the interpretation of each column, use print(col.notes.help_cols()).

Take a look at the documentation to find out more about more about the available methods!

Some basic examples:

📈 Analysis

More examples: Analysis documentation, projects that use AnkiPandas.

Show a histogram of the number of reviews (repetitions) of each card for all decks:

col.cards.hist(column="creps", by="cdeck")

Show the number of leeches per deck as pie chart:

cards = col.cards.merge_notes()
selection = cards[cards.has_tag("leech")]
selection["cdeck"].value_counts().plot.pie()

Find all notes of model MnemoticModel with empty Mnemotic field:

notes = col.notes.fields_as_columns()
notes.query("model=='MnemoticModel' and 'Mnemotic'==''")

🛠️ Manipulations

Warning Writing the database has currently been disabled until #137 has been resolved. Help is much appreciated!

Warning Please be careful and test this well! Ankipandas will create a backup of your database before writing, so you can always restore the previous state. Please make sure that everything is working before continuing to use Anki normally!

Add the difficult-japanese and marked tag to all notes that contain the tags Japanese and leech:

notes = col.notes
selection = notes[notes.has_tags(["Japanese", "leech"])]
selection = selection.add_tag(["difficult-japanese", "marked"])
col.notes.update(selection)
col.write(modify=True)  # Overwrites your database after creating a backup!

Set the language field to English for all notes of model LanguageModel that are tagged with English:

notes = col.notes
selection = notes[notes.has_tag(["English"])].query("model=='LanguageModel'").copy()
selection.fields_as_columns(inplace=True)
selection["language"] = "English"
col.notes.update(selection)
col.write(modify=True)

Move all cards tagged leech to the deck Leeches Only:

cards = col.cards
selection = cards[cards.has_tag("leech")]
selection["cdeck"] = "Leeches Only"
col.cards.update(selection)
col.write(modify=True)

🐞 Troubleshooting

See the troubleshooting section in the documentation.

💖 Contributing

Your help is greatly appreciated! Suggestions, bug reports and feature requests are best opened as github issues. You could also first discuss in the gitter community. If you want to code something yourself, you are very welcome to submit a pull request!

Bug reports and pull requests are credited with the help of the allcontributors bot.

📃 License & Disclaimer

This software is licenced under the MIT license and (despite best testing efforts) comes without any warranty. The logo is inspired by the Anki logo (license) and the logo of the pandas package (license2). This library and its author(s) are not affiliated/associated with the main Anki or pandas project in any way.

✨ Contributors

Thanks goes to these wonderful people (emoji key):

Blocked
Blocked

🐛
CalculusAce
CalculusAce

🐛
Francis Tseng
Francis Tseng

🐛 💻
Keith Hughitt
Keith Hughitt

🐛
Miroslav Šedivý
Miroslav Šedivý

⚠️ 💻
Nicholas Bollweg
Nicholas Bollweg

💻
Thomas Brownback
Thomas Brownback

🐛
eshrh
eshrh

📖
exc4l
exc4l

🐛 💻
p4nix
p4nix

🐛

This project follows the all-contributors specification. Contributions of any kind welcome!