From 9bc656b2680b675498fa098d8c6838380c170f4e Mon Sep 17 00:00:00 2001 From: "hampton.ford" Date: Wed, 13 Aug 2025 21:15:21 -0600 Subject: [PATCH 1/4] add detail on initiating a collection --- src/the-anki-module.md | 75 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 70 insertions(+), 5 deletions(-) diff --git a/src/the-anki-module.md b/src/the-anki-module.md index ef983b2..9b8f2d2 100644 --- a/src/the-anki-module.md +++ b/src/the-anki-module.md @@ -9,11 +9,35 @@ in Anki's source repo. All operations on a collection file are accessed via a `Collection` object. The currently-open Collection is accessible via a global `mw.col`, -where `mw` stands for `main window`. When using the `anki` module outside -of Anki, you will need to create your own Collection object. +where `mw` stands for `main window`. -Some basic examples of what you can do follow. Please note that you should put -these in something like [testFunction()](./a-basic-addon.md). You can’t run them +**Initiate collection from mw:** +```python +from anki.collection import ImportCsvRequest +from aqt import mw + + +col = mw.col +``` +When using the `anki` module outside of Anki, the `mw` object will not exist. +You will need to create your own `Collection` object +from `collection.anki2` ([see docs ]( https://docs.ankiweb.net/files.html) +or [use our helper function](#get-collection-path-helper-function)). + +**Initiate collection from file:** +```python +from anki.collection import Collection + + +profile_name = 'insert_your_profile_name' # hint: default is 'User 1' +# col_path = 'insert_manually' # manual insertion +col_path = get_collection_path(profile_name) # using helper function +col = Collection(col_path) +``` + +Some basic examples of what you can do with a collection follow. +With `mw` usage, please note that you should put +these in something like [testFunction()](./a-basic-addon.md); you can’t run them directly in an add-on, as add-ons are initialized during Anki startup, before any collection or profile has been loaded. @@ -73,7 +97,8 @@ Requires Anki 2.1.55+. ```python from anki.collection import ImportCsvRequest from aqt import mw -col = mw.col + + path = "/home/dae/foo.csv" metadata = col.get_csv_metadata(path=path, delimiter=None) request = ImportCsvRequest(path=path, metadata=metadata) @@ -196,3 +221,43 @@ If you need to store addon-specific data, consider using Anki’s If you need the data to sync across devices, small options can be stored within mw.col.conf. Please don’t store large amounts of data there, as it’s currently sent on every sync. + +**Get collection path helper function** +```python +import os +import platform + +def get_collection_path(profile_name, attempts=0): + def get_anki_dir(attempts, *anki_dir_tuple): + anki_dir_tuple = anki_dir_tuple[attempts:] # try progressively older locations + for path in anki_dir_tuple: + if os.path.exists(path): + return path + raise FileNotFoundError('No anki collection file not found in any of the searched directories.') + + collection_anki2_filename = 'collection.anki2' + system = platform.system() + profile_dir = '' + + # get dir - locations may be found at https://docs.ankiweb.net/files.html + if system == 'Windows': + modern_dir = f'{USER_PATH}/AppData/Roaming/%APPDATA%/Anki2/{profile_name}' + old_dir = f'{USER_PATH}/Documents/{profile_name}' + profile_dir = get_anki_dir(attempts, modern_dir, old_dir) + elif system == 'Linux': + modern_collection = f'{USER_PATH}/.local/share/Anki2/{profile_name}' + old_collection = f'{USER_PATH}/Documents/Anki/{profile_name}' + older_collection = f'{USER_PATH}/Anki/{profile_name}' + profile_dir = get_anki_dir(attempts, modern_collection, old_collection, older_collection) + elif system == 'Darwin': + modern_collection = f'{USER_PATH}/Library/Application Support/Anki2/{profile_name}' + old_collection = f'{USER_PATH}/Documents/Anki/{profile_name}' + profile_dir = get_anki_dir(attempts, modern_collection, old_collection) + + # ensure file exists + path = f'{profile_dir}/{collection_anki2_filename}' + if not os.path.exists(path): + return get_collection_path(profile_name, attempts+1) + + return path +``` \ No newline at end of file From 11a6964b31d9c5f40e9ee0b9b90773d55f404902 Mon Sep 17 00:00:00 2001 From: "hampton.ford" Date: Wed, 20 Aug 2025 20:48:27 -0600 Subject: [PATCH 2/4] fixed broken windows path --- src/the-anki-module.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/the-anki-module.md b/src/the-anki-module.md index 9b8f2d2..bfa74fa 100644 --- a/src/the-anki-module.md +++ b/src/the-anki-module.md @@ -241,7 +241,7 @@ def get_collection_path(profile_name, attempts=0): # get dir - locations may be found at https://docs.ankiweb.net/files.html if system == 'Windows': - modern_dir = f'{USER_PATH}/AppData/Roaming/%APPDATA%/Anki2/{profile_name}' + modern_dir = f'{USER_PATH}/AppData/Roaming/Anki2/{profile_name}' old_dir = f'{USER_PATH}/Documents/{profile_name}' profile_dir = get_anki_dir(attempts, modern_dir, old_dir) elif system == 'Linux': From f3cac4677d4c1322d5e04995fd94fad27432eeb3 Mon Sep 17 00:00:00 2001 From: "hampton.ford" Date: Tue, 26 Aug 2025 19:34:30 -0600 Subject: [PATCH 3/4] slight tweak based on feedback --- src/the-anki-module.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/the-anki-module.md b/src/the-anki-module.md index bfa74fa..2bf5177 100644 --- a/src/the-anki-module.md +++ b/src/the-anki-module.md @@ -8,12 +8,13 @@ in Anki's source repo. ## The Collection All operations on a collection file are accessed via a `Collection` -object. The currently-open Collection is accessible via a global `mw.col`, -where `mw` stands for `main window`. +object. -**Initiate collection from mw:** +If running code inside an add-on, the Anki collection will be +accessible via the Anki main window, called `mw`, as shown below. + +**Access collection from mw:** ```python -from anki.collection import ImportCsvRequest from aqt import mw @@ -21,7 +22,7 @@ col = mw.col ``` When using the `anki` module outside of Anki, the `mw` object will not exist. You will need to create your own `Collection` object -from `collection.anki2` ([see docs ]( https://docs.ankiweb.net/files.html) +from `collection.anki2` ([see docs]( https://docs.ankiweb.net/files.html) or [use our helper function](#get-collection-path-helper-function)). **Initiate collection from file:** @@ -30,14 +31,13 @@ from anki.collection import Collection profile_name = 'insert_your_profile_name' # hint: default is 'User 1' -# col_path = 'insert_manually' # manual insertion col_path = get_collection_path(profile_name) # using helper function col = Collection(col_path) ``` Some basic examples of what you can do with a collection follow. -With `mw` usage, please note that you should put -these in something like [testFunction()](./a-basic-addon.md); you can’t run them +With `mw` usage, please note that you should put its calls +in something like [testFunction()](./a-basic-addon.md); you can’t run them directly in an add-on, as add-ons are initialized during Anki startup, before any collection or profile has been loaded. From b9e65ab85a8c7c5e8a2658fdc1ad572cbfa01aef Mon Sep 17 00:00:00 2001 From: "hampton.ford" Date: Thu, 28 Aug 2025 00:26:45 -0600 Subject: [PATCH 4/4] remove helper function. replace w/ aqt basepath --- src/the-anki-module.md | 49 ++++-------------------------------------- 1 file changed, 4 insertions(+), 45 deletions(-) diff --git a/src/the-anki-module.md b/src/the-anki-module.md index 2bf5177..3b66d9b 100644 --- a/src/the-anki-module.md +++ b/src/the-anki-module.md @@ -22,16 +22,15 @@ col = mw.col ``` When using the `anki` module outside of Anki, the `mw` object will not exist. You will need to create your own `Collection` object -from `collection.anki2` ([see docs]( https://docs.ankiweb.net/files.html) -or [use our helper function](#get-collection-path-helper-function)). +from the `collection.anki2` file. The file can located via the [the docs](https://docs.ankiweb.net/files.html) +or as shown below. **Initiate collection from file:** ```python from anki.collection import Collection +from aqt.profiles import ProfileManager - -profile_name = 'insert_your_profile_name' # hint: default is 'User 1' -col_path = get_collection_path(profile_name) # using helper function +col_path = ProfileManager.get_created_base_folder(None) col = Collection(col_path) ``` @@ -221,43 +220,3 @@ If you need to store addon-specific data, consider using Anki’s If you need the data to sync across devices, small options can be stored within mw.col.conf. Please don’t store large amounts of data there, as it’s currently sent on every sync. - -**Get collection path helper function** -```python -import os -import platform - -def get_collection_path(profile_name, attempts=0): - def get_anki_dir(attempts, *anki_dir_tuple): - anki_dir_tuple = anki_dir_tuple[attempts:] # try progressively older locations - for path in anki_dir_tuple: - if os.path.exists(path): - return path - raise FileNotFoundError('No anki collection file not found in any of the searched directories.') - - collection_anki2_filename = 'collection.anki2' - system = platform.system() - profile_dir = '' - - # get dir - locations may be found at https://docs.ankiweb.net/files.html - if system == 'Windows': - modern_dir = f'{USER_PATH}/AppData/Roaming/Anki2/{profile_name}' - old_dir = f'{USER_PATH}/Documents/{profile_name}' - profile_dir = get_anki_dir(attempts, modern_dir, old_dir) - elif system == 'Linux': - modern_collection = f'{USER_PATH}/.local/share/Anki2/{profile_name}' - old_collection = f'{USER_PATH}/Documents/Anki/{profile_name}' - older_collection = f'{USER_PATH}/Anki/{profile_name}' - profile_dir = get_anki_dir(attempts, modern_collection, old_collection, older_collection) - elif system == 'Darwin': - modern_collection = f'{USER_PATH}/Library/Application Support/Anki2/{profile_name}' - old_collection = f'{USER_PATH}/Documents/Anki/{profile_name}' - profile_dir = get_anki_dir(attempts, modern_collection, old_collection) - - # ensure file exists - path = f'{profile_dir}/{collection_anki2_filename}' - if not os.path.exists(path): - return get_collection_path(profile_name, attempts+1) - - return path -``` \ No newline at end of file