kahoot-to-anki 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

kahoot_to_anki/__init__.py

@@ -1 +1 @@
-"""CLI tool to convert Kahoot quiz reports into Anki flashcards."""
+__version__ = "1.2.0"

kahoot_to_anki/cli.py

@@ -0,0 +1,127 @@
+# Standard library imports
+import argparse
+from dataclasses import dataclass
+import logging
+import os
+import glob
+
+from kahoot_to_anki import __version__
+
+
+# Constants
+DEFAULT_INPUT_DIRECTORY = "./data"
+DEFAULT_OUTPUT_DIRECTORY = "./"
+DEFAULT_DECK_TITLE = "Kahoot"
+KAHOOT_EXCEL_SHEET_NAME_RAW_DATA = "RawReportData Data"
+
+# Dataclass to hold CLI arguments
+@dataclass
+class CLIArgs:
+    input_path: str
+    output_path: str
+    sheet: str
+    export_csv: bool
+    deck_title: str
+    
+
+def get_commandline_arguments() -> CLIArgs:
+    """
+    Parses the command line arguments and returns a CLIArgs dataclass instance.
+
+    :return: A CLIArgs dataclass instance
+    :rtype: CLIArgs
+    """
+    parser = argparse.ArgumentParser(description="Create Anki Deck from Kahoot answer")
+    parser.add_argument(
+        "-i",
+        "--inp",
+        default=DEFAULT_INPUT_DIRECTORY,
+        help=f"Path to the directory containing input Excel files or a single input Excel file. If a directory is "
+        f"provided, all Excel files in the directory will be processed. Default: {DEFAULT_INPUT_DIRECTORY}",
+        type=str,
+    )
+    parser.add_argument(
+        "-o",
+        "--out",
+        default=DEFAULT_OUTPUT_DIRECTORY,
+        help="Path to the directory where the Anki flashcards package will be generated. "
+        "If not specified, the package will be created in the current working directory.",
+        type=str,
+    )
+    parser.add_argument(
+        "--sheet",
+        default=KAHOOT_EXCEL_SHEET_NAME_RAW_DATA,
+        help=f"The Excel Sheet Name with the Kahoot Raw Data. Default {KAHOOT_EXCEL_SHEET_NAME_RAW_DATA}",
+        type=str,
+    )
+    parser.add_argument(
+        "--csv",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Enable or disable CSV export of question data (default: disabled).",
+    )
+    parser.add_argument(
+        "-t",
+        "--title",
+        default=DEFAULT_DECK_TITLE,
+        help="Name of the Anki deck to be created. "
+        f"If not specified, the default deck name '{DEFAULT_DECK_TITLE}' will be used.",
+        type=str,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Show the version number and exit.",
+    )
+    args = parser.parse_args()
+
+    return CLIArgs(
+        input_path=os.path.abspath(args.inp),
+        output_path=os.path.abspath(args.out),
+        sheet=args.sheet,
+        export_csv=args.csv,
+        deck_title=args.title
+    )
+
+
+def validation(input_directory: str, output_directory: str) -> None:
+    """
+    This function validates the command line arguments, checking if the input path is a valid Excel file or directory
+    and if the output path is a valid directory.
+    The input path needs to be an Excel file or a directory that contains Excel files.
+    The output path needs to be a directory and not a file.
+
+    :param input_directory: The path of the input Excel or directory
+    :param output_directory: The path of the output directory
+    :return: None
+    :rtype: None
+    """
+    # Check if input is a file
+    if not os.path.exists(input_directory):
+        logging.error(f"Input directory {input_directory} does not exist!")
+        raise FileNotFoundError(f"Input directory {input_directory} does not exist!")
+    elif (
+        os.path.isfile(input_directory)
+        and os.path.splitext(input_directory)[-1] != ".xlsx"
+    ):
+        logging.error("Input file is not an excel file!")
+        raise ValueError("Input file is not an excel file!")
+    elif os.path.isdir(input_directory):
+        input_excels = os.path.join(input_directory, "*.xlsx")
+        if not glob.glob(input_excels):
+            logging.error("Input directory does not contain any excel files!")
+            raise FileNotFoundError("Input directory does not contain any excel files!")
+
+    # Check output directory and create when not existing
+    if not os.path.isdir(output_directory):
+        logging.error("Output is not a directory!")
+        raise ValueError("Output is not a directory!")
+    if not os.path.exists(output_directory):
+        try:
+            os.makedirs(output_directory)
+        except OSError as e:
+            logging.error(
+                "Failed to create output directory '%s': %s", output_directory, str(e)
+            )
+            raise

kahoot_to_anki/main.py

@@ -0,0 +1,40 @@
+import os
+import logging
+import sys
+
+from kahoot_to_anki.cli import get_commandline_arguments, validation
+from kahoot_to_anki.processing import get_questions, make_anki
+
+# Configure logging settings
+logging.basicConfig(level=logging.INFO)
+
+
+def main() -> None:
+    # Check command line arguments
+    args = get_commandline_arguments()
+
+    validation(args.input_path, args.output_path)
+
+    df = get_questions(input_directory=args.input_path, sheet_name=args.sheet)
+    
+    if df.empty:
+        logging.warning("No Kahoot questions found to process. Exiting.")
+        sys.exit(0)
+
+    if args.export_csv:
+        df.to_csv(
+            os.path.join(args.output_path, "kahoot.csv"),
+            sep=";",
+            index=False,
+            encoding="utf-8-sig",
+        )
+        
+    make_anki(df, args.output_path, args.deck_title)
+
+
+if __name__ == "__main__":
+    main()
+    
+    
+    
+    

kahoot_to_anki/processing.py

@@ -0,0 +1,143 @@
+# Standard library imports
+import logging
+import os
+import glob
+from typing import Iterator, Optional
+
+# Third-party library imports
+import genanki
+import pandas as pd
+
+
+def get_questions(input_directory: str, sheet_name: str) -> pd.DataFrame:
+    """
+    Extracts all the kahoot questions out of the Excel file(s)
+
+    :param input_directory: The path to the input directory or Excel file
+    :param sheet_name: The Excel sheet name with the Kahoot Answers
+    :return: All the questions with the possible answers and the solution
+    :rtype: pd.DataFrame
+    """
+
+    out = pd.DataFrame(columns=["Question", "Possible Answers", "Correct Answers"])
+
+    questions_cnt = 0
+    files_cnt = 0
+
+    for file in get_excels(input_directory):
+        df = get_excel_data(excel_file=file, sheet_name=sheet_name)
+        if df is None:
+            continue
+        files_cnt += 1
+
+        df = df_processing(df)
+
+        # add to out dataframe
+        out = pd.concat([out, df], axis=0, ignore_index=True)
+
+        questions_cnt += len(df)
+
+    logging.info("Read input files: %d", files_cnt)
+    logging.info("Read questions: %d", questions_cnt)
+    out = out.drop_duplicates(subset=["Question"])
+    return out
+
+
+def get_excels(path: str) -> Iterator[str]:
+    """
+    Returns a generator with all Excel files in the given path.
+    :param path: the path to an Excel file or a directory with Excel files
+    :return: a generator of Excel file paths
+    """
+    if os.path.isfile(path):
+        yield path
+    else:
+        yield from glob.glob(os.path.join(path, "*.xlsx"))
+
+
+def get_excel_data(excel_file: str, sheet_name:str) -> Optional[pd.DataFrame]:
+    """
+    Returns a pd.DataFrame with the kahoot raw data
+    :param excel_file: an Excel file with Kahoot raw data
+    :param sheet_name: the Excel sheet name with the Kahoot answers
+    :return: a DataFrame with the data
+    """
+    try:
+        # read file
+        return pd.read_excel(
+            excel_file, sheet_name=sheet_name
+        )
+    except ValueError:
+        logging.warning(
+            "Skipping file '%s' as it is not a valid Excel file.", excel_file
+        )
+        return None
+    except Exception as e:
+        logging.error("Failed to read file '%s': %s", excel_file, str(e))
+        return None
+
+
+def df_processing(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Processes the Kahoot question data.
+    :param data: DataFrame with Kahoot question data
+    :return: Processed DataFrame
+    """
+    if data.empty:
+        return pd.DataFrame(columns=["Question", "Possible Answers", "Correct Answers"])
+    
+    # delete duplicated questions
+    data = data.drop_duplicates(subset=["Question Number"])
+    data = data.fillna("")
+
+    data["Possible Answers"] = data[
+        ["Answer 1", "Answer 2", "Answer 3", "Answer 4", "Answer 5", "Answer 6"]
+    ].astype(str).agg("<br>".join, axis=1)
+
+    # keep only needed columns
+    data = data[["Question", "Possible Answers", "Correct Answers"]]
+
+    return data
+
+
+def make_anki(df: pd.DataFrame, out: str, title: str) -> None:
+    """
+    Creates an Anki deck from the given Kahoot questions
+
+    :param df: The kahoot questions in a pd.DataFrame
+    :param out: The path to the output directory
+    :param title: The title of the Anki deck
+    :return: None
+    """
+    my_model = genanki.Model(
+        1607392319,
+        "Simple Model",
+        fields=[
+            {"name": "Question"},
+            {"name": "Answer"},
+            {"name": "selects"},
+        ],
+        templates=[
+            {
+                "name": "Card 1",
+                "qfmt": "{{Question}}<br><br>{{selects}}",
+                "afmt": '{{FrontSide}}<hr id="answer">{{Answer}}',
+            },
+        ],
+    )
+
+    my_deck = genanki.Deck(2059400110, title)
+
+    for index, row in df.iterrows():
+        my_note = genanki.Note(
+            model=my_model,
+            fields=[row["Question"], row["Correct Answers"], row["Possible Answers"]],
+        )
+        my_deck.add_note(my_note)
+
+    try:
+        genanki.Package(my_deck).write_to_file(
+            os.path.join(out, "anki.apkg"),
+        )
+    except Exception as e:
+        logging.error("Failed to write Anki package file: %s", str(e))

kahoot_to_anki-1.2.0.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: kahoot-to-anki
+Version: 1.2.0
+Summary: CLI tool to convert Kahoot quiz reports into Anki flashcards
+Author: Simon Hardmeier
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: genanki
+Requires-Dist: pandas
+Requires-Dist: openpyxl
+Dynamic: license-file
+
+# kahoot-to-anki
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](#installation)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+<br>
+
+**kahoot-to-anki** is a command‑line tool that converts exported Kahoot quiz reports (Excel Files) into Anki flashcard decks (.apkg format).<br>
+Designed for educators, students, and any self-learners to easily turn quiz results into effective spaced‑repetition decks.
+
+## Installation & Usage
+### Option 1: Install via pip
+```
+pip install kahoot-to-anki
+```
+Then run:
+```
+kahoot-to-anki --help
+```
+Example: Process all Kahoot Exports in the `./exports/` folder and write the flashcard deck and CSV file to `./data/`:
+```
+kahoot-to-anki --inp "./exports" --out "./data" --csv
+```
+
+### Option 2: Run with Docker
+```
+# Clone Repository
+git clone https://github.com/SimonHRD/kahoot-to-anki.git
+
+# Move into Repository
+cd kahoot-to-anki
+
+# Build docker image with the kahoot-to-anki tag
+docker build -t kahoot-to-anki .
+
+# Check help command
+docker run --rm kahoot-to-anki --help
+
+# Run with local data
+docker run --rm -v "$(pwd)/data:/app/data" kahoot-to-anki --out "./data" --csv
+```
+
+On PowerShell:
+```
+docker run --rm -v ${PWD}\data:/app/data kahoot-to-anki --out "./data" --csv
+```
+
+## CLI Arguments
+You can provide either a single Kahoot Excel file or a directory containing multiple `.xlsx` files as input.<br>
+All valid Excel files in the directory will be processed.
+
+| Argument             | Description                                                                    |
+|----------------------|--------------------------------------------------------------------------------|
+| `-i`, `--inp`        | Path to the input Excel file or directory (default: `./data`)                  |
+| `-o`, `--out`        | Path to the output directory for the Anki deck (default: `./`)                 |
+| `--sheet`            | The Excel Sheet with the raw Kahoot quiz data (default: `RawReportData Data`)  |    
+| `--csv`, `--no-csv`  | Enable or disable CSV export of the questions (default: disabled)              |
+| `-t`, `--title`      | Title of the generated Anki deck (default: `"Kahoot"`)                         |
+| `--version`          | Show the version of the installed kahoot-to-anki package                       |
+
+
+## Example
+An example Kahoot export file is available in `data/`. The generated deck will be saved as `anki.apkg` in the specified `--out` directory (default: `./`).
+
+## License
+MIT — see [LICENSE](./LICENSE)

kahoot_to_anki-1.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+kahoot_to_anki/__init__.py,sha256=Btl_98iBIXFtvGx47MqpfbaEVYoOMPBQn9bao7UASkQ,21
+kahoot_to_anki/cli.py,sha256=2tRiIcnbcrPXVPQ8mdeUOHXYP3LO9ExNfp3Uy1FSaFk,4484
+kahoot_to_anki/main.py,sha256=oVmOLqXUnzy1Q0Xnn4Dzr65bFf8Jaw4vYRwvDTSd_ro,936
+kahoot_to_anki/processing.py,sha256=Ku8nFhgWpprmYWdLL6f-T8P7J_SmMuQD2NLVCQQErCs,4346
+kahoot_to_anki-1.2.0.dist-info/licenses/LICENSE,sha256=HxPBlT4sSfEgRBrX0jZd8WTfM0c31VFgnLaCEWzGMZc,1122
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_cli.py,sha256=SL1WEJoA59-G7hRdWg5wOUyCPrjzZvsgPJxAZMPXpWg,3195
+tests/test_processing.py,sha256=swLG2gkcwWm1ZG0T5u6izlhV-2AIsaMKdg174jp3za8,10951
+kahoot_to_anki-1.2.0.dist-info/METADATA,sha256=I8iBo7bvvBQMyMticSKPHsILRASFMaB0VRi45EWhv3E,2953
+kahoot_to_anki-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kahoot_to_anki-1.2.0.dist-info/entry_points.txt,sha256=VqCk_PPVpGFgnGCBIlEnz8Y0qUqYV8J2tYNZZa8IRWA,60
+kahoot_to_anki-1.2.0.dist-info/top_level.txt,sha256=aTMCk83rMZjWFZ556EHLIxVOgEawIWsMZzRpR3IPQ1w,21
+kahoot_to_anki-1.2.0.dist-info/RECORD,,

kahoot_to_anki-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kahoot-to-anki = kahoot_to_anki.main:main

tests/test_cli.py

@@ -0,0 +1,111 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+from kahoot_to_anki.cli import get_commandline_arguments, validation
+
+
+# --- get_commandline_arguments ---
+def test_get_commandline_arguments(monkeypatch):
+    """Test that CLI arguments are correctly parsed."""
+
+    test_args = [
+        "kahoot-to-anki",
+        "-i", "tests/data",
+        "-o", "output_dir",
+        "--csv",
+        "--sheet", "CustomSheet",
+        "--title", "My Deck"
+    ]
+
+    monkeypatch.setattr(sys, "argv", test_args)
+
+    args = get_commandline_arguments()
+
+    assert Path(args.input_path).name == "data"
+    assert Path(args.output_path).name == "output_dir"
+    assert args.export_csv is True
+    assert args.sheet == "CustomSheet"
+    assert args.deck_title == "My Deck"
+  
+    
+def test_get_commandline_arguments_no_csv(monkeypatch):
+    """Test that --no-csv CLI argument is correctly parsed."""
+
+    test_args = [
+        "kahoot-to-anki",
+        "--no-csv",
+    ]
+
+    monkeypatch.setattr(sys, "argv", test_args)
+    args = get_commandline_arguments()
+
+    assert args.export_csv is False
+    
+    
+# --- validation ---
+def test_validation_valid_excel_file(tmp_path):
+    # Create dummy Excel file
+    excel_file = tmp_path / "valid.xlsx"
+    excel_file.write_text("Excel content")
+
+    # Create output directory
+    output_dir = tmp_path / "output"
+    output_dir.mkdir()
+
+    # Should not raise
+    validation(str(excel_file), str(output_dir)) 
+    
+    
+def test_validation_valid_input_directory_with_excel(tmp_path):
+    input_dir = tmp_path / "input"
+    input_dir.mkdir()
+    (input_dir / "file1.xlsx").write_text("Excel content")
+
+    output_dir = tmp_path / "output"
+    output_dir.mkdir()
+
+     # Should not raise
+    validation(str(input_dir), str(output_dir)) 
+    
+    
+def test_validation_input_path_does_not_exist(tmp_path):
+    output_dir = tmp_path / "output"
+    output_dir.mkdir()
+
+    with pytest.raises(FileNotFoundError):
+        validation(str(tmp_path / "missing.xlsx"), str(output_dir))
+        
+        
+def test_validation_input_not_excel_file(tmp_path):
+    file = tmp_path / "file.txt"
+    file.write_text("Not Excel")
+    output_dir = tmp_path / "output"
+    output_dir.mkdir()
+
+    with pytest.raises(ValueError, match="Input file is not an excel file"):
+        validation(str(file), str(output_dir))
+        
+        
+def test_validation_input_directory_no_excel_files(tmp_path):
+    input_dir = tmp_path / "input"
+    input_dir.mkdir()
+    (input_dir / "file.txt").write_text("Just text")
+
+    output_dir = tmp_path / "output"
+    output_dir.mkdir()
+
+    with pytest.raises(FileNotFoundError, match="does not contain any excel files"):
+        validation(str(input_dir), str(output_dir))
+        
+        
+def test_validation_output_not_a_directory(tmp_path):
+    excel_file = tmp_path / "valid.xlsx"
+    excel_file.write_text("Excel content")
+
+    output_path = tmp_path / "output.txt"
+    output_path.write_text("Not a directory")
+
+    with pytest.raises(ValueError, match="Output is not a directory"):
+        validation(str(excel_file), str(output_path))