Metadata-Version: 2.4
Name: anki-yaml-sync
Version: 0.1.0
Summary: A CLI tool to import/export Anki notes as YAML files
Author-email: Your Name <your.email@example.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: license-file

# Anki YAML Sync

A Python CLI tool for bi-directional syncing of Anki notes as YAML files for easy editing and version control.

## Features

- **Import**: Fetch all notes from Anki and save them as YAML files
- **Export**: Sync edited YAML files back to Anki
- **Flexible**: Update existing notes or create new ones
- **Simple**: Flat file structure, one YAML file per note

## Installation

### Requirements

- Python 3.8+
- Anki with [AnkiConnect](https://github.com/FooSoft/anki-connect) installed

### Setup

1. Fork and clone the repository:
```bash
git clone <repo-url>
cd anki-yaml-sync
```

2. Install the package in development mode:
```bash
pip install -e .
```

This will install the CLI tool `anki-yaml-sync` and all dependencies.

### Development Installation

To install with development dependencies (for testing and linting):

```bash
pip install -e ".[dev]"
```

## Usage

### Import Notes from Anki

Fetch all notes from Anki and save them as YAML files:

```bash
anki-yaml-sync import [--output-dir OUTPUT]
```

Options:
- `--output-dir`, `-o`: Directory to save YAML files (default: `notes`)

Example:
```bash
anki-yaml-sync import --output-dir ./my-notes
```

### Export Notes to Anki

Sync YAML files back to Anki:

```bash
anki-yaml-sync export [--input-dir INPUT] [--deck DECK]
```

Options:
- `--input-dir`, `-i`: Directory containing YAML files (default: `notes`)
- `--deck`: Deck to add new notes to (default: `Default`)

Example:
```bash
anki-yaml-sync export --input-dir ./my-notes --deck "My Deck"
```

### Verbose Output

Add `-v` or `--verbose` flag to any command for detailed logging:

```bash
anki-yaml-sync -v import
anki-yaml-sync -v export
```

## YAML Format

Each note is stored as a separate YAML file. Example:

```yaml
id: 1234567890
type: Basic
tags:
  - french
  - vocabulary
fields:
  Front: Bonjour
  Back: Hello
created: 2024-02-12T10:30:00
modified: 2024-02-12T10:30:00
```

**Fields:**
- `id`: Anki note ID (required for updates)
- `type`: Note type name (e.g., "Basic", "Cloze")
- `tags`: List of tags to apply
- `fields`: Dictionary of field names to field values
- `created`: Creation timestamp
- `modified`: LastModification timestamp

## Workflow

1. **Initial Import**: Run `anki-yaml-sync import` to create YAML files from your Anki collection
2. **Edit**: Open and edit the YAML files with your text editor or IDE
3. **Sync Back**: Run `anki-yaml-sync export` to sync your changes back to Anki

### Updating Existing Notes

If a YAML file has an `id` field that matches an existing Anki note, the export will update that note. Fields are completely replaced (not merged).

### Creating New Notes

To create a new card:
1. Create a new YAML file with a temporary or missing `id` (e.g., `0` or `null`)
2. Run `anki-yaml-sync export`
3. The YAML file will be automatically updated with the assigned note ID

## Requirements

- **Anki**: Running instance of Anki desktop
- **AnkiConnect**: Must be installed and running on `localhost:8765` (default)

To set up AnkiConnect (https://ankiweb.net/shared/info/2055492159):
1. Open Anki > Menu Bar > Tools > Add-ons > Get Add-ons
2. Enter the code `2055492159` and click "OK" to install AnkiConnect
3. Restart Anki

## Testing

Run tests with pytest:

```bash
source venv/bin/activate && pytest
```

With coverage:

```bash
source venv/bin/activate && pytest --cov=anki_sync
```

## Troubleshooting

### "Could not connect to Anki Connect"

- Ensure Anki is running
- Verify AnkiConnect is installed (Tools → Add-ons in Anki)
- Check that AnkiConnect is listening on `localhost:8765`

### "Model not found"

- Ensure the note type (model) name matches exactly in Anki
- Check spelling and capitalization

### YAML parsing errors

- Ensure YAML syntax is valid
- Use proper indentation (spaces, not tabs)
- Quote special characters in strings if needed

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.
