hanky 0.0.1__tar.gz

hanky-0.0.1/.gitignore

@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

hanky-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hanky-0.0.1/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.3
+Name: hanky
+Version: 0.0.1
+Summary: Simple library and command line tool for loading flash cards into anki.
+Project-URL: Homepage, https://github.com/Haeata-Ash/hanky
+Project-URL: Issues, https://github.com/Haeata-Ash/hanky/issues
+Author-email: HBA <hanky-pypi.8ebs0@simplelogin.com>
+License-File: LICENSE
+Keywords: anki
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: anki
+Requires-Dist: psutil
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hanky
+
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+
+Library and command line application for loading flash cards into anki.
+
+> **:information_source: Note:**
+> This project is currently in alpha and is not stable.
+
+## Installation
+
+Install via pip:
+
+`pip install hanky`
+
+Optionally install text to speech code seen in tutorial:
+
+` pip install hanky[toc]`
+
+## Configuration
+
+Currently two configuration options are exposed:
+
+- `anki_database`: tells hanky where to find the anki collection (an sqlite database where anki stores flash cards and other data). The normal locations at the time of writing are as follows:
+    - MAC OS
+        - `~/Library/Application Support/Anki2/User 1/collection.anki2`
+    - Linux
+        - `~/.local/share/Anki2/User 1/collection.anki2`
+
+- `database_safety_check`: a boolean which when set to `true` will check for any running processes using the anki collection.
+    > **:warning: Caution:** 
+    > Setting this option to false may result in database corruption. Always ensure your anki is backed up.
+
+- `allow_duplicates`: a boolean which when set to `true` allows duplicate cards (all field values match another cards field values) to be added.
+s
+Example configuration:
+
+```toml
+# where to find the anki collection (sqlite db where anki stores data)
+# Usual system lo
+anki_database = "~/.local/share/Anki2/User 1/collection.anki2"
+
+# whether or not to check for other processes using the anki database
+database_safety_check = true
+
+# whether or not to allow duplicate cards to be added
+allow_duplicates = false
+```
+
+## Usage 
+
+Hanky can be used as both a command line application and a library. 
+
+- If you want to do something more complex than simply adding cards directly from files, such as generating speech, querying an api or performing other operations at runtime, see the [Library Tutorial](#library-tutorial)
+
+- If you just want to load flash cards from files, jump to the [command line usage](#command-line-usage)
+
+## Library Tutorial
+
+
+## Command Line Usage
+
+Hanky can be used out of the box as a command line application. If running your own hanky script, omit the `-m` seen in the below examples.
+
+### Recursively load decks from files in a folder
+
+Recursively load all csv files as decks of cards using the 'basic' anki model/note type. The relative path from the specified folder will be used as the deck name.
+
+`python3 -m hanky load "basic" "~/french/" "*.csv" -r`
+
+For example, given the following folder structure:
+```
+french
+├── animals.csv
+├── bodies.csv
+├── clothing.csv
+└── grammar
+    └── passe_compose.csv
+```
+
+The following decks will be created:
+- `french`: top level deck
+- `french::animals`: nested animal vocab deck
+- `french::bodies`: nested bodies vocab deck
+- `french::clothing`: nested clothing vocab deck
+- `french::grammar`: nested container deck for grammar
+- `french::grammar::passe_compose`: doubly nested deck for passe compose rules
+
+The created anki decks will have the following structure:
+```
+french
+├── animals
+├── bodies
+├── clothing
+└── grammar
+    └── passe_compose
+```
+
+### Load decks from files from a folder
+
+Load all csv files in a folder as decks of cards using the 'basic' anki model/note type. The relative path from the specified folder will be used as the deck name.
+
+`python3 -m hanky load "basic" "~/french/" "*.csv"`
+
+For example, given the following folder structure:
+```
+french
+├── animals.csv
+├── bodies.csv
+├── clothing.csv
+└── grammar
+    └── passe_compose.csv
+```
+
+The following decks will be created:
+- `french`: top level deck
+- `french::animals`: nested animal vocab deck
+- `french::bodies`: nested bodies vocab deck
+- `french::clothing`: nested clothing vocab deck
+
+The created anki decks will have the following structure:
+```
+french
+├── animals
+├── bodies
+├── clothing
+```
+
+### Load a deck from a file
+
+Load a single deck using the 'basic' anki model/note type from a file
+
+`python3 -m hanky load-deck "basic" ~/my-folder/countries.csv`
+
+The following deck will be created:
+- `countries`

hanky-0.0.1/README.md

@@ -0,0 +1,136 @@
+# hanky
+
+[![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)
+
+Library and command line application for loading flash cards into anki.
+
+> **:information_source: Note:**
+> This project is currently in alpha and is not stable.
+
+## Installation
+
+Install via pip:
+
+`pip install hanky`
+
+Optionally install text to speech code seen in tutorial:
+
+` pip install hanky[toc]`
+
+## Configuration
+
+Currently two configuration options are exposed:
+
+- `anki_database`: tells hanky where to find the anki collection (an sqlite database where anki stores flash cards and other data). The normal locations at the time of writing are as follows:
+    - MAC OS
+        - `~/Library/Application Support/Anki2/User 1/collection.anki2`
+    - Linux
+        - `~/.local/share/Anki2/User 1/collection.anki2`
+
+- `database_safety_check`: a boolean which when set to `true` will check for any running processes using the anki collection.
+    > **:warning: Caution:** 
+    > Setting this option to false may result in database corruption. Always ensure your anki is backed up.
+
+- `allow_duplicates`: a boolean which when set to `true` allows duplicate cards (all field values match another cards field values) to be added.
+s
+Example configuration:
+
+```toml
+# where to find the anki collection (sqlite db where anki stores data)
+# Usual system lo
+anki_database = "~/.local/share/Anki2/User 1/collection.anki2"
+
+# whether or not to check for other processes using the anki database
+database_safety_check = true
+
+# whether or not to allow duplicate cards to be added
+allow_duplicates = false
+```
+
+## Usage 
+
+Hanky can be used as both a command line application and a library. 
+
+- If you want to do something more complex than simply adding cards directly from files, such as generating speech, querying an api or performing other operations at runtime, see the [Library Tutorial](#library-tutorial)
+
+- If you just want to load flash cards from files, jump to the [command line usage](#command-line-usage)
+
+## Library Tutorial
+
+
+## Command Line Usage
+
+Hanky can be used out of the box as a command line application. If running your own hanky script, omit the `-m` seen in the below examples.
+
+### Recursively load decks from files in a folder
+
+Recursively load all csv files as decks of cards using the 'basic' anki model/note type. The relative path from the specified folder will be used as the deck name.
+
+`python3 -m hanky load "basic" "~/french/" "*.csv" -r`
+
+For example, given the following folder structure:
+```
+french
+├── animals.csv
+├── bodies.csv
+├── clothing.csv
+└── grammar
+    └── passe_compose.csv
+```
+
+The following decks will be created:
+- `french`: top level deck
+- `french::animals`: nested animal vocab deck
+- `french::bodies`: nested bodies vocab deck
+- `french::clothing`: nested clothing vocab deck
+- `french::grammar`: nested container deck for grammar
+- `french::grammar::passe_compose`: doubly nested deck for passe compose rules
+
+The created anki decks will have the following structure:
+```
+french
+├── animals
+├── bodies
+├── clothing
+└── grammar
+    └── passe_compose
+```
+
+### Load decks from files from a folder
+
+Load all csv files in a folder as decks of cards using the 'basic' anki model/note type. The relative path from the specified folder will be used as the deck name.
+
+`python3 -m hanky load "basic" "~/french/" "*.csv"`
+
+For example, given the following folder structure:
+```
+french
+├── animals.csv
+├── bodies.csv
+├── clothing.csv
+└── grammar
+    └── passe_compose.csv
+```
+
+The following decks will be created:
+- `french`: top level deck
+- `french::animals`: nested animal vocab deck
+- `french::bodies`: nested bodies vocab deck
+- `french::clothing`: nested clothing vocab deck
+
+The created anki decks will have the following structure:
+```
+french
+├── animals
+├── bodies
+├── clothing
+```
+
+### Load a deck from a file
+
+Load a single deck using the 'basic' anki model/note type from a file
+
+`python3 -m hanky load-deck "basic" ~/my-folder/countries.csv`
+
+The following deck will be created:
+- `countries`

hanky-0.0.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hanky"
+authors = [{ name = "HBA", email = "hanky-pypi.8ebs0@simplelogin.com" }]
+description = "Simple library and command line tool for loading flash cards into anki."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Operating System :: Unix",
+]
+
+keywords = ["anki"]
+dynamic = ["version"]
+
+dependencies = [
+  "anki",
+  "psutil"
+]
+
+[project.optional-dependencies]
+# tos = [
+#   "boto3"
+# ]
+
+dev = [
+  "pytest",
+  "mypy"
+]
+
+[project.urls]
+Homepage = "https://github.com/Haeata-Ash/hanky"
+Issues = "https://github.com/Haeata-Ash/hanky/issues"
+
+[tool]
+
+[tool.hatch.version]
+path = "src/hanky/__about__.py"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.github",
+  "/docs",
+  "/tests",
+  "/.venv",
+  "/.mypy_cache",
+  "/demo.py",
+  "/.*"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hanky"]

hanky-0.0.1/src/hanky/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

hanky-0.0.1/src/hanky/__init__.py

@@ -0,0 +1 @@
+from .hanky import Hanky as Hanky

hanky-0.0.1/src/hanky/__main__.py

@@ -0,0 +1,5 @@
+from hanky import Hanky
+
+if __name__ == "__main__":
+    hanky = Hanky()
+    hanky.run()

hanky-0.0.1/src/hanky/cli.py

@@ -0,0 +1,135 @@
+import argparse
+
+
+# def make_parser():
+#     parser = argparse.ArgumentParser(
+#         "hanky",
+#         description="Simple program to allow programatic management of anki cards",
+#     )
+#     parser.add_argument(
+#         "--config",
+#         dest="config",
+#         nargs=1,
+#         help="Path to hanky json configuration file",
+#     )
+
+
+#     object_subparsers = parser.add_subparsers(
+#         dest = "object",
+#         help="Type of anki object to manage",
+#         required = True
+#     )
+
+
+#     card_obj = object_subparsers.add_parser(
+#         "card", help="Perform an operation on anki cards."
+#     )
+
+#     card_cmds = card_obj.add_subparsers(
+#         dest="action",
+#         required=True,
+#         help="Action to perform against anki cards."
+#     )
+
+#     # add anki cards to a deck using model
+#     add_card = card_cmds.add_parser("add", help="Add card(s) to an anki deck.")
+#     add_card.add_argument("-i", "--input-file", required=True, help="Source file to add the cards from.")
+#     add_card.add_argument("-m", "--model", required=True, help="Anki model to create the card from.")
+#     add_card.add_argument("-d", "--deck", required=True, help="Anki deck add the card to")
+#     add_card.add_argument("--model-args", help="Arguments to pass to the model.")
+#     # list anki cards in a deck
+#     list_card = card_cmds.add_parser("list", help="List card(s) in an anki deck.")
+#     list_card.add_argument("-d", "--deck", required=True, help="List anki cards from deck")
+
+
+#     deck_obj = object_subparsers.add_parser(
+#         "deck", help="Perform an operation on an anki deck."
+#     )
+
+
+#     deck_cmds = deck_obj.add_subparsers(
+#         dest="action",
+#         required=True,
+#         help="Action to perform against an anki deck."
+#     )
+
+
+#     add_deck = deck_cmds.add_parser("add", help="Add deck to the anki collection.")
+
+#     # add anki deck
+#     add_deck.add_argument("name", help="Full name of the anki deck, including '::' for nesting.")
+#     add_deck.add_argument("-p", "--parent", help="Optionally specify parent deck to avoid manually adding '::' for nesting.")
+    
+#     # list anki decks
+#     add_deck = deck_cmds.add_parser("list", help="Add deck to the anki collection.")
+
+
+#     model_obj = object_subparsers.add_parser(
+#         "model", help="Perform an operation on an anki model."
+#     )
+
+#     model_cmds = model_obj.add_subparsers(
+#         dest="action",
+#         required=True,
+#         help="Action to perform against an anki model."
+#     )
+
+#     # list anki cards in a deck
+#     add_card = model_cmds.add_parser("list", help="List models in anki collection.")
+    
+#     return parser
+
+
+class KeyValueArg(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        setattr(namespace, self.dest, dict())
+
+        for v in values:
+            print(v)
+            key, value = v.split("=")
+            getattr(namespace, self.dest)[key] = value
+
+def make_parser():
+    parser = argparse.ArgumentParser(
+        "hanky",
+        description="Simple program to allow programatic management of anki cards",
+    )
+    parser.add_argument(
+        "--config",
+        dest="config",
+        help="Path to hanky json configuration file",
+    )
+
+    op_parser = parser.add_subparsers(
+        dest = "operation",
+        help="Type of operation to perform",
+        required = True
+    )
+    load_file = op_parser.add_parser(
+        "load-deck",
+        help="Load cards into an anki deck from a file"
+    )
+    load_file.add_argument(
+        "model",
+        help="Name of the anki model to create cards with."
+    )
+    load_file.add_argument("file", help="Path of the file to load from")
+
+
+    load_file.add_argument("-d", "--deck", dest="deck", default=None, help="Name of the deck to load cards into. If not specified, defaults to the filename without the extension.")
+    load_file.add_argument("--args", dest="args", default={}, nargs="*", action=KeyValueArg, help="Key value arguments to pass to registered transformers.")
+
+    load_dir = op_parser.add_parser(
+        "load",
+        help="Load cards into anki deck(s) from files in a directory, using the filenames as deck names."
+    )
+    load_dir.add_argument("-r", "--recursive", dest="is_rec", action="store_true", default=False, help="If loading files from a directory, recursively load from files in sub directories as well.")
+    load_dir.add_argument(
+        "model",
+        help="Name of the anki model to create cards with."
+    )
+    load_dir.add_argument("dir", help="Path of the file to load from")
+    load_dir.add_argument("pattern", help="Glob pattern used to decide which files to load. For example, '*.csv'")
+
+    load_dir.add_argument("--args", dest="args", default={}, nargs="*", action=KeyValueArg, help="Key value arguments to pass to registered transformers.")
+    return parser

hanky-0.0.1/src/hanky/config.py

@@ -0,0 +1,56 @@
+import platform
+from pathlib import Path
+from typing import Callable, Union
+
+def _get_default_anki_db_path() -> str:
+    """Choose a default path for the anki sqlite collection database based on
+    the OS.
+
+    Defaults:
+        Linux: "~/.local/share/Anki2/User 1/collection.anki2"
+        MacOS: "~/Library/Application Support/Anki2/User 1/collection.anki2"
+    """
+    if platform.system() == "Linux":
+        return "~/.local/share/Anki2/User 1/collection.anki2"
+    elif platform.system() == "Darwin":
+        return "~/Library/Application Support/Anki2/User 1/collection.anki2"
+    else:
+        return ""
+
+
+ANKI_DB_PATH = "anki_database"
+DO_SAFET_CHECK = "database_safety_check"
+ALLOW_DUPLICATES = "allow_duplicates"
+
+DEFAULT_CONFIG = {
+    ANKI_DB_PATH: _get_default_anki_db_path(),
+    DO_SAFET_CHECK: True,
+    ALLOW_DUPLICATES: False
+}
+
+class Config(dict):
+    """Configuration object"""
+
+
+    def __init__(self, **kwargs):
+        self._config = None
+        self.default_path = Path("~/.config/hanky/hanky.toml").expanduser()
+        super().__init__(kwargs)
+
+    def from_file(
+        self,
+        file: Union[Path, str],
+        loader: Callable[[Union[str, Path], dict], dict],
+        text=False,
+        **kwargs,
+    ):
+        with open(file, "r" if text else "rb") as f:
+            cfg = loader(f, **kwargs)
+            if not isinstance(cfg, dict):
+                raise TypeError(
+                    f"Received type '{type(cfg)}' but expected '{type(dict)}' from loader function."
+                )
+
+            for k, v in cfg.items():
+                self[k] = v
+

hanky-0.0.1/src/hanky/fs.py

@@ -0,0 +1,35 @@
+from typing import Generator, Iterator, Union, TextIO, Callable
+from pathlib import Path
+import json
+import csv
+import psutil
+
+
+def read_file(
+    path: str, loader: Callable[[TextIO], Union[Iterator, Generator]]
+) -> Union[Iterator, Generator]:
+    path = Path(path)
+    if not path.is_file():
+        raise IOError(f"{path} is not a file.")
+    with open(path, "r") as f:
+        for item in loader(f):
+            yield item
+
+
+DEFAULT_LOADERS = {".json": json.load, ".csv": csv.DictReader}
+
+
+
+
+def has_handle(fpath):
+    fpath = Path(fpath).expanduser().absolute()
+    for proc in psutil.process_iter():
+        try:
+            for item in proc.open_files():
+                if str(fpath) == str(item.path):
+                    return True
+        except psutil.Error: 
+            pass
+
+    return False
+

hanky-0.0.1/src/hanky/hanky.py

@@ -0,0 +1,351 @@
+import functools
+import hashlib
+from pathlib import Path
+from typing import Callable, Generator, Iterator, List, Union
+
+from anki.collection import Collection, SearchNode
+from tomllib import load as toml_load
+
+from hanky.cli import make_parser
+from hanky.config import (
+    ALLOW_DUPLICATES,
+    ANKI_DB_PATH,
+    DEFAULT_CONFIG,
+    DO_SAFET_CHECK,
+    Config,
+)
+from hanky.fs import DEFAULT_LOADERS, has_handle, read_file
+from hanky.media import is_audio_ext, make_anki_sound_ref
+
+
+class ModelProcessor:
+    def __init__(self, model_name: str, func, expected_args, required_fields):
+        self.f = func
+        self.model = model_name
+        self.expected_args = expected_args
+        self.required_fields = required_fields
+
+        if not isinstance(self.expected_args, list):
+            raise TypeError("'expected_args' must be a list of strings")
+        if not isinstance(self.required_fields, list):
+            raise TypeError("'required_fields' must be a list of strings")
+
+    def __call__(self, card: dict, **kwargs) -> dict:
+        for k in self.required_fields:
+            if k not in card:
+                raise KeyError(
+                    f"Processor requires '{k}' to be present in card. \n {str(card)}"
+                )
+
+        for k in self.expected_args:
+            if k not in kwargs:
+                raise KeyError(
+                    f"Processor for {self.model} expects key word argument '{k}'. Ensure it is passed in via the --model-args option"
+                )
+
+        ret = self.f(card, **kwargs)
+        if not isinstance(ret, dict):
+            raise TypeError(
+                f"Processor function did not return a dictionary like object, returned type {type(ret)}"
+            )
+
+        return ret
+
+
+class Hanky:
+    def __init__(self, **kwargs):
+        # set default config and then overwrite with config object provided via constructor
+        # ensures default keys are present
+        self.config: Config = Config(**DEFAULT_CONFIG)
+        if kwargs:
+            self.config.update(kwargs)
+
+        self._col: Collection = None
+
+        self.processors = dict()
+        self.loaders = dict(DEFAULT_LOADERS)
+
+    def run(self):
+        parser = make_parser()
+        args = parser.parse_args()
+
+        if args.config:
+            self.config.from_file(args.config, toml_load)
+
+        if args.operation == "load-deck":
+            self.load_deck(
+                args.file,
+                args.model,
+                deck_name=args.deck,
+                **(args.args) if args.args else {},
+            )
+
+        elif args.operation == "load":
+            self.load_dir(
+                args.model,
+                args.dir,
+                args.pattern,
+                recursive=args.is_rec,
+                *(args.args) if args.args else {},
+            )
+
+    @property
+    def col(self):
+        if not self._col:
+            if not self.config[ANKI_DB_PATH]:
+                raise RuntimeError(
+                    """Path to anki sqlite collection database was 
+                    not provided in config and no suitable default known."""
+                )
+            db_path = Path(self.config[ANKI_DB_PATH]).expanduser().absolute()
+
+            if not db_path.exists() or not db_path.is_file():
+                raise FileNotFoundError(
+                    f"'{db_path}' either does not exist or is not a file. Please check the provided path to the anki collection."
+                )
+
+            if self.config[DO_SAFET_CHECK]:
+                if has_handle(self.config[ANKI_DB_PATH]):
+                    raise RuntimeError(
+                        """At least one other process is using the anki database. Ensure the Anki application is closed before using Hanky to avoid possible corruption."""
+                    )
+
+            self._col = Collection(db_path)
+        return self._col
+
+    def add_card(
+        self,
+        deck_name,
+        model_name,
+        filter_query: str = None,
+        allow_duplicates=False,
+        **fields,
+    ) -> bool:
+        model = self.col.models.by_name(model_name)
+        if not model:
+            raise ValueError(
+                f"Model '{model_name}' does not exist in your anki collection. Ensure it has been added before using it with hanky."
+            )
+        deck_id = self.col.decks.id(deck_name, create=False)
+        if not deck_id:
+            ValueError(
+                f"Deck '{deck_name}' does not exist in your anki collection. Ensure it has been created before using it with hanky."
+            )
+        expected_fields = self.col.models.field_names(model)
+        for k in expected_fields:
+            if k not in fields:
+                raise KeyError(f"Expected field '{k}' is missing.")
+
+        new_card = self.col.new_note(model)
+
+        for k, v in fields.items():
+            new_card[k] = str(v)
+
+        if filter_query:
+            matches = self.col.find_cards(filter_query)
+            if len(matches):
+                return False
+
+        allow_duplicates = allow_duplicates if allow_duplicates else self.config[ALLOW_DUPLICATES]
+
+        if not allow_duplicates:
+            rets = [True]
+
+            for field in fields:
+                if self.col.find_notes(
+                    self.col.build_search_string(
+                        new_card[field], SearchNode(field_name=field)
+                    )
+                ):
+                    rets.append(True)
+                else:
+                    rets.append(False)
+
+            is_dupe = functools.reduce(lambda x, y: x and y, rets)
+
+            if is_dupe:
+                return False
+
+        self.col.add_note(new_card, deck_id)
+
+        return True
+
+    def add_deck(self, deck_name) -> bool:
+        self.col.decks.id(deck_name)
+        return True
+
+    def register_loader(
+        self, file_ext: str, loader: Callable[[str], Union[Iterator, Generator]]
+    ):
+        self.loaders[file_ext] = loader
+
+    def register_card_processor(
+        self,
+        model_name: str,
+        handler: Callable[[dict], dict],
+        expected_args: List[str] = [],
+        expected_fields: List[str] = [],
+    ):
+        if model_name not in self.processors:
+            self.processors[model_name] = []
+        self.processors[model_name].append(
+            ModelProcessor(model_name, handler, expected_args, expected_fields)
+        )
+
+    def card_processor(
+        self, model: str, expected_args: List[str], expected_fields: List[str]
+    ):
+        def decorator(func):
+            self.register_card_processor(model, func, expected_args, expected_fields)
+            return func
+
+        return decorator
+
+    def get_model_processors(self, model_name: str) -> List[ModelProcessor]:
+        if model_name in self.processors:
+            return self.processors[model_name]
+
+        return []
+
+    def get_loader(self, suffix) -> Callable:
+        return self.loaders[suffix]
+
+    def load_deck(
+        self,
+        fpath: str,
+        model_name: str,
+        deck_name: str = None,
+        loader=None,
+        parent_deck="",
+        **model_args,
+    ):
+        print(f"Loading into deck {deck_name}")
+        fpath = Path(fpath).absolute()
+
+        transformers = self.get_model_processors(model_name)
+        loader = loader if loader else self.get_loader(fpath.suffix)
+
+        model = self.col.models.by_name(model_name)
+        if not model:
+            raise KeyError(
+                f"Model '{model_name}' does not exist in your anki collection. Ensure it has been added before using it with hanky."
+            )
+
+        # deck is the specified name or filename without extension
+        deck_name = deck_name if deck_name else fpath.stem
+
+        self.add_deck(deck_name)
+
+        count = 0
+        total = 0
+        for item in read_file(fpath, loader):
+            card = dict(item)
+            for t in transformers:
+                card = t(card, **model_args)
+
+            ret = self.add_card(
+                deck_name,
+                model_name,
+                **card,
+            )
+            total += 1
+            if ret:
+                count += 1
+        
+        print(f"Added {count} out of {total} cards.")
+
+    def add_media(
+        self, data, anki_media_filename: str = None, file_ext: str = None
+    ) -> str:
+        ext = None
+        if anki_media_filename:
+            path = Path(anki_media_filename)
+            ext = path.suffix
+        elif file_ext:
+            ext = file_ext
+        else:
+            raise ValueError(
+                "If argument 'anki_media_filename' is not provided then 'file_ext' must be present"
+            )
+
+        if isinstance(data, str):
+            data = data.encode()
+
+        desired_name = anki_media_filename
+
+        # no filename given, use hash of the data plus file_ext
+        if not desired_name:
+            m = hashlib.sha256()
+            m.update(data)
+            desired_name = m.hexdigest() + ext
+
+        # write media to anki database
+        actual_name = self.col.media.write_data(
+            desired_name,
+            data,
+        )
+
+        anki_ref = self.col.media.escape_media_filenames(actual_name)
+
+        if is_audio_ext(actual_name):
+            anki_ref = make_anki_sound_ref(anki_ref)
+
+        return anki_ref
+
+    def add_media_file(self, local_path) -> str:
+        anki_ref = self.col.media.escape_media_filenames(
+            self.col.media.add_file(local_path)
+        )
+        if is_audio_ext(anki_ref):
+            anki_ref = make_anki_sound_ref(anki_ref)
+
+        return anki_ref
+
+    def load_dir(
+        self,
+        model: str,
+        root_dir: str,
+        glob_pattern: str,
+        recursive=False,
+        parent_deck: str = "",
+        loader=None,
+        **model_args,
+    ):
+        parent_deck = ""
+
+        root = Path(root_dir).expanduser()
+
+        root_deck = parent_deck if parent_deck else root.name
+
+        def _glob(root, pattern, recursive):
+            if recursive:
+                for path in root.rglob(pattern):
+                    yield path
+            else:
+                for path in root.glob(pattern):
+                    yield path
+
+        for path in _glob(root, glob_pattern, recursive):
+            if path.is_file():
+                path = path.relative_to(root)
+                abs_path = root.joinpath(path)
+                parents = [p.name for p in reversed(path.parents)]
+
+                # don't need the first empty entry for the current directory
+                parents.pop(0)
+                deck_list = [root_deck]
+
+                i = 0
+                while i < len(parents):
+                    deck_list.append(parents[i])
+                    i += 1
+                deck_list.append(path.stem)
+                full_deck = "::".join(deck_list)
+
+                self.load_deck(
+                    abs_path,
+                    model,
+                    deck_name=full_deck,
+                    loader=loader,
+                    **model_args,
+                )

hanky-0.0.1/src/hanky/media.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+
+def is_audio_ext(filename: str) -> bool:
+    AUDIO_EXT = set(
+            ".mp3",
+            ".oga",
+            ".opus",
+            ".wav",
+            ".weba",
+            ".aac",
+        )
+    
+    if Path(filename).suffix in AUDIO_EXT:
+        return True
+    
+    return False
+
+
+def make_anki_sound_ref(media_ref: str) -> str:
+    return f"[sound:{media_ref}]"