# 🤖 anki-robo
An Anki-card-creation framework. Quickly create [Anki](https://apps.ankiweb.net/)
cards using data from remote sources. (Or any sources, really!)
## Table of contents
- [Warning](#-warning-)
- [What is anki-robo?](#what-is-anki-robo)
- [Who is it for?](#who-is-it-for)
- [Quick-start](#quick-start)
- [Requirements](#requirements)
- [Installation](#installation)
- [Available data sources](#available-data-sources)
- [Future plans / roadmap](#future-plans--roadmap)
- [I'd like to contribute / set up a new data source](#id-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](https://apps.ankiweb.net/) 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](extractor-details.md#sample-data-1) 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](https://jotoba.de/) | Japanese -> English | [Details](extractor-details.md#jotoba)
| `linguee-de-en` | [Linguee](https://www.linguee.com/german-english/) | German -> English | [Details](extractor-details.md#linguee)
| `linguee-es-en` | [Linguee](https://www.linguee.com/spanish-english/) | Spanish -> English | [Details](extractor-details.md#linguee)
| `linguee-fr-en` | [Linguee](https://www.linguee.com/french-english/) | French -> English | [Details](extractor-details.md#linguee)
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:
```python
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](https://beautiful-soup-4.readthedocs.io/en/latest/)
- 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "anki-robo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "anki",
"author": "Keith Fancher",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/77/54/ba5e6fc3004e60971ac4cf3e007d2fc59668a71dd57b729818fc655ac6d0/anki_robo-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83e\udd16 anki-robo\n\nAn Anki-card-creation framework. Quickly create [Anki](https://apps.ankiweb.net/)\ncards using data from remote sources. (Or any sources, really!)\n\n## Table of contents\n\n- [Warning](#-warning-)\n- [What is anki-robo?](#what-is-anki-robo)\n- [Who is it for?](#who-is-it-for)\n- [Quick-start](#quick-start)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Available data sources](#available-data-sources)\n- [Future plans / roadmap](#future-plans--roadmap)\n- [I'd like to contribute / set up a new data source](#id-like-to-contribute--set-up-a-new-data-source)\n\n## \ud83d\udea8 Warning \ud83d\udea8\n\nanki-robo is still **EARLY** in its development. It's beta software, at best.\nUse at your own risk!\n\nAnd of course you should **always remember to back up your Anki deck before\nmaking any changes to it**, whether with this tool or any other. Don't take\nany chances with your precious Anki data!\n\n(That said, don't worry: anki-robo does **not** currently make any changes to\nyour Anki deck directly. It simply outputs Anki-importable CSV files. You're\nin complete control of how that data is imported into your decks.)\n\n## What is anki-robo?\n\nanki-robo is (or will be) a few things:\n\n1. \ud83e\udde9 **A Python library/framework** which provides a common, generic\n interface for extracting data from various sources and creating [Anki\n cards](https://apps.ankiweb.net/) from that data;\n2. \ud83d\udcbb **a CLI application** which uses the above framework to extract data\n from a library of pre-configured sources and automatically create Anki\n cards;\n3. \ud83d\udd0c **an Anki plugin** which integrates the above behavior directly into the\n Anki desktop application (but which doesn't exist yet).\n\nIn short, anki-robo is an **Anki-card-creation framework**.\n\n## Who is it for?\n\nDo you use Anki? Do you ever make Anki cards? It might be for you.\n\n## Quick-start\n\nThe `anki-robo` CLI app takes the name of a *data source* and an *input file*.\nThe file contains newline-delimited search terms. `anki-robo` will query the\ndata source with each search term and collect the resulting data into an\nAnki-importable format.\n\nFirst, let's check what data sources are available with the `anki-robo list`\ncommand:\n\n```\n$ anki-robo list\njotoba-jp-en\nlinguee-de-en\nlinguee-es-en\nlinguee-fr-en\n```\n\nNow, let's say I'm studying French. I keep a running list of words I want to\nmake Anki cards for later. Here's my list so far:\n\n```\n$ cat vocabulaire.txt\nhilarant\nfl\u00e2ner\nencre\noreiller\ntonnerre\n```\n\nOkay, let's make our cards! We use the `anki-robo get` command. Again, it\ntakes the name of the data source (`linguee-fr-en`) and the file with my\nsearch terms (`vocabulaire.txt`):\n\n```\n$ anki-robo get linguee-fr-en vocabulaire.txt\nExtracting data from source `linguee-fr-en` using search keys from file: vocabulaire.txt...\nWriting CSV output to ankirobo-linguee-fr-en-1709946408.csv... Complete!\n```\n\nThe CSV data file will be populated with the words, their definitions, sample\nsentences, and plenty of other data for your Anki cards.\n\nNow I can open Anki, import `ankirobo-linguee-fr-en-1709946408.csv` and start\nlearning my new words! (See the Linguee extractor's [sample\ndata](extractor-details.md#sample-data-1) to get an idea of what fields are\nincluded in this particular case.)\n\n## Requirements\n\n- Python >= `3.9` (which is also the version currently bundled with Anki)\n\nThe following dependencies will be installed automatically if you use `pip` to\ninstall anki-robo:\n\n- `requests`\n- `beautifulsoup4`\n\n## Installation\n\nTo install the latest stable version of anki-robo from PyPI, use `pip`:\n\n```\n$ pip install anki-robo\n```\n\nIf you'd like to install the bleeding-edge, not-yet-released version, you can\ndo that too:\n\n```\n$ pip install https://github.com/keithfancher/anki-robo/archive/refs/heads/master.tar.gz\n```\n\nYou can also simply clone the repo and run the included `anki-robo` binary\ndirectly. However, in this case you'll need to manually install anki-robo's\ndependencies. The quickest way to do that is to use the included\n`requirements.txt` file:\n\n```\n$ pip install -r requirements.txt\n```\n\n## Available data sources\n\nanki-robo has extractors for the following data sources so far, with more on\nthe way!\n\n| Name | Source | Type | Info |\n|------|--------|------|------|\n| `jotoba-jp-en` | [Jotoba](https://jotoba.de/) | Japanese -> English | [Details](extractor-details.md#jotoba)\n| `linguee-de-en` | [Linguee](https://www.linguee.com/german-english/) | German -> English | [Details](extractor-details.md#linguee)\n| `linguee-es-en` | [Linguee](https://www.linguee.com/spanish-english/) | Spanish -> English | [Details](extractor-details.md#linguee)\n| `linguee-fr-en` | [Linguee](https://www.linguee.com/french-english/) | French -> English | [Details](extractor-details.md#linguee)\n\nClick a \"Details\" link above for more information about using a given\nextractor, the type of data returned, etc.\n\n## Future plans / roadmap\n\n- [ ] Option to output an Anki `.apkg` file instead of a `.csv`\n- [ ] Accept markdown input (lists and checklists)\n- [ ] Media support (audio, images, &c.)\n- [ ] Merge results from multiple data sources into a single output set\n- [ ] Anki plugin, to use directly from desktop Anki interface\n- [ ] More data sources!\n- [ ] ...and so on :D\n\n## I'd like to contribute / set up a new data source\n\nAwesome! It's easy, if you've got a little Python experience. Comprehensive\ndocumentation does not exist yet, but here's a quick overview.\n\nThe fundamental interface for anki-robo is an `Extractor`. An `Extractor` is\njust a function which takes a single string (one search key) and returns a\nlist of `Result` objects. (There's also a flag for testing -- but don't worry\nabout that for now.)\n\nThe `Result` object is a simple Python dictionary -- essentially a map of\nstring -> string. This corresponds to \"Anki field name -> field data\". One\n`Result` corresponds to one Anki card.\n\nIn other words, an extractor is just a function that look like this:\n\n```python\ndef extract(key: str) -> list[Result]:\n ...\n```\n\nThat's it! Under the hood, your extractor can do anything it wants. For\nexample:\n\n- Scrape web data using [Beautiful\n Soup](https://beautiful-soup-4.readthedocs.io/en/latest/)\n- Pull data from a REST API\n- Process local files (Ebooks? Text files? &c.)\n- ...or whatever else! (Assuming you can implement it in Python.)\n\nYou write the code to extract data for a single term, and anki-robo will tie\nthe pieces together for you.\n",
"bugtrack_url": null,
"license": null,
"summary": "An Anki-card-creation framework",
"version": "0.1.0",
"project_urls": {
"GitHub": "https://github.com/keithfancher/anki-robo"
},
"split_keywords": [
"anki"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "147194ad3aa6d831e676e325999273240144cee5abe09c5e4022509f71d8c821",
"md5": "5b0e484dd564e2bcddbc8c2b3eaa955a",
"sha256": "3a6ee4acb5a8fde72b43fc04e4b26a3adddb6dd78a9dee6f604fa9e32dc0b9e6"
},
"downloads": -1,
"filename": "anki_robo-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b0e484dd564e2bcddbc8c2b3eaa955a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 656665,
"upload_time": "2024-03-23T19:23:04",
"upload_time_iso_8601": "2024-03-23T19:23:04.388705Z",
"url": "https://files.pythonhosted.org/packages/14/71/94ad3aa6d831e676e325999273240144cee5abe09c5e4022509f71d8c821/anki_robo-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7754ba5e6fc3004e60971ac4cf3e007d2fc59668a71dd57b729818fc655ac6d0",
"md5": "eeaa403cfd010c1ac3414e780ed158cd",
"sha256": "dc8165b458685a486b62c384e744cfcb7951c2886658b673d8cd0c33e42450c0"
},
"downloads": -1,
"filename": "anki_robo-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "eeaa403cfd010c1ac3414e780ed158cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 647336,
"upload_time": "2024-03-23T19:23:07",
"upload_time_iso_8601": "2024-03-23T19:23:07.200830Z",
"url": "https://files.pythonhosted.org/packages/77/54/ba5e6fc3004e60971ac4cf3e007d2fc59668a71dd57b729818fc655ac6d0/anki_robo-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-23 19:23:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keithfancher",
"github_project": "anki-robo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "beautifulsoup4",
"specs": [
[
"==",
"4.12.3"
]
]
},
{
"name": "build",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"7.4.4"
]
]
},
{
"name": "mypy",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.1.1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "ruff",
"specs": [
[
"==",
"0.3.3"
]
]
},
{
"name": "types-beautifulsoup4",
"specs": [
[
"==",
"4.12.0.20240229"
]
]
},
{
"name": "types-requests",
"specs": [
[
"==",
"2.31.0.20240311"
]
]
}
],
"lcname": "anki-robo"
}
JSON
