Metadata-Version: 2.4
Name: anki-toolkit
Version: 0.1.0
Summary: A comprehensive toolkit for working with Anki decks
Home-page: https://github.com/yourusername/anki-toolkit
Author: Your Name
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/anki-toolkit
Project-URL: Documentation, https://github.com/yourusername/anki-toolkit#readme
Project-URL: Repository, https://github.com/yourusername/anki-toolkit
Project-URL: Bug Tracker, https://github.com/yourusername/anki-toolkit/issues
Keywords: anki,flashcard,education,learning,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: twine>=3.4.0; extra == "dev"
Requires-Dist: wheel>=0.36.0; extra == "dev"
Requires-Dist: setuptools>=45.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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

```bash
pip install anki-toolkit
```

### From Source

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

## Quick Start

### Basic Usage

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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:

```python
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:

```python
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:

```python
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

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

### Run Tests

```bash
pytest tests/
```

### Format Code

```bash
black anki_toolkit/
```

### Lint Code

```bash
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](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](https://github.com/yourusername/anki-toolkit/issues) on GitHub.
