Add Anki flashcard generator for Warsaw districts using real OpenStreetMap boundaries (#1)

* Initial plan

* Add Warsaw districts Anki generator with tests and documentation

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

* Apply pre-commit formatting fixes

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

* Address code review feedback: remove unused code and fix imports

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

* Address PR feedback: use genanki for self-contained .apkg, fix tests, update README

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

* Use real Warsaw district boundaries from OpenStreetMap instead of mock circles

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

python_pkg/warsaw_districts/README.md

@@ -0,0 +1,115 @@
+# Warsaw Districts Anki Generator
+
+Generate Anki flashcards for learning the 18 districts (dzielnice) of Warsaw, Poland.
+
+## Features
+
+- Generates flashcards for all 18 Warsaw districts
+- **Uses real district boundaries from OpenStreetMap data**
+- Front of card: Map showing the full city with only the target district's border highlighted in bold
+- Back of card: District name in Polish
+- Self-contained .apkg file with embedded images
+- Compatible with AnkiWeb and AnkiDroid
+
+## Data Source
+
+District boundaries are sourced from [andilabs/warszawa-dzielnice-geojson](https://github.com/andilabs/warszawa-dzielnice-geojson), which provides accurate OpenStreetMap-based GeoJSON data for all Warsaw districts.
+
+## Installation
+
+Install dependencies using your preferred method:
+
+### Using pyenv (recommended)
+```bash
+pyenv install 3.10  # or later
+pyenv shell 3.10
+pip install matplotlib genanki geopandas
+```
+
+### Using pipx
+```bash
+pipx install --python python3.10 matplotlib genanki geopandas
+```
+
+### Using system package manager (Arch Linux)
+```bash
+sudo pacman -S python-matplotlib python-geopandas
+pip install genanki
+```
+
+### Using pip directly
+```bash
+pip install matplotlib genanki geopandas
+```
+
+## Usage
+
+### Generate flashcards
+
+```bash
+# From the repository root
+python -m python_pkg.warsaw_districts.warsaw_districts_anki
+```
+
+This creates:
+- `warsaw_districts.apkg` - Self-contained Anki package with all images embedded
+
+### Custom options
+
+```bash
+# Custom output file
+python -m python_pkg.warsaw_districts.warsaw_districts_anki --output my_cards.apkg
+
+# Custom deck name
+python -m python_pkg.warsaw_districts.warsaw_districts_anki --deck-name "Warszawa - Dzielnice"
+```
+
+## Importing into Anki
+
+1. Open Anki
+2. File → Import
+3. Select the generated `warsaw_districts.apkg` file
+4. Click Import
+
+That's it! All images are already embedded in the .apkg file.
+
+## Warsaw Districts
+
+The generator includes all 18 official districts of Warsaw:
+
+1. Bemowo
+2. Białołęka
+3. Bielany
+4. Mokotów
+5. Ochota
+6. Praga-Południe
+7. Praga-Północ
+8. Rembertów
+9. Śródmieście
+10. Targówek
+11. Ursus
+12. Ursynów
+13. Wawer
+14. Wesoła
+15. Wilanów
+16. Włochy
+17. Wola
+18. Żoliborz
+
+## Development
+
+### Running tests
+
+```bash
+pytest python_pkg/warsaw_districts/tests/
+```
+
+### Code quality
+
+```bash
+ruff check python_pkg/warsaw_districts/
+```
+
+## License
+
+Same as the parent repository.

python_pkg/warsaw_districts/__init__.py

@@ -0,0 +1,5 @@
+"""Warsaw districts Anki flashcard generator."""
+
+from __future__ import annotations
+
+__all__ = ["generate_anki_deck", "main"]

python_pkg/warsaw_districts/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Tests init file."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

python_pkg/warsaw_districts/tests/test_warsaw_districts_anki.py

@@ -0,0 +1,175 @@
+"""Tests for the Warsaw districts Anki generator."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import pytest
+
+try:
+    from python_pkg.warsaw_districts.warsaw_districts_anki import (
+        WARSAW_DISTRICTS,
+        create_district_map,
+        generate_anki_package,
+        generate_district_image_bytes,
+        main,
+    )
+except ImportError:
+    import sys
+
+    sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+    from python_pkg.warsaw_districts.warsaw_districts_anki import (
+        WARSAW_DISTRICTS,
+        create_district_map,
+        generate_anki_package,
+        generate_district_image_bytes,
+        main,
+    )
+
+
+class TestDistricts:
+    """Tests for Warsaw districts data."""
+
+    def test_has_18_districts(self) -> None:
+        """Test that we have exactly 18 Warsaw districts."""
+        assert len(WARSAW_DISTRICTS) == 18
+
+    def test_all_districts_are_strings(self) -> None:
+        """Test that all district entries are strings."""
+        for district in WARSAW_DISTRICTS:
+            assert isinstance(district, str)
+            assert len(district) > 0
+
+    def test_districts_are_unique(self) -> None:
+        """Test that all district names are unique."""
+        assert len(WARSAW_DISTRICTS) == len(set(WARSAW_DISTRICTS))
+
+    def test_known_districts_present(self) -> None:
+        """Test that all known Warsaw districts are in the list."""
+        district_set = set(WARSAW_DISTRICTS)
+        # Check all 18 districts
+        expected_districts = {
+            "Bemowo",
+            "Białołęka",
+            "Bielany",
+            "Mokotów",
+            "Ochota",
+            "Praga Południe",  # Note: space, not hyphen
+            "Praga Północ",     # Note: space, not hyphen
+            "Rembertów",
+            "Śródmieście",
+            "Targówek",
+            "Ursus",
+            "Ursynów",
+            "Wawer",
+            "Wesoła",
+            "Wilanów",
+            "Włochy",
+            "Wola",
+            "Żoliborz",
+        }
+        assert district_set == expected_districts
+
+
+class TestCreateDistrictMap:
+    """Tests for creating district maps."""
+
+    def test_creates_figure(self) -> None:
+        """Test that create_district_map returns a Figure."""
+        district = WARSAW_DISTRICTS[0]
+        fig = create_district_map(district)
+        assert fig is not None
+        # Clean up
+        plt.close(fig)
+
+    def test_creates_figure_for_all_districts(self) -> None:
+        """Test that we can create maps for all districts."""
+        for district in WARSAW_DISTRICTS:
+            fig = create_district_map(district)
+            assert fig is not None
+            plt.close(fig)
+
+
+class TestGenerateDistrictImageBytes:
+    """Tests for generating district image bytes."""
+
+    def test_generates_bytes(self) -> None:
+        """Test that generate_district_image_bytes returns bytes."""
+        district = WARSAW_DISTRICTS[0]
+        image_bytes = generate_district_image_bytes(district)
+        assert isinstance(image_bytes, bytes)
+        assert len(image_bytes) > 0
+
+    def test_generates_for_all_districts(self) -> None:
+        """Test that we can generate images for all districts."""
+        for district in WARSAW_DISTRICTS:
+            image_bytes = generate_district_image_bytes(district)
+            assert isinstance(image_bytes, bytes)
+            assert len(image_bytes) > 0
+
+
+class TestGenerateAnkiPackage:
+    """Tests for generating Anki package."""
+
+    def test_generates_package(self) -> None:
+        """Test that output is a genanki Package."""
+        package = generate_anki_package("Test Deck")
+        assert package is not None
+        assert len(package.decks) == 1
+
+    def test_generates_notes_for_all_districts(self) -> None:
+        """Test that package contains cards for all 18 districts."""
+        package = generate_anki_package()
+        deck = package.decks[0]
+        assert len(deck.notes) == len(WARSAW_DISTRICTS)
+
+    def test_custom_deck_name(self) -> None:
+        """Test that custom deck name is used."""
+        package = generate_anki_package("Custom Deck")
+        deck = package.decks[0]
+        assert deck.name == "Custom Deck"
+
+
+class TestMain:
+    """Tests for the main CLI function."""
+
+    def test_creates_output_file(self, tmp_path: Path) -> None:
+        """Test that main creates the output file."""
+        output_file = tmp_path / "test_output.apkg"
+
+        result = main(
+            [
+                "--output",
+                str(output_file),
+            ]
+        )
+
+        assert result == 0
+        assert output_file.exists()
+
+    def test_custom_deck_name(self, tmp_path: Path) -> None:
+        """Test that custom deck name is used."""
+        output_file = tmp_path / "test_output.apkg"
+
+        result = main(
+            [
+                "--output",
+                str(output_file),
+                "--deck-name",
+                "Custom Deck",
+            ]
+        )
+
+        assert result == 0
+        assert output_file.exists()
+
+    def test_help_flag(self) -> None:
+        """Test that --help works."""
+        with pytest.raises(SystemExit) as exc_info:
+            main(["--help"])
+        assert exc_info.value.code == 0
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

python_pkg/warsaw_districts/warsaw_districts_anki.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""Anki flashcard generator for Warsaw districts.
+
+Generates Anki-compatible flashcard decks with maps showing individual
+Warsaw districts (dzielnice) with their borders using real boundary data
+from OpenStreetMap.
+
+Usage:
+    # Generate Anki cards for all Warsaw districts
+    python -m python_pkg.warsaw_districts.warsaw_districts_anki
+
+    # Specify custom output file
+    python -m python_pkg.warsaw_districts.warsaw_districts_anki --output warsaw.apkg
+
+Output:
+    Creates a self-contained .apkg file that can be directly imported into Anki.
+    The file includes all images embedded, so no manual file copying is needed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+from io import BytesIO
+from pathlib import Path
+import random
+import sys
+from typing import TYPE_CHECKING
+
+import genanki
+import geopandas as gpd
+import matplotlib.pyplot as plt
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from matplotlib.figure import Figure
+
+
+# Path to GeoJSON file with Warsaw district boundaries
+GEOJSON_PATH = Path(__file__).parent / "warszawa-dzielnice.geojson"
+
+
+def load_district_data() -> gpd.GeoDataFrame:
+    """Load Warsaw district boundaries from GeoJSON.
+
+    Returns:
+        GeoDataFrame with district boundaries.
+    """
+    if not GEOJSON_PATH.exists():
+        msg = f"GeoJSON file not found at {GEOJSON_PATH}"
+        raise FileNotFoundError(msg)
+
+    gdf = gpd.read_file(GEOJSON_PATH)
+    # Filter out the "Warszawa" entry (whole city) and keep only districts
+    return gdf[gdf["name"] != "Warszawa"].copy()
+
+
+def get_district_names() -> list[str]:
+    """Get list of all district names from GeoJSON data.
+
+    Returns:
+        Sorted list of district names.
+    """
+    gdf = load_district_data()
+    return sorted(gdf["name"].tolist())
+
+
+# Load district names from actual data
+WARSAW_DISTRICTS = get_district_names()
+
+
+def create_district_map(district_name: str) -> Figure:
+    """Create a map showing Warsaw districts with one district highlighted.
+
+    Args:
+        district_name: Name of the district to highlight.
+
+    Returns:
+        A matplotlib Figure object.
+    """
+    # Load all district data
+    gdf = load_district_data()
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=(10, 10))
+    ax.set_aspect("equal")
+    ax.axis("off")
+
+    # Plot all districts with light gray borders
+    gdf.boundary.plot(ax=ax, color="lightgray", linewidth=0.5, alpha=0.5)
+
+    # Find and highlight the target district
+    target = gdf[gdf["name"] == district_name]
+    if len(target) == 0:
+        msg = f"District {district_name} not found in data"
+        raise ValueError(msg)
+
+    # Plot the highlighted district with bold black border
+    target.boundary.plot(ax=ax, color="black", linewidth=3)
+
+    # Set tight layout
+    ax.set_xlim(gdf.total_bounds[0], gdf.total_bounds[2])
+    ax.set_ylim(gdf.total_bounds[1], gdf.total_bounds[3])
+
+    return fig
+
+
+def generate_district_image_bytes(district_name: str) -> bytes:
+    """Generate a district map image as bytes.
+
+    Args:
+        district_name: Name of the district to visualize.
+
+    Returns:
+        PNG image data as bytes.
+    """
+    fig = create_district_map(district_name)
+
+    # Save to bytes buffer
+    buf = BytesIO()
+    fig.savefig(buf, format="png", bbox_inches="tight", dpi=150)
+    plt.close(fig)
+    buf.seek(0)
+
+    return buf.read()
+
+
+def generate_anki_package(
+    deck_name: str = "Warsaw Districts",
+) -> genanki.Package:
+    """Generate Anki package (.apkg) for Warsaw districts.
+
+    Args:
+        deck_name: Name for the Anki deck.
+
+    Returns:
+        genanki.Package object ready to be written to file.
+    """
+    # Create a unique model ID based on deck name
+    model_id_hash = hashlib.md5(  # noqa: S324
+        f"warsaw_districts_{deck_name}".encode()
+    )
+    model_id = int(model_id_hash.hexdigest()[:8], 16)
+
+    # Define the note model (card template)
+    my_model = genanki.Model(
+        model_id,
+        "Warsaw District Model",
+        fields=[
+            {"name": "DistrictMap"},
+            {"name": "DistrictName"},
+        ],
+        templates=[
+            {
+                "name": "Card 1",
+                "qfmt": "{{DistrictMap}}",
+                "afmt": '{{FrontSide}}<hr id="answer">{{DistrictName}}',
+            },
+        ],
+    )
+
+    # Create a unique deck ID based on deck name
+    deck_id = random.randrange(1 << 30, 1 << 31)  # noqa: S311
+
+    # Create the deck
+    my_deck = genanki.Deck(deck_id, deck_name)
+
+    # Store media files
+    media_files = []
+
+    # Generate notes for each district
+    for district_name in WARSAW_DISTRICTS:
+        # Generate image
+        image_data = generate_district_image_bytes(district_name)
+
+        # Create unique filename
+        filename = f"{district_name.replace(' ', '_').replace('-', '_')}.png"
+
+        # Create note
+        note = genanki.Note(
+            model=my_model,
+            fields=[
+                f'<img src="{filename}">',
+                district_name,
+            ],
+            tags=["geography", "warsaw", "poland"],
+        )
+
+        my_deck.add_note(note)
+
+        # Save image data to temporary file for packaging
+        temp_path = Path(f"/tmp/{filename}")  # noqa: S108
+        temp_path.write_bytes(image_data)
+        media_files.append(str(temp_path))
+
+    # Create package
+    package = genanki.Package(my_deck)
+    package.media_files = media_files
+
+    return package
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main entry point.
+
+    Args:
+        argv: Command line arguments.
+
+    Returns:
+        Exit code.
+    """
+    parser = argparse.ArgumentParser(
+        description="Generate Anki flashcards for Warsaw districts.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        default=None,
+        help="Output file path (default: warsaw_districts.apkg)",
+    )
+    parser.add_argument(
+        "--deck-name",
+        "-d",
+        type=str,
+        default="Warsaw Districts",
+        help="Name for the Anki deck (default: 'Warsaw Districts')",
+    )
+
+    args = parser.parse_args(argv)
+
+    # Determine output path
+    output_path = (
+        Path(args.output) if args.output else Path("warsaw_districts.apkg")
+    )
+
+    try:
+        num_districts = len(WARSAW_DISTRICTS)
+        sys.stdout.write(
+            f"Generating flashcards for {num_districts} Warsaw districts...\n"
+        )
+        sys.stdout.write("Using real district boundaries from OpenStreetMap data.\n")
+
+        # Generate the package
+        package = generate_anki_package(args.deck_name)
+
+        # Write to file
+        package.write_to_file(str(output_path))
+
+        sys.stdout.write("\n")
+        sys.stdout.write("=" * 60 + "\n")
+        sys.stdout.write("FLASHCARD GENERATION COMPLETE\n")
+        sys.stdout.write("=" * 60 + "\n")
+        sys.stdout.write(f"Districts: {num_districts}\n")
+        sys.stdout.write(f"Output file: {output_path.absolute()}\n")
+        sys.stdout.write("\n")
+        sys.stdout.write("To import into Anki:\n")
+        sys.stdout.write("  1. Open Anki\n")
+        sys.stdout.write("  2. File -> Import\n")
+        sys.stdout.write(f"  3. Select: {output_path.absolute()}\n")
+        sys.stdout.write("  4. Click Import\n")
+        sys.stdout.write("\n")
+        sys.stdout.write("All images are embedded in the .apkg file!\n")
+    except (OSError, ValueError) as e:
+        sys.stderr.write(f"Error: {e}\n")
+        return 1
+    else:
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

requirements.txt

@@ -1,10 +1,13 @@
 beautifulsoup4>=4.0
 berserk>=0.13
 bottle>=0.12
+genanki>=0.13
+geopandas>=1.0
 lxml>=5.0
-mitmproxy>=10.0
 
 # Optional dependencies for specific scripts (needed for full pylint analysis)
+matplotlib>=3.0
+mitmproxy>=10.0
 opencv-python>=4.0
 pillow>=10.0
 pygame>=2.0