dsap-cli 0.1.0__py3-none-any.whl

dsap/models.py

@@ -0,0 +1,225 @@
+"""Pydantic models for DSAP.
+
+These models define the core data structures used throughout the application.
+Using Pydantic provides:
+- Automatic validation of data types and constraints
+- Clear documentation of fields and their requirements
+- Easy serialization to/from JSON and dictionaries
+- Type hints for better IDE support
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field, HttpUrl, field_validator, model_validator
+
+
+class DSAPBaseModel(BaseModel):
+    """Base model with common configuration for all DSAP models."""
+
+    model_config = {
+        "validate_assignment": True,
+    }
+
+
+class Difficulty(str, Enum):
+    """Problem difficulty levels.
+
+    Using an enum ensures only valid difficulties are accepted
+    and provides better autocomplete in IDEs.
+    """
+
+    EASY = "Easy"
+    MEDIUM = "Medium"
+    HARD = "Hard"
+
+    @classmethod
+    def from_string(cls, value: str) -> Difficulty:
+        """Convert a string to Difficulty, case-insensitive."""
+        normalized = value.strip().lower()
+        mapping: dict[str, Difficulty] = {
+            "easy": cls.EASY,
+            "medium": cls.MEDIUM,
+            "hard": cls.HARD,
+        }
+        if normalized not in mapping:
+            raise ValueError(
+                f"Invalid difficulty: {value}. Must be Easy, Medium, or Hard"
+            )
+        return mapping[normalized]
+
+
+class Problem(DSAPBaseModel):
+    """Represents a DSA problem from a curated problem set."""
+
+    id: int | None = None
+    title: Annotated[str, Field(min_length=1, max_length=200)]
+    url: HttpUrl
+    difficulty: Difficulty
+    category: Annotated[str, Field(min_length=1, max_length=100)]
+    description: str = ""
+    tags: list[str] = Field(default_factory=list)
+    problem_set: str = "custom"
+    problem_number: int = Field(default=0, ge=0)
+    company_tags: list[str] = Field(default_factory=list)
+    hints: list[str] = Field(default_factory=list)
+    created_at: datetime | None = None
+
+    model_config = {
+        "str_strip_whitespace": True,
+        "validate_assignment": True,
+    }
+
+    @field_validator("title", "category")
+    @classmethod
+    def strip_whitespace(cls, value: str) -> str:
+        """Strip leading/trailing whitespace from string fields."""
+        return value.strip()
+
+    @field_validator("tags", "company_tags", "hints", mode="before")
+    @classmethod
+    def ensure_list(cls, value: Any) -> list[str]:
+        """Ensure list fields are actually lists of strings."""
+        if value is None:
+            return []
+        if isinstance(value, str):
+            return [x.strip() for x in value.split(",") if x.strip()]
+        if isinstance(value, list):
+            return value
+        return [str(value)]
+
+    @field_validator("difficulty", mode="before")
+    @classmethod
+    def normalize_difficulty(cls, value: Difficulty | str) -> Difficulty:
+        """Accept difficulty as string or enum."""
+        if isinstance(value, Difficulty):
+            return value
+        return Difficulty.from_string(value)
+
+
+class ProblemProgress(DSAPBaseModel):
+    """Tracks user's progress on a specific problem with SM-2 state."""
+
+    problem_id: int
+
+    # SM-2 state with validation
+    easiness_factor: Annotated[float, Field(ge=1.3, le=5.0)] = 2.5
+    interval: Annotated[int, Field(ge=0)] = 0
+    repetitions: Annotated[int, Field(ge=0)] = 0
+    next_review: datetime | None = None
+    last_reviewed: datetime | None = None
+
+    # Practice tracking
+    attempts: Annotated[int, Field(ge=0)] = 0
+    solved: bool = False
+    first_attempted: datetime | None = None
+    solved_at: datetime | None = None
+    last_quality: Annotated[int, Field(ge=0, le=5)] | None = None
+    notes: str = ""
+    time_spent_minutes: Annotated[int, Field(ge=0)] = 0
+
+    @model_validator(mode="after")
+    def validate_dates(self) -> ProblemProgress:
+        """Ensure date fields are logically consistent."""
+        if (
+            self.solved_at
+            and self.first_attempted
+            and self.solved_at < self.first_attempted
+        ):
+            raise ValueError("solved_at cannot be before first_attempted")
+
+        if self.solved and self.solved_at is None:
+            self.solved_at = datetime.now()
+        return self
+
+    def is_due(self, now: datetime | None = None) -> bool:
+        """Check if this problem is due for review."""
+        if now is None:
+            now = datetime.now()
+        if self.next_review is None:
+            return True
+        return now >= self.next_review
+
+    def is_new(self) -> bool:
+        """Check if this problem has never been attempted."""
+        return self.attempts == 0
+
+
+class ReviewSession(DSAPBaseModel):
+    """Represents a single practice/review session."""
+
+    id: int | None = None
+    date: datetime = Field(default_factory=datetime.now)
+    problems_reviewed: Annotated[int, Field(ge=0)] = 0
+    problems_due: Annotated[int, Field(ge=0)] = 0
+    average_quality: Annotated[float, Field(ge=0, le=5)] = 0.0
+    duration_minutes: Annotated[int, Field(ge=0)] = 0
+    notes: str = ""
+
+
+class Statistics(DSAPBaseModel):
+    """Aggregated statistics for display."""
+
+    total_problems: int = 0
+    reviewed_problems: int = 0
+    solved_problems: int = 0
+    due_today: int = 0
+    due_this_week: int = 0
+    average_easiness_factor: float = 2.5
+    current_streak: int = 0
+    best_streak: int = 0
+    total_reviews: int = 0
+
+    # Breakdown by difficulty
+    easy_total: int = 0
+    easy_solved: int = 0
+    medium_total: int = 0
+    medium_solved: int = 0
+    hard_total: int = 0
+    hard_solved: int = 0
+
+    @property
+    def solved_percentage(self) -> float:
+        """Calculate overall solved percentage."""
+        if self.total_problems == 0:
+            return 0.0
+        return round(self.solved_problems / self.total_problems * 100, 1)
+
+    @property
+    def easy_percentage(self) -> float:
+        """Calculate Easy solved percentage."""
+        if self.easy_total == 0:
+            return 0.0
+        return round(self.easy_solved / self.easy_total * 100, 1)
+
+    @property
+    def medium_percentage(self) -> float:
+        """Calculate Medium solved percentage."""
+        if self.medium_total == 0:
+            return 0.0
+        return round(self.medium_solved / self.medium_total * 100, 1)
+
+    @property
+    def hard_percentage(self) -> float:
+        """Calculate Hard solved percentage."""
+        if self.hard_total == 0:
+            return 0.0
+        return round(self.hard_solved / self.hard_total * 100, 1)
+
+
+class Config(DSAPBaseModel):
+    """User configuration settings.
+
+    Stored in ~/.dsap/config.json
+    """
+
+    daily_goal: Annotated[int, Field(ge=1, le=100)] = 5
+    preferred_difficulty: Difficulty | None = None
+    preferred_set: str | None = None
+    favorite_categories: list[str] = Field(default_factory=list)
+    show_hints: bool = True
+    auto_open_browser: bool = True
+    theme: str = "default"

dsap/problem_sets.py

@@ -0,0 +1,195 @@
+"""Problem Set Loader for DSAP.
+
+Handles loading problems from:
+- Bundled YAML files (Blind 75, NeetCode 150, Grind 75)
+- Custom user YAML files
+"""
+
+import logging
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from dsap.models import Difficulty, Problem
+
+
+logger = logging.getLogger(__name__)
+
+
+# Bundled problem sets
+BUNDLED_SETS: dict[str, str] = {
+    "blind75": "blind75.yaml",
+    "neetcode150": "neetcode150.yaml",
+    "grind75": "grind75.yaml",
+}
+
+# Descriptions for listing
+SET_DESCRIPTIONS: dict[str, str] = {
+    "blind75": "Blind 75 - The essential 75 LeetCode problems",
+    "neetcode150": "NeetCode 150 - Extended curated problem set",
+    "grind75": "Grind 75 - Flexible 75-question study plan",
+}
+
+
+def list_bundled_sets() -> dict[str, str]:
+    """List available bundled problem sets.
+
+    Returns:
+        Dict mapping set name to description
+    """
+    return SET_DESCRIPTIONS.copy()
+
+
+def get_bundled_path(set_name: str) -> Path:
+    """Get the path to a bundled problem set file.
+
+    Args:
+        set_name: Name of the set (e.g., "blind75")
+
+    Returns:
+        Path to the YAML file
+
+    Raises:
+        ValueError: If set_name is not a valid bundled set
+    """
+    if set_name not in BUNDLED_SETS:
+        available = ", ".join(BUNDLED_SETS.keys())
+        raise ValueError(f"Unknown problem set: '{set_name}'. Available: {available}")
+
+    try:
+        files = resources.files("dsap.data")
+        path = files.joinpath(BUNDLED_SETS[set_name])
+
+        with resources.as_file(path) as p:
+            return Path(p)
+    except (TypeError, AttributeError):
+        data_dir = Path(__file__).parent / "data"
+        return data_dir / BUNDLED_SETS[set_name]
+
+
+def load_problem_set(source: str) -> list[Problem]:
+    """Load problems from a YAML file or bundled set name.
+
+    Args:
+        source: Either a bundled set name (e.g., "blind75")
+               or a path to a custom YAML file
+
+    Returns:
+        List of Problem objects
+
+    Raises:
+        ValueError: If source is not valid
+        FileNotFoundError: If file doesn't exist
+    """
+    # Check if it's a bundled set name
+    if source.lower() in BUNDLED_SETS:
+        path = get_bundled_path(source.lower())
+    else:
+        path = Path(source)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Problem set file not found: {path}")
+
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    return parse_problem_set(data)
+
+
+def parse_problem_set(data: dict[str, Any]) -> list[Problem]:
+    """Parse YAML data structure into Problem objects.
+
+    Expected YAML structure:
+    ```yaml
+    metadata:
+      name: "Set Name"
+      description: "Description"
+    categories:
+      - name: "Category Name"
+        problems:
+          - title: "Problem Title"
+            url: "https://..."
+            difficulty: "Easy"
+            ...
+    ```
+
+    Args:
+        data: Parsed YAML data
+
+    Returns:
+        List of Problem objects
+    """
+    problems: list[Problem] = []
+
+    # Get metadata
+    metadata = data.get("metadata", {})
+    set_name = metadata.get("name", "custom")
+
+    # Track problem number across all categories
+    problem_number = 1
+
+    # Parse each category
+    for category in data.get("categories", []):
+        category_name = category.get("name", "Uncategorized")
+
+        for prob_data in category.get("problems", []):
+            try:
+                problem = Problem(
+                    title=prob_data["title"],
+                    url=prob_data["url"],
+                    difficulty=Difficulty.from_string(prob_data["difficulty"]),
+                    category=category_name,
+                    description=prob_data.get("description", ""),
+                    tags=prob_data.get("tags", []),
+                    problem_set=set_name,
+                    problem_number=problem_number,
+                    company_tags=prob_data.get("company_tags", []),
+                    hints=prob_data.get("hints", []),
+                )
+                problems.append(problem)
+                problem_number += 1
+            except (KeyError, ValueError, TypeError) as e:
+                title = prob_data.get("title", "Unknown")
+                logger.warning("Failed to parse problem '%s': %s", title, e)
+
+    return problems
+
+
+def create_custom_set(
+    name: str,
+    problems: list[dict[str, Any]],
+    output_path: Path,
+) -> None:
+    """Create a custom problem set YAML file.
+
+    Args:
+        name: Name of the problem set
+        problems: List of problem dictionaries
+        output_path: Where to save the YAML file
+    """
+    # Group problems by category
+    by_category: dict[str, list[dict[str, Any]]] = {}
+    for prob in problems:
+        cat = prob.get("category", "Custom")
+        if cat not in by_category:
+            by_category[cat] = []
+        by_category[cat].append(prob)
+
+    # Build YAML structure
+    data = {
+        "metadata": {
+            "name": name,
+            "description": f"Custom problem set: {name}",
+            "total_problems": len(problems),
+        },
+        "categories": [
+            {"name": cat, "problems": probs} for cat, probs in by_category.items()
+        ],
+    }
+
+    # Write to file
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)