ankitextlayer 0.1.0__tar.gz

ankitextlayer-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: ankitextlayer
+Version: 0.1.0
+Summary: Bidirectional sync between Anki and Markdown
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: beautifulsoup4>=4.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# AnkiTextLayer (ATL)
+
+Write your decks in Markdown, sync them to Anki for studying, make edits in either place, and sync changes back.
+
+## Why Use This
+
+- **Write in Markdown**: Your cards live in plain text: easy to edit fast, search, refactor, and review in your editor.
+- **Keep full overview**: Browse hundreds of cards in one file, search across decks instantly, and reorganize freely.
+- **Work with AI**: Markdown is a great interface for AI help (drafting, rephrasing, generating variants) while you stay in control of the final wording.
+- **Version control**: Track exactly what changed and when, roll back safely, and collaborate using Git like any other text-based project.
+
+If you already love Anki for studying, ATL just upgrades how you create and maintain your cards.
+
+## How It Works
+
+In a directory of your choice, each Markdown file represents an Anki deck. On first sync, ATL assigns HTML comment IDs to each card for tracking. After that, it knows what's new, changed, moved between decks, or deleted, and will sync accordingly.
+
+Two note types are provided: `LayerQA` and `LayerCloze`. In a markdown file, each field is represented by a line starting with a specific letter and a colon. `Q:` and `A:` start question and answer fields, `T:` starts a text field for clozes, and `E:` and `M:` start optional extra and "more" fields on the back of the card. Cards are separated by a blank line, three dashes, and another blank line.
+
+A fresh markdown deck could look like this:
+
+```markdown
+Q: What is the capital of France?
+A: Paris.
+E: ![alt text](tour_eiffel.png){width=700}
+
+---
+
+T: The capital of Germany is {{c1::Berlin}}.
+```
+
+With the first ATL sync to Anki, the deck and each card gets a unique ID in an HTML comment:
+
+```markdown
+<!-- deck_id: 1770487991521 -->
+<!-- card_id: 1770487991522 -->
+Q: What is the capital of France?
+A: Paris.
+E: ![alt text](tour_eiffel.png){width=700}
+
+---
+
+<!-- note_id: 1770487991521 -->
+T: The capital of Germany is {{c1::Berlin}}.
+```
+
+ATL only acts on the provided note types, so your existing collection is never affected. You can mix managed and unmanaged cards in the same deck without issues.
+
+Before every ATL sync, it automatically creates a Git commit so you can always roll back if something breaks.
+
+## How to Get Started
+
+Install via [pipx](https://github.com/pypa/pipx):
+```bash
+pipx install ankitextlayer
+```
+Make sure Anki is running, with the [AnkiConnect add-on](https://ankiweb.net/shared/info/2055492159) enabled. Then initialize ATL in any directory (not your Anki data folder):
+
+```bash
+ankitextlayer init --tutorial
+```
+The tutorial flag creates a sample markdown deck with further information. We can import it into Anki using:
+```bash
+ankitextlayer ma
+```
+Where `ma` is shorthand for `markdown-to-anki`. Conversely, there is `ankitextlayer am` for `anki-to-markdown`. The tutorial deck should provide you with a good starting point to explore the features of ATL.
+
+## Workflow
+
+Start by writing your cards in Markdown. Images can be added by pasting them directly into your markdown file in VS Code as explained in the tutorial. When you ATL sync to Anki, the images are saved in the media collection of Anki (`media/LayerMedia/`) via a symlink set up by ATL.
+
+```markdown
+Q: Question text here
+A: Answer text here
+E: Extra information (optional)
+M: Content behind "more" button (optional)
+
+---
+
+T: Text with {{c1::cloze deletions}}.
+
+---
+
+And so on…
+```
+
+Push your cards to Anki, study them, make edits in either place, then pull changes back:
+
+```bash
+ankitextlayer init   # Use once per directory, to set up
+ankitextlayer ma     # Markdown to Anki
+# Review and edit in Anki...
+ankitextlayer am     # Anki to Markdown
+```
+And that's it! Your markdown files and Anki decks stay in sync, giving you the best of both worlds.
+
+---
+
+## Support This Project
+
+If ATL saves you time or makes your workflow better, consider buying me a coffee! 
+
+Your support helps me:
+- Keep the project maintained and bug-free
+- Add new features based on user feedback
+- Respond quickly to issues and questions
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/visserle)
+
+MIT License

ankitextlayer-0.1.0/README.md

@@ -0,0 +1,110 @@
+# AnkiTextLayer (ATL)
+
+Write your decks in Markdown, sync them to Anki for studying, make edits in either place, and sync changes back.
+
+## Why Use This
+
+- **Write in Markdown**: Your cards live in plain text: easy to edit fast, search, refactor, and review in your editor.
+- **Keep full overview**: Browse hundreds of cards in one file, search across decks instantly, and reorganize freely.
+- **Work with AI**: Markdown is a great interface for AI help (drafting, rephrasing, generating variants) while you stay in control of the final wording.
+- **Version control**: Track exactly what changed and when, roll back safely, and collaborate using Git like any other text-based project.
+
+If you already love Anki for studying, ATL just upgrades how you create and maintain your cards.
+
+## How It Works
+
+In a directory of your choice, each Markdown file represents an Anki deck. On first sync, ATL assigns HTML comment IDs to each card for tracking. After that, it knows what's new, changed, moved between decks, or deleted, and will sync accordingly.
+
+Two note types are provided: `LayerQA` and `LayerCloze`. In a markdown file, each field is represented by a line starting with a specific letter and a colon. `Q:` and `A:` start question and answer fields, `T:` starts a text field for clozes, and `E:` and `M:` start optional extra and "more" fields on the back of the card. Cards are separated by a blank line, three dashes, and another blank line.
+
+A fresh markdown deck could look like this:
+
+```markdown
+Q: What is the capital of France?
+A: Paris.
+E: ![alt text](tour_eiffel.png){width=700}
+
+---
+
+T: The capital of Germany is {{c1::Berlin}}.
+```
+
+With the first ATL sync to Anki, the deck and each card gets a unique ID in an HTML comment:
+
+```markdown
+<!-- deck_id: 1770487991521 -->
+<!-- card_id: 1770487991522 -->
+Q: What is the capital of France?
+A: Paris.
+E: ![alt text](tour_eiffel.png){width=700}
+
+---
+
+<!-- note_id: 1770487991521 -->
+T: The capital of Germany is {{c1::Berlin}}.
+```
+
+ATL only acts on the provided note types, so your existing collection is never affected. You can mix managed and unmanaged cards in the same deck without issues.
+
+Before every ATL sync, it automatically creates a Git commit so you can always roll back if something breaks.
+
+## How to Get Started
+
+Install via [pipx](https://github.com/pypa/pipx):
+```bash
+pipx install ankitextlayer
+```
+Make sure Anki is running, with the [AnkiConnect add-on](https://ankiweb.net/shared/info/2055492159) enabled. Then initialize ATL in any directory (not your Anki data folder):
+
+```bash
+ankitextlayer init --tutorial
+```
+The tutorial flag creates a sample markdown deck with further information. We can import it into Anki using:
+```bash
+ankitextlayer ma
+```
+Where `ma` is shorthand for `markdown-to-anki`. Conversely, there is `ankitextlayer am` for `anki-to-markdown`. The tutorial deck should provide you with a good starting point to explore the features of ATL.
+
+## Workflow
+
+Start by writing your cards in Markdown. Images can be added by pasting them directly into your markdown file in VS Code as explained in the tutorial. When you ATL sync to Anki, the images are saved in the media collection of Anki (`media/LayerMedia/`) via a symlink set up by ATL.
+
+```markdown
+Q: Question text here
+A: Answer text here
+E: Extra information (optional)
+M: Content behind "more" button (optional)
+
+---
+
+T: Text with {{c1::cloze deletions}}.
+
+---
+
+And so on…
+```
+
+Push your cards to Anki, study them, make edits in either place, then pull changes back:
+
+```bash
+ankitextlayer init   # Use once per directory, to set up
+ankitextlayer ma     # Markdown to Anki
+# Review and edit in Anki...
+ankitextlayer am     # Anki to Markdown
+```
+And that's it! Your markdown files and Anki decks stay in sync, giving you the best of both worlds.
+
+---
+
+## Support This Project
+
+If ATL saves you time or makes your workflow better, consider buying me a coffee! 
+
+Your support helps me:
+- Keep the project maintained and bug-free
+- Add new features based on user feedback
+- Respond quickly to issues and questions
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/visserle)
+
+MIT License

ankitextlayer-0.1.0/ankitextlayer/__init__.py

@@ -0,0 +1,6 @@
+"""AnkiTextLayer – bidirectional sync between Anki and Markdown."""
+
+from ankitextlayer.cli import main
+
+__version__ = "0.1.0"
+__all__ = ["main", "__version__"]

ankitextlayer-0.1.0/ankitextlayer/anki_client.py

@@ -0,0 +1,32 @@
+"""Shared AnkiConnect client and helpers used by both import/export scripts."""
+
+import re
+from typing import Any
+
+import requests
+
+from ankitextlayer.config import ANKI_CONNECT_URL
+
+
+def invoke(action: str, **params) -> Any:
+    """Send a request to AnkiConnect and return the result.
+
+    Raises an Exception when AnkiConnect returns an error.
+    """
+    response = requests.post(
+        ANKI_CONNECT_URL,
+        json={"action": action, "version": 6, "params": params},
+        timeout=10,
+    )
+    result = response.json()
+    if result.get("error"):
+        raise Exception(f"AnkiConnect error: {result['error']}")
+    return result["result"]
+
+
+def extract_deck_id(content: str) -> tuple[int | None, str]:
+    """Extract deck_id from the first line and return (deck_id, remaining content)."""
+    match = re.match(r"<!--\s*deck_id:\s*(\d+)\s*-->\n?", content)
+    if match:
+        return int(match.group(1)), content[match.end() :]
+    return None, content

ankitextlayer-0.1.0/ankitextlayer/anki_to_markdown.py

@@ -0,0 +1,350 @@
+"""Transcribe Anki decks to Markdown files."""
+
+import logging
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ankitextlayer.anki_client import extract_deck_id, invoke
+from ankitextlayer.config import CARD_SEPARATOR, SUPPORTED_NOTE_TYPES
+from ankitextlayer.html_converter import HTMLToMarkdown
+from ankitextlayer.markdown_helpers import (
+    extract_card_blocks,
+    format_card,
+    sanitize_filename,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DeckExportResult:
+    """Result of exporting a single deck."""
+
+    deck_name: str
+    file_path: Path | None
+    total_cards: int
+    updated: int
+    created: int
+    deleted: int
+    skipped: int
+    # Block IDs (e.g. "card_id: 123") that appeared/disappeared
+    # compared to the previous file, used for cross-deck move detection.
+    created_ids: set[str] | None = None
+    deleted_ids: set[str] | None = None
+
+
+def transcribe_deck(
+    deck_name: str, output_dir: str = ".", deck_id: int | None = None
+) -> DeckExportResult:
+    """Transcribe an Anki deck to a Markdown file (excluding subdecks)."""
+    converter = HTMLToMarkdown()
+    # Collect (note_id, formatted_block) tuples.
+    # In Anki the note ID is the creation timestamp in milliseconds.
+    blocks_with_ids: list[tuple[int, str]] = []
+
+    # --- LayerQA: one block per card ---
+    qa_query = f'deck:"{deck_name}" -deck:"{deck_name}::*" note:LayerQA'
+    qa_card_ids = invoke("findCards", query=qa_query)
+
+    if qa_card_ids:
+        qa_cards_info = invoke("cardsInfo", cards=qa_card_ids)
+        qa_note_ids = list({card["note"] for card in qa_cards_info})
+        qa_notes_info = invoke("notesInfo", notes=qa_note_ids)
+        qa_note_dict = {note["noteId"]: note for note in qa_notes_info}
+
+        for card in qa_cards_info:
+            blocks_with_ids.append(
+                (
+                    card["note"],
+                    format_card(
+                        card["cardId"],
+                        qa_note_dict[card["note"]],
+                        converter,
+                        note_type="LayerQA",
+                    ),
+                )
+            )
+
+    # --- LayerCloze: one block per note (deduplicated) ---
+    cloze_query = f'deck:"{deck_name}" -deck:"{deck_name}::*" note:LayerCloze'
+    cloze_card_ids = invoke("findCards", query=cloze_query)
+
+    if cloze_card_ids:
+        cloze_cards_info = invoke("cardsInfo", cards=cloze_card_ids)
+        cloze_note_ids = list({card["note"] for card in cloze_cards_info})
+        cloze_notes_info = invoke("notesInfo", notes=cloze_note_ids)
+
+        for note in cloze_notes_info:
+            blocks_with_ids.append(
+                (
+                    note["noteId"],
+                    format_card(
+                        note["noteId"],
+                        note,
+                        converter,
+                        note_type="LayerCloze",
+                    ),
+                )
+            )
+
+    # Build a lookup from block ID string to (note_id, formatted_block)
+    block_by_id: dict[str, tuple[int, str]] = {}
+    for note_id, block in blocks_with_ids:
+        match = re.match(r"<!--\s*((?:card_id|note_id):\s*\d+)\s*-->", block)
+        if match:
+            key = re.sub(r"\s+", " ", match.group(1))
+            block_by_id[key] = (note_id, block)
+
+    if not blocks_with_ids:
+        return DeckExportResult(
+            deck_name=deck_name,
+            file_path=None,
+            total_cards=0,
+            updated=0,
+            created=0,
+            deleted=0,
+            skipped=0,
+        )
+
+    output_path = Path(output_dir) / (sanitize_filename(deck_name) + ".md")
+    deck_id_line = "<!-- deck_id: {} -->".format(deck_id) + "\n" if deck_id else ""
+
+    # Compare with existing file to determine per-card changes
+    updated = 0
+    created = 0
+    deleted = 0
+    skipped = 0
+    created_ids: set[str] = set()
+    deleted_ids: set[str] = set()
+
+    old_content = (
+        output_path.read_text(encoding="utf-8") if output_path.exists() else None
+    )
+
+    if old_content is not None:
+        existing_blocks = extract_card_blocks(old_content)
+
+        # Preserve existing file order; append new cards sorted by creation date.
+        new_block_ids = set(block_by_id.keys())
+        ordered_blocks: list[str] = []
+
+        # Keep existing cards in their current order, updating content
+        for block_id in existing_blocks:
+            if block_id in block_by_id:
+                _, block = block_by_id[block_id]
+                ordered_blocks.append(block)
+                if existing_blocks[block_id] == block:
+                    skipped += 1
+                else:
+                    updated += 1
+            else:
+                deleted += 1
+                deleted_ids.add(block_id)
+
+        # Append genuinely new cards, sorted by creation date among themselves
+        new_ids = new_block_ids - set(existing_blocks)
+        new_entries = sorted(
+            ((bid, *block_by_id[bid]) for bid in new_ids),
+            key=lambda x: x[1],  # sort by note_id (creation timestamp)
+        )
+        for bid, _, block in new_entries:
+            ordered_blocks.append(block)
+            created += 1
+            created_ids.add(bid)
+
+        markdown_blocks = ordered_blocks
+    else:
+        # First export for this deck: sort by creation date (chronological).
+        blocks_with_ids.sort(key=lambda x: x[0])
+        markdown_blocks = [block for _, block in blocks_with_ids]
+        created = len(markdown_blocks)
+
+    cards_content = CARD_SEPARATOR.join(markdown_blocks)
+    new_content = deck_id_line + cards_content
+
+    # Only write if content actually changed
+    if old_content != new_content:
+        output_path.write_text(new_content, encoding="utf-8")
+
+    logger.debug(f"{deck_name}: {len(markdown_blocks)} blocks -> {output_path.name}")
+    return DeckExportResult(
+        deck_name=deck_name,
+        file_path=output_path,
+        total_cards=len(markdown_blocks),
+        updated=updated,
+        created=created,
+        deleted=deleted,
+        skipped=skipped,
+        created_ids=created_ids,
+        deleted_ids=deleted_ids,
+    )
+
+
+def _find_relevant_decks() -> set[str]:
+    """Return deck names that contain LayerQA or LayerCloze notes."""
+    query = " OR ".join(f"note:{nt}" for nt in SUPPORTED_NOTE_TYPES)
+    card_ids = invoke("findCards", query=query)
+    if not card_ids:
+        return set()
+    cards_info = invoke("cardsInfo", cards=card_ids)
+    return {card["deckName"] for card in cards_info}
+
+
+def transcribe_collection(output_dir: str = ".") -> list[DeckExportResult]:
+    """Transcribe all decks in the collection to Markdown files."""
+    deck_names_and_ids = invoke("deckNamesAndIds")
+    relevant_decks = _find_relevant_decks()
+    logger.info(
+        f"Found {len(deck_names_and_ids)} decks, "
+        f"{len(relevant_decks)} with supported note types"
+    )
+
+    # Also include decks that have existing markdown files (they may
+    # have become empty after cards moved out and need updating).
+    output_path = Path(output_dir)
+    id_to_name = {v: k for k, v in deck_names_and_ids.items()}
+    for md_file in output_path.glob("*.md"):
+        content = md_file.read_text(encoding="utf-8")
+        deck_id, _ = extract_deck_id(content)
+        if deck_id and deck_id in id_to_name:
+            relevant_decks.add(id_to_name[deck_id])
+
+    results = []
+    for deck_name in sorted(deck_names_and_ids):
+        if deck_name not in relevant_decks:
+            continue
+        deck_id = deck_names_and_ids[deck_name]
+        logger.info(f"Processing {deck_name} (id: {deck_id})...")
+        result = transcribe_deck(deck_name, output_dir, deck_id=deck_id)
+        if result.file_path:
+            results.append(result)
+
+        if result.total_cards > 0:
+            logger.info(
+                f"  Updated: {result.updated}, Created: {result.created}, "
+                f"Deleted: {result.deleted}, Skipped: {result.skipped}"
+            )
+
+    # Check for cross-deck moves: a card/note ID that disappeared from
+    # one file and appeared in another was moved between decks in Anki.
+    all_created_ids: set[str] = set()
+    all_deleted_ids: set[str] = set()
+    for r in results:
+        all_created_ids.update(r.created_ids or set())
+        all_deleted_ids.update(r.deleted_ids or set())
+    moved = len(all_created_ids & all_deleted_ids)
+    if moved:
+        logger.info(
+            f"  Note: {moved} of the above created/deleted card(s) were "
+            f"moved between decks (review history is preserved)"
+        )
+
+    return results
+
+
+def rename_markdown_files(output_dir: str = ".") -> int:
+    """Rename markdown files to match their Anki deck name via deck_id.
+
+    If a deck was renamed in Anki, the corresponding markdown file is
+    renamed to reflect the new deck name.  The deck_id inside the file
+    is used to link the file to its deck.
+    Returns the number of renamed files.
+    """
+    deck_names_and_ids = invoke("deckNamesAndIds")
+    id_to_name = {v: k for k, v in deck_names_and_ids.items()}
+    renamed = 0
+
+    for md_file in Path(output_dir).glob("*.md"):
+        content = md_file.read_text(encoding="utf-8")
+        deck_id, _ = extract_deck_id(content)
+        if deck_id is None or deck_id not in id_to_name:
+            continue
+
+        expected_filename = sanitize_filename(id_to_name[deck_id]) + ".md"
+        if md_file.name != expected_filename:
+            new_path = md_file.parent / expected_filename
+            logger.info(f"  Renamed {md_file.name} -> {expected_filename}")
+            md_file.rename(new_path)
+            renamed += 1
+
+    return renamed
+
+
+def delete_orphaned_decks(output_dir: str = ".") -> int:
+    """Delete markdown files whose deck_id is not found in Anki.
+
+    Files without a deck_id are kept (they are likely new decks pending first sync).
+    Returns the number of deleted files.
+    """
+    anki_deck_ids = set(invoke("deckNamesAndIds").values())
+    deleted = 0
+
+    for md_file in Path(output_dir).glob("*.md"):
+        content = md_file.read_text(encoding="utf-8")
+        deck_id, _ = extract_deck_id(content)
+        if deck_id is not None and deck_id not in anki_deck_ids:
+            logger.info(
+                f"  Deleting orphaned deck file {md_file.name} (deck_id: {deck_id})"
+            )
+            md_file.unlink()
+            deleted += 1
+
+    return deleted
+
+
+def delete_orphaned_cards(output_dir: str = ".") -> int:
+    """Delete cards/notes from markdown files whose IDs are not found in Anki.
+
+    Cards without an ID are kept (they are new cards pending first sync).
+    Returns the total number of deleted blocks.
+    """
+    anki_card_ids = set(invoke("findCards", query="deck:*"))
+    # Get all note IDs for note_id-based blocks (LayerCloze)
+    anki_note_ids: set[int] = set()
+    for note_type in SUPPORTED_NOTE_TYPES:
+        note_ids = invoke("findNotes", query=f"note:{note_type}")
+        anki_note_ids.update(note_ids)
+
+    total_deleted = 0
+
+    for md_file in Path(output_dir).glob("*.md"):
+        content = md_file.read_text(encoding="utf-8")
+        deck_id_line_match = re.match(r"(<!--\s*deck_id:\s*\d+\s*-->\n?)", content)
+        deck_id_prefix = deck_id_line_match.group(1) if deck_id_line_match else ""
+        _, cards_content = extract_deck_id(content)
+
+        blocks = cards_content.split(CARD_SEPARATOR)
+        kept: list[str] = []
+        deleted = 0
+
+        for block in blocks:
+            stripped = block.strip()
+            if not stripped:
+                continue
+
+            card_match = re.match(r"<!--\s*card_id:\s*(\d+)\s*-->", stripped)
+            if card_match:
+                card_id = int(card_match.group(1))
+                if card_id not in anki_card_ids:
+                    deleted += 1
+                    logger.info(f"  Deleting card {card_id} from {md_file.name}")
+                    continue
+
+            note_match = re.match(r"<!--\s*note_id:\s*(\d+)\s*-->", stripped)
+            if note_match:
+                note_id = int(note_match.group(1))
+                if note_id not in anki_note_ids:
+                    deleted += 1
+                    logger.info(f"  Deleting note {note_id} from {md_file.name}")
+                    continue
+
+            kept.append(stripped)
+
+        if deleted > 0:
+            new_content = deck_id_prefix + CARD_SEPARATOR.join(kept)
+            md_file.write_text(new_content, encoding="utf-8")
+            logger.info(f"{md_file.name}: deleted {deleted} orphaned block(s)")
+            total_deleted += deleted
+
+    return total_deleted