anki-robo 0.1.0

An Anki-card-creation framework

🤖 anki-robo

An Anki-card-creation framework. Quickly create Anki cards using data from remote sources. (Or any sources, really!)

Table of contents

• Warning
• What is anki-robo?
• Who is it for?
• Quick-start
• Requirements
• Installation
• Available data sources
• Future plans / roadmap
• I'd like to contribute / set up a new data source

🚨 Warning 🚨

anki-robo is still EARLY in its development. It's beta software, at best. Use at your own risk!

And of course you should always remember to back up your Anki deck before making any changes to it, whether with this tool or any other. Don't take any chances with your precious Anki data!

(That said, don't worry: anki-robo does not currently make any changes to your Anki deck directly. It simply outputs Anki-importable CSV files. You're in complete control of how that data is imported into your decks.)

What is anki-robo?

anki-robo is (or will be) a few things:

1. 🧩 A Python library/framework which provides a common, generic interface for extracting data from various sources and creating Anki cards from that data;
2. 💻 a CLI application which uses the above framework to extract data from a library of pre-configured sources and automatically create Anki cards;
3. 🔌 an Anki plugin which integrates the above behavior directly into the Anki desktop application (but which doesn't exist yet).

In short, anki-robo is an Anki-card-creation framework.

Who is it for?

Do you use Anki? Do you ever make Anki cards? It might be for you.

Quick-start

The anki-robo CLI app takes the name of a data source and an input file. The file contains newline-delimited search terms. anki-robo will query the data source with each search term and collect the resulting data into an Anki-importable format.

First, let's check what data sources are available with the anki-robo list command:

$ anki-robo list
jotoba-jp-en
linguee-de-en
linguee-es-en
linguee-fr-en

Now, let's say I'm studying French. I keep a running list of words I want to make Anki cards for later. Here's my list so far:

$ cat vocabulaire.txt
hilarant
flâner
encre
oreiller
tonnerre

Okay, let's make our cards! We use the anki-robo get command. Again, it takes the name of the data source (linguee-fr-en) and the file with my search terms (vocabulaire.txt):

$ anki-robo get linguee-fr-en vocabulaire.txt
Extracting data from source `linguee-fr-en` using search keys from file: vocabulaire.txt...
Writing CSV output to ankirobo-linguee-fr-en-1709946408.csv... Complete!

The CSV data file will be populated with the words, their definitions, sample sentences, and plenty of other data for your Anki cards.

Now I can open Anki, import ankirobo-linguee-fr-en-1709946408.csv and start learning my new words! (See the Linguee extractor's sample data to get an idea of what fields are included in this particular case.)

Requirements

• Python >= 3.9 (which is also the version currently bundled with Anki)

The following dependencies will be installed automatically if you use pip to install anki-robo:

• requests
• beautifulsoup4

Installation

To install the latest stable version of anki-robo from PyPI, use pip:

$ pip install anki-robo

If you'd like to install the bleeding-edge, not-yet-released version, you can do that too:

$ pip install https://github.com/keithfancher/anki-robo/archive/refs/heads/master.tar.gz

You can also simply clone the repo and run the included anki-robo binary directly. However, in this case you'll need to manually install anki-robo's dependencies. The quickest way to do that is to use the included requirements.txt file:

$ pip install -r requirements.txt

Available data sources

anki-robo has extractors for the following data sources so far, with more on the way!

Name	Source	Type	Info
jotoba-jp-en	Jotoba	Japanese -> English	Details
linguee-de-en	Linguee	German -> English	Details
linguee-es-en	Linguee	Spanish -> English	Details
linguee-fr-en	Linguee	French -> English	Details

Click a "Details" link above for more information about using a given extractor, the type of data returned, etc.

Future plans / roadmap

• Option to output an Anki .apkg file instead of a .csv
• Accept markdown input (lists and checklists)
• Media support (audio, images, &c.)
• Merge results from multiple data sources into a single output set
• Anki plugin, to use directly from desktop Anki interface
• More data sources!
• ...and so on :D

I'd like to contribute / set up a new data source

Awesome! It's easy, if you've got a little Python experience. Comprehensive documentation does not exist yet, but here's a quick overview.

The fundamental interface for anki-robo is an Extractor. An Extractor is just a function which takes a single string (one search key) and returns a list of Result objects. (There's also a flag for testing -- but don't worry about that for now.)

The Result object is a simple Python dictionary -- essentially a map of string -> string. This corresponds to "Anki field name -> field data". One Result corresponds to one Anki card.

In other words, an extractor is just a function that look like this:

def extract(key: str) -> list[Result]:
    ...

That's it! Under the hood, your extractor can do anything it wants. For example:

• Scrape web data using Beautiful Soup
• Pull data from a REST API
• Process local files (Ebooks? Text files? &c.)
• ...or whatever else! (Assuming you can implement it in Python.)

You write the code to extract data for a single term, and anki-robo will tie the pieces together for you.