mcqpy-core 0.2.0__tar.gz

mcqpy_core-0.2.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.3
+Name: mcqpy-core
+Version: 0.2.0
+Summary: Core question, manifest, grading, analysis, and browser-safe runtime logic for MCQPy
+Author: Mads-Peter
+Author-email: Mads-Peter <machri@phys.au.dk>
+Requires-Dist: pydantic>=2.6,<2.12
+Requires-Dist: matplotlib>=3.10.7 ; extra == 'analysis'
+Requires-Dist: numpy>=2.3.3 ; extra == 'analysis'
+Requires-Dist: scipy>=1.17.0 ; extra == 'analysis'
+Requires-Dist: rich>=14.2.0 ; extra == 'cli'
+Requires-Dist: rich-click>=1.9.3 ; extra == 'cli'
+Requires-Dist: pandas>=2.3.3 ; extra == 'grading'
+Requires-Dist: pyyaml>=6.0.3 ; extra == 'yaml'
+Requires-Python: >=3.12
+Provides-Extra: analysis
+Provides-Extra: cli
+Provides-Extra: grading
+Provides-Extra: yaml
+Description-Content-Type: text/markdown
+
+# mcqpy-core
+
+Core question, manifest, grading, analysis, and browser-safe runtime logic for MCQPy.
+
+This package is built from its package-local source tree under `packages/mcqpy-core/src/mcqpy_core`.

mcqpy_core-0.2.0/README.md

@@ -0,0 +1,5 @@
+# mcqpy-core
+
+Core question, manifest, grading, analysis, and browser-safe runtime logic for MCQPy.
+
+This package is built from its package-local source tree under `packages/mcqpy-core/src/mcqpy_core`.

mcqpy_core-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "mcqpy-core"
+version = "0.2.0"
+description = "Core question, manifest, grading, analysis, and browser-safe runtime logic for MCQPy"
+readme = "README.md"
+authors = [
+    { name = "Mads-Peter", email = "machri@phys.au.dk" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.6,<2.12",
+]
+
+[project.optional-dependencies]
+yaml = [
+    "pyyaml>=6.0.3",
+]
+grading = [
+    "pandas>=2.3.3",
+]
+analysis = [
+    "matplotlib>=3.10.7",
+    "numpy>=2.3.3",
+    "scipy>=1.17.0",
+]
+cli = [
+    "rich>=14.2.0",
+    "rich-click>=1.9.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.18,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"

mcqpy_core-0.2.0/src/mcqpy_core/__init__.py

@@ -0,0 +1,14 @@
+"""Core MCQPy models and logic."""
+
+from importlib import import_module
+
+from .manifest import Manifest, ManifestItem
+from .question import Question
+
+__all__ = ["Manifest", "ManifestItem", "Question", "QuestionBank"]
+
+
+def __getattr__(name: str):
+    if name == "QuestionBank":
+        return import_module("mcqpy_core.question").QuestionBank
+    raise AttributeError(name)

mcqpy_core-0.2.0/src/mcqpy_core/cli/__init__.py

@@ -0,0 +1,29 @@
+"""Command registration for mcqpy-core."""
+
+from mcqpy_core.cli.main import main
+from mcqpy_core.cli.export import export_group
+from mcqpy_core.cli.export.token import decode_token_command, encode_token_command
+from mcqpy_core.cli.export.web import export_web_command
+from mcqpy_core.cli.init import init_command
+from mcqpy_core.cli.question import question_group
+from mcqpy_core.cli.utils.check_filter import check_filter_command
+from mcqpy_core.cli.utils.main import utils_group
+
+
+def register_core_commands(parent) -> None:
+    for name, command in main.commands.items():
+        parent.add_command(command, name)
+
+
+__all__ = [
+    "register_core_commands",
+    "main",
+    "init_command",
+    "export_group",
+    "export_web_command",
+    "encode_token_command",
+    "decode_token_command",
+    "question_group",
+    "utils_group",
+    "check_filter_command",
+]

mcqpy_core-0.2.0/src/mcqpy_core/cli/_selection.py

@@ -0,0 +1,31 @@
+"""Shared question-selection helpers for CLI commands."""
+
+from __future__ import annotations
+
+from mcqpy_core.cli.config import SelectionConfig
+from mcqpy_core.question import QuestionBank
+from mcqpy_core.question.filter import FilterFactory
+
+
+def _build_filter(filter_name: str, filter_params: dict):
+    filter_config = {"type": filter_name, **filter_params}
+    return FilterFactory.from_config(filter_config)
+
+
+def build_filters(selection_config: SelectionConfig):
+    filter_objs = []
+    if selection_config.filters:
+        for filter_name, filter_params in selection_config.filters.items():
+            filter_objs.append(_build_filter(filter_name, filter_params))
+    return filter_objs
+
+
+def select_questions(question_bank: QuestionBank, selection_config: SelectionConfig):
+    for filter_obj in build_filters(selection_config):
+        question_bank.add_filter(filter_obj)
+
+    return question_bank.get_filtered_questions(
+        number_of_questions=selection_config.number_of_questions,
+        shuffle=selection_config.shuffle,
+        sorting=selection_config.sort_type,
+    )

mcqpy_core-0.2.0/src/mcqpy_core/cli/build.py

@@ -0,0 +1,89 @@
+"""
+CLI Build Command
+"""
+
+from pathlib import Path
+
+import rich_click as click
+from rich.pretty import Pretty
+from rich.console import Console
+
+from mcqpy_core.cli._selection import select_questions, _build_filter, build_filters
+from mcqpy_core.cli.config import QuizConfig
+from mcqpy_core.cli.main import main
+from mcqpy_pdf.compile import MultipleChoiceQuiz
+from mcqpy_core.manifest import Manifest
+from mcqpy_core.question import QuestionBank
+
+
+# Backward-compatible private alias kept for older tests/importers.
+_select_questions = select_questions
+
+
+def build_solution(questions, manifest, output_path: Path):
+    from mcqpy_pdf.compile.solution_pdf import SolutionPDF
+
+    solution_pdf = SolutionPDF(file=output_path, questions=questions, manifest=manifest)
+    solution_pdf.build(generate_pdf=True)
+
+@main.command(
+    name="build",
+    help="""Build the quiz PDF from question files based on the provided configuration.
+    This command reads the quiz configuration, selects questions from the question bank,
+    and generates the quiz PDF along with a solution PDF.
+""",
+)
+@click.option(
+    "-c",
+    "--config",
+    type=click.Path(exists=True, path_type=Path),
+    default="config.yaml",
+    help="Path to the config file",
+    show_default=True,
+)
+def build_command(config):
+    """ 
+    Build the quiz PDF from question files based on the provided configuration.
+    This command reads the quiz configuration, selects questions from the question bank,
+    and generates the quiz PDF along with a solution PDF.
+
+    ```
+    mcqpy build --config config.yaml
+    ```
+    """
+
+    config = QuizConfig.read_yaml(config)
+    question_bank = QuestionBank.from_directories(
+        config.questions_paths, seed=config.selection.seed
+    )
+    questions = select_questions(question_bank, config.selection)
+
+    console = Console()
+    console.print("[bold green]Quiz Configuration:[/bold green]")
+    console.print(Pretty(config))
+    console.print(
+        f"[bold green]Total questions in bank:[/bold green] {len(question_bank)}"
+    )
+    console.print(f"[bold green]Selected questions:[/bold green] {len(questions)}")
+
+    ## Paths:
+    for path in [config.root_directory, config.output_directory, config.submission_directory]:
+        if path and not path.exists():
+            path.mkdir(parents=True, exist_ok=True)  # pragma: no cover
+
+    mcq = MultipleChoiceQuiz(
+        file=config.file_path,
+        questions=questions,
+        front_matter=config.front_matter,
+        header_footer=config.header,
+    )
+
+    mcq.build(generate_pdf=True)
+
+    # Build solution PDF
+    manifest_path = mcq.get_manifest_path()
+    manifest = Manifest.load_from_file(manifest_path)
+    solution_output_path = (
+        config.output_directory / f"{config.file_name.replace('.pdf', '')}_solution.pdf"
+    )
+    build_solution(questions, manifest, solution_output_path)

mcqpy_core-0.2.0/src/mcqpy_core/cli/check_latex.py

@@ -0,0 +1,31 @@
+"""
+CLI command to check LaTeX installation and configuration.
+"""
+
+from mcqpy_core.cli import main
+
+@main.command('check-latex', help="Check LaTeX installation and configuration.")
+def check_latex_command():
+    """
+    Check if LaTeX is installed and properly configured. 
+    Provides the CLI command:
+    ```
+    mcqpy check-latex
+    ```
+    This command verifies the presence of LaTeX tools such as `pdflatex` and `latexmk`,
+    and attempts to compile a simple LaTeX document to ensure everything is functioning correctly.
+    """
+
+    from mcqpy_pdf.utils.check_latex import check_latex_installation
+    from rich.console import Console
+    
+    console = Console()    
+    success, details = check_latex_installation()
+    
+    if success:
+        console.print("[bold green]✓ LaTeX is properly installed![/bold green]")
+        console.print(f"[green]pdflatex version[/green]: {details['pdflatex'].version}")
+        console.print(f"[green]latexmk version[/green]: {details['latexmk'].version}")
+        console.print("[green]Compilation test passed successfully.[/green]")
+    else:
+        console.print(f"[bold red]✗ LaTeX installation issue: {details['error_message']}[/bold red]")

mcqpy_core-0.2.0/src/mcqpy_core/cli/config.py

@@ -0,0 +1,167 @@
+"""Quiz configuration management using Pydantic and YAML."""
+
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, ConfigDict, field_validator, model_validator
+
+from mcqpy_core.front_config import FrontMatterOptions
+from mcqpy_core.header_config import HeaderFooterOptions
+
+
+def _import_yaml():
+    try:
+        import yaml
+    except ModuleNotFoundError as exc:  # pragma: no cover - environment dependent
+        raise ModuleNotFoundError(
+            "PyYAML is required for quiz config YAML operations. "
+            "Install mcqpy-core with the 'yaml' extra."
+        ) from exc
+    return yaml
+
+
+class GradingConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+    submission_directory: str = Field(
+        default="submissions", description="Directory for student submissions relative to quiz root directory"
+    )
+    anonymous_pattern: str | None = Field(
+        default=None,
+        description="Regex pattern to extract identifiers from anonymous exam filenames (e.g., 'exam_(?P<id1>\\w+)_(?P<id2>\\w+)\\.pdf')",
+    )
+    output_sort_key: str | None = Field(
+        default=None,
+        description="Key to sort output files, e.g., 'student_name' or 'student_id' or one based on the anonymous pattern",
+    )
+
+    @field_validator("anonymous_pattern")
+    @classmethod
+    def validate_pattern(cls, v):
+        """Validate that the pattern is a valid regex"""
+        if v is not None:
+            import re
+
+            try:
+                re.compile(v)
+            except re.error as e:
+                raise ValueError(f"Invalid regex pattern: {e}")
+        return v
+
+
+class SelectionConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+    number_of_questions: int | None = Field(
+        default=20, description="Number of questions to select"
+    )
+    filters: dict[str, dict[str, Any]] | None = Field(
+        default=None, description="Filters to apply when selecting questions"
+    )
+    seed: int | None = Field(
+        default=None, description="Random seed for question selection"
+    )
+    shuffle: bool = Field(
+        default=False, description="Whether to shuffle selected questions"
+    )
+    sort_type: Literal["slug", "none"] = Field(
+        default="none", description="Sort type for selected questions"
+    )
+
+
+class QuizConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", validate_assignment=True, populate_by_name=True)
+    questions_paths_: list[str] | str = Field(
+        default=["questions"], description="Paths to question files or directories, relative to the config file's directory", alias="questions_paths"
+    )
+    file_name: str = Field(
+        default="quiz.pdf", description="Name of the output PDF file"
+    )
+    
+    root_directory_: str = Field(
+        default=".", description="Root directory for the quiz project, relative to the location of the config file", 
+        alias="root_directory"
+    )
+    output_directory_: str = Field(
+        default="output", description="Directory for output files, relative to the root directory", alias="output_directory"
+    )
+    grading: GradingConfig = Field(default_factory=GradingConfig)
+    front_matter: FrontMatterOptions = Field(default_factory=FrontMatterOptions)
+    header: HeaderFooterOptions = Field(default_factory=HeaderFooterOptions)
+    selection: SelectionConfig = Field(default_factory=SelectionConfig)
+    path: Path | None = Field(None, description="Internal: file path from which the config was loaded", exclude=True)
+
+    @property
+    def root_directory(self) -> Path:
+        """Get root directory as a Path object"""
+        return (Path(self.path).parent / self.root_directory_).resolve()
+    
+    @property
+    def output_directory(self) -> Path:
+        """Get output directory as a Path object"""
+        return self.root_directory / self.output_directory_
+
+    @property
+    def questions_paths(self) -> list[Path]:
+        """Get questions paths as Path objects"""
+        return [(self.path.parent / p).resolve() for p in self.questions_paths_]
+    
+    @property
+    def file_path(self) -> Path:
+        """Get full file path for the output PDF"""
+        return self.output_directory / self.file_name
+    
+    @property
+    def submission_directory(self) -> Path:
+        """Get submission directory as a Path object"""
+        return self.root_directory / self.grading.submission_directory
+    
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_submission_directory(cls, data):
+        """Migrate submission_directory from top level to grading config"""
+        if isinstance(data, dict) and "submission_directory" in data:
+            if "grading" not in data:
+                data["grading"] = {}
+            data["grading"]["submission_directory"] = data.pop("submission_directory")
+        return data
+    
+    @model_validator(mode="before")
+    def check_paths_exist(cls, data):
+        """Resolve questions_paths relative to the config file's directory"""
+        path = data.get("path")
+        if not path:
+            return data
+        
+        config_dir = path.parent
+        
+        # Questions:
+        paths_to_check = data.get("questions_paths", []) + data.get("questions_paths_", [])
+        for path in paths_to_check:
+            resolved_path = (config_dir / path).resolve()
+            if not resolved_path.exists():
+                raise FileNotFoundError(f"Questions path does not exist: {resolved_path}")
+
+        return data
+
+    def yaml_dump(self) -> str:
+        """Dump the current configuration to a YAML string"""
+        yaml = _import_yaml()
+        config_dict = self.model_dump(by_alias=True)
+        yaml_content = yaml.dump(config_dict, default_flow_style=False, sort_keys=False)
+        return yaml_content
+
+    @classmethod
+    def generate_example_yaml(cls) -> str:
+        """Generate example YAML with comments"""
+        example = cls()
+        return example.yaml_dump()
+
+    @classmethod
+    def read_yaml(cls, file_path: str) -> "QuizConfig":
+        """Read YAML file and return a QuizConfig instance"""
+        yaml = _import_yaml()
+        with open(file_path, "r") as file:
+            yaml_string = file.read()
+        data = yaml.safe_load(yaml_string)
+        data['path'] = Path(file_path).resolve()
+        return cls(**data)

mcqpy_core-0.2.0/src/mcqpy_core/cli/export/__init__.py

@@ -0,0 +1,12 @@
+"""Export command registrations."""
+
+from .main import export_group
+from .token import decode_token_command, encode_token_command
+from .web import export_web_command
+
+__all__ = [
+    "export_group",
+    "encode_token_command",
+    "decode_token_command",
+    "export_web_command",
+]

mcqpy_core-0.2.0/src/mcqpy_core/cli/export/main.py

@@ -0,0 +1,11 @@
+"""CLI group for web export utilities."""
+
+import rich_click as click
+
+from mcqpy_core.cli.main import main
+
+
+@main.group(name="export")
+def export_group() -> None:
+    """Commands for exporting browser-ready quiz artifacts."""
+    return None  # pragma: no cover

mcqpy_core-0.2.0/src/mcqpy_core/cli/export/token.py

@@ -0,0 +1,20 @@
+"""CLI helpers for quiz link obfuscation tokens."""
+
+from __future__ import annotations
+
+import rich_click as click
+
+from mcqpy_core.cli.export.main import export_group
+from mcqpy_core.web import decode_quiz_token, encode_quiz_token
+
+
+@export_group.command(name="encode-token", help="Encode a public quiz bundle URL.")
+@click.argument("url")
+def encode_token_command(url: str) -> None:
+    click.echo(encode_quiz_token(url))
+
+
+@export_group.command(name="decode-token", help="Decode a quiz token to its public URL.")
+@click.argument("token")
+def decode_token_command(token: str) -> None:
+    click.echo(decode_quiz_token(token))

mcqpy_core-0.2.0/src/mcqpy_core/cli/export/web.py

@@ -0,0 +1,73 @@
+"""Export browser-ready quiz bundles."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import rich_click as click
+from rich.console import Console
+
+from mcqpy_core.cli._selection import select_questions
+from mcqpy_core.cli.config import QuizConfig
+from mcqpy_core.cli.export.main import export_group
+from mcqpy_core.question import QuestionBank
+from mcqpy_core.web import build_web_quiz_bundle
+
+
+def _default_web_output_dir(config: QuizConfig) -> Path:
+    quiz_stem = Path(config.file_name).stem
+    return config.output_directory / "web" / quiz_stem
+
+
+@export_group.command(name="web", help="Export a static web quiz bundle.")
+@click.option(
+    "-c",
+    "--config",
+    type=click.Path(exists=True, path_type=Path),
+    default="config.yaml",
+    show_default=True,
+    help="Path to the quiz config file.",
+)
+@click.option(
+    "-o",
+    "--output-dir",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Directory for the exported bundle. Defaults to output/web/<quiz-name>/.",
+)
+@click.option(
+    "--asset-base-url",
+    default=None,
+    help="Optional published base URL used to rewrite copied local assets.",
+)
+def export_web_command(
+    config: Path,
+    output_dir: Path | None,
+    asset_base_url: str | None,
+) -> None:
+    """Export selected questions as a browser-ready quiz bundle."""
+
+    quiz_config = QuizConfig.read_yaml(config)
+    target_dir = output_dir or _default_web_output_dir(quiz_config)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    question_bank = QuestionBank.from_directories(
+        quiz_config.questions_paths,
+        seed=quiz_config.selection.seed,
+    )
+    questions = select_questions(question_bank, quiz_config.selection)
+
+    bundle = build_web_quiz_bundle(
+        questions,
+        title=quiz_config.front_matter.title or Path(quiz_config.file_name).stem,
+        description=quiz_config.front_matter.exam_information,
+        source=str(config),
+        asset_dir=target_dir / "assets",
+        asset_base_url=asset_base_url,
+    )
+    bundle_path = bundle.save_to_file(target_dir / "quiz.json")
+
+    console = Console()
+    console.print(f"[bold green]Exported web bundle:[/bold green] {bundle_path}")
+    console.print(f"[bold green]Questions:[/bold green] {len(bundle.questions)}")
+    console.print(f"[bold green]Assets directory:[/bold green] {target_dir / 'assets'}")

mcqpy_core-0.2.0/src/mcqpy_core/cli/grade.py

@@ -0,0 +1,100 @@
+"""Grade student submissions from a quiz."""
+
+import rich_click as click
+from mcqpy_core.cli.main import main
+from mcqpy_core.cli.config import QuizConfig
+from pathlib import Path
+
+from mcqpy_core.grading import MCQGrader, get_grade_dataframe
+from mcqpy_core.manifest import Manifest
+from mcqpy_core.grading.rubric import StrictRubric
+from rich.progress import track
+
+from mcqpy_core.question.question_bank import QuestionBank
+
+
+@main.command(
+    name="grade",
+    help="""Grade student submissions.
+Generates a grade report in the specified format (Excel or CSV).
+Students submissions are expected to be in submission directory specified in the config file.                            
+              """,
+)
+@click.option(
+    "-c",
+    "--config",
+    type=click.Path(exists=True, path_type=Path),
+    default="config.yaml",
+    help="Path to the config file",
+    show_default=True,
+)
+@click.option("-v", "--verbose", is_flag=True, help="Enable verbose output")
+@click.option(
+    "-f",
+    "--file-format",
+    type=click.Choice(["xlsx", "csv"]),
+    default="xlsx",
+    help="Output format for the grades",
+    show_default=True,
+)
+@click.option(
+    "-a",
+    "--analysis",
+    is_flag=True,
+    help="Generate question analysis reports",
+    default=False,
+)
+def grade_command(config, verbose: bool, file_format: str, analysis: bool):
+    """
+    Grade student submissions based on the provided configuration file.
+    Generates a grade report in the specified format (Excel or CSV).
+    Students submissions are expected to be in submission directory specified in the config file.
+
+    Provides the CLI command:
+    ```
+    mcqpy grade --config config.yaml --file-format xlsx --analysis
+    ```
+    """
+    # Load config
+    config = QuizConfig.read_yaml(config)
+    manifest_path = config.output_directory / f"{config.file_path.stem}_manifest.json"
+    manifest = Manifest.load_from_file(manifest_path)
+
+    # Read & Grade submissions
+    graded_sets = []
+    grader = MCQGrader(
+        manifest, StrictRubric(), regex_pattern=config.grading.anonymous_pattern
+    )
+    submissions = list(config.submission_directory.glob("*.pdf"))
+    for submission in track(
+        submissions,
+        description=f"Grading submissions ({len(submissions)})",
+        total=len(submissions),
+    ):
+        graded_set = grader.grade(submission)
+        graded_sets.append(graded_set)
+
+    # Export grades to dataframe
+    df = get_grade_dataframe(graded_sets, sort_key=config.grading.output_sort_key)
+    output_path = (config.root_directory / f"{config.file_path.stem}_grades.{file_format}")
+    if file_format == "xlsx":
+        df.to_excel(output_path, index=False)
+    elif file_format == "csv":
+        df.to_csv(output_path, index=False)
+
+    if analysis:
+        from mcqpy_pdf.analysis.report import QuizAnalysis
+
+        analysis_directory = config.root_directory / "analysis/"
+        analysis_directory.mkdir(exist_ok=True)
+
+        question_bank = QuestionBank.from_directories(config.questions_paths)
+        print(f"Question bank loaded for analysis - {len(question_bank)}")
+
+        quiz_analysis = QuizAnalysis(
+            graded_sets,
+            question_bank=question_bank,
+            output_dir=analysis_directory,
+            grading_config=config.grading,
+        )
+        quiz_analysis.build()