anki-toolkit 0.1.0

A comprehensive toolkit for working with Anki decks

Anki Toolkit

A comprehensive Python toolkit for working with Anki decks. This toolkit provides powerful tools for APKG file handling, card processing, audio downloading, and more.

Features

• APKG File Handling: Extract, read, and save Anki deck files (.apkg)
• Card Deduplication: Intelligent removal of duplicate cards while preserving learning progress
• Audio Downloading: Download audio from multiple sources (Youdao, Baidu, Google TTS, Dictionary.com)
• Card Format Transformation: Transform cards to listening mode (audio → word/meaning)
• GUID Generation: Generate fixed GUIDs for Anki cards
• Easy to Use: Simple and intuitive API

Installation

From PyPI

pip install anki-toolkit

From Source

git clone https://github.com/yourusername/anki-toolkit.git
cd anki-toolkit
pip install -e .

Quick Start

Basic Usage

from anki_toolkit import APKGHandler, AudioDownloader, CardProcessor

# Initialize handler
handler = APKGHandler("input.apkg")

# Extract APKG file
media_map = handler.extract()

# Read cards
cards = handler.read_cards()
print(f"Found {len(cards)} cards")

# Initialize audio downloader
audio_downloader = AudioDownloader("/path/to/audio/dir")

# Initialize card processor
processor = CardProcessor(
    audio_downloader=audio_downloader,
    extract_dir=handler.extract_dir,
    media_map=handler.media_map
)

# Remove duplicates
cards = processor.remove_duplicates(cards)
print(f"After deduplication: {len(cards)} cards")

# Transform card format (add audio)
for i, card in enumerate(cards):
    cards[i] = processor.transform_card_format(card)

# Shuffle cards
cards = processor.shuffle_cards(cards)

# Save to new APKG
handler.save_cards_to_apkg(cards, "output.apkg")

# Cleanup
handler.cleanup()

Download Audio

from anki_toolkit import AudioDownloader

# Initialize downloader
downloader = AudioDownloader("/path/to/save/dir")

# Download audio for a word
audio_path = downloader.download("hello")
if audio_path:
    print(f"Audio saved to: {audio_path}")

# Find local audio file
local_audio = downloader.get_local_audio("hello", ["/path/to/audio/dir"])
if local_audio:
    print(f"Found local audio: {local_audio}")

Generate GUID

from anki_toolkit import generate_note_guid

# Generate GUID for a card
guid = generate_note_guid("vocabulary", "hello")
print(f"GUID: {guid}")

API Reference

APKGHandler

Handle Anki APKG file operations.

Constructor

APKGHandler(apkg_path: str)

Methods

• extract(extract_dir: Optional[str] = None) -> Dict[str, str]: Extract APKG file
• read_cards() -> List[Dict[str, Any]]: Read cards from extracted APKG
• save_cards_to_apkg(cards: List[Dict[str, Any]], output_path: str, audio_resource_dir: Optional[str] = None) -> int: Save cards to new APKG
• cleanup(): Clean up temporary extraction directory

AudioDownloader

Download audio files from multiple online sources.

Constructor

AudioDownloader(save_dir: str)

Methods

• download(word: str) -> Optional[str]: Download audio for a word
• get_local_audio(word: str, audio_dirs: Optional[List[str]] = None) -> Optional[str]: Find local audio file

CardProcessor

Process and transform Anki cards.

Constructor

CardProcessor(audio_downloader=None, extract_dir: str = '', media_map: dict = None)

Methods

• remove_duplicates(cards: List[Dict[str, Any]]) -> List[Dict[str, Any]]: Remove duplicate cards
• transform_card_format(card: Dict[str, Any]) -> Dict[str, Any]: Transform card format
• shuffle_cards(cards: List[Dict[str, Any]]) -> List[Dict[str, Any]]: Randomly shuffle cards

Utility Functions

• generate_note_guid(prefix: str, content: str) -> int: Generate a fixed note GUID
• format_time(seconds: int) -> str: Format seconds into human-readable time
• validate_apkg_path(path: str) -> bool: Validate if path is a valid APKG file

Use Cases

1. Deck Cleanup

Remove duplicate cards and organize your Anki decks:

from anki_toolkit import APKGHandler, CardProcessor

handler = APKGHandler("my_deck.apkg")
handler.extract()
cards = handler.read_cards()

processor = CardProcessor()
cards = processor.remove_duplicates(cards)
cards = processor.shuffle_cards(cards)

handler.save_cards_to_apkg(cards, "my_deck_cleaned.apkg")
handler.cleanup()

2. Add Audio to Cards

Automatically download and add audio to your vocabulary cards:

from anki_toolkit import APKGHandler, AudioDownloader, CardProcessor

handler = APKGHandler("vocabulary.apkg")
handler.extract()
cards = handler.read_cards()

audio_downloader = AudioDownloader("./audio")
processor = CardProcessor(
    audio_downloader=audio_downloader,
    extract_dir=handler.extract_dir,
    media_map=handler.media_map
)

for i, card in enumerate(cards):
    cards[i] = processor.transform_card_format(card)

handler.save_cards_to_apkg(cards, "vocabulary_with_audio.apkg")
handler.cleanup()

3. Batch Processing

Process multiple APKG files:

import os
from anki_toolkit import APKGHandler, CardProcessor

apkg_files = ["deck1.apkg", "deck2.apkg", "deck3.apkg"]

for apkg_file in apkg_files:
    handler = APKGHandler(apkg_file)
    handler.extract()
    cards = handler.read_cards()
    
    processor = CardProcessor()
    cards = processor.remove_duplicates(cards)
    
    output_file = f"cleaned_{os.path.basename(apkg_file)}"
    handler.save_cards_to_apkg(cards, output_file)
    handler.cleanup()
    
    print(f"Processed: {apkg_file} -> {output_file}")

Requirements

• Python 3.7+
• requests >= 2.25.0

Development

Setup Development Environment

git clone https://github.com/yourusername/anki-toolkit.git
cd anki-toolkit
pip install -e ".[dev]"

Run Tests

pytest tests/

Format Code

black anki_toolkit/

Lint Code

flake8 anki_toolkit/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the need for better Anki deck management tools
• Thanks to the Anki community for their feedback and suggestions

Changelog

Version 0.1.0 (2024-01-XX)

• Initial release
• APKG file handling
• Card deduplication
• Audio downloading from multiple sources
• Card format transformation
• GUID generation

Support

If you encounter any issues or have questions, please open an issue on GitHub.