"""TRREB PDF parser for monthly market watch reports.

This module provides the structure for parsing TRREB (Toronto Regional Real Estate Board)
monthly Market Watch PDF reports into structured data.
"""

from pathlib import Path
from typing import Any

from portfolio_app.toronto.schemas import TRREBMonthlyRecord, TRREBMonthlyReport


class TRREBParser:
    """Parser for TRREB Market Watch PDF reports.

    TRREB publishes monthly Market Watch reports as PDFs containing:
    - Summary statistics by area (416, 905, Total)
    - District-level breakdowns
    - Year-over-year comparisons

    The parser extracts tabular data from these PDFs and validates
    against the TRREBMonthlyRecord schema.
    """

    def __init__(self, pdf_path: Path) -> None:
        """Initialize parser with path to PDF file.

        Args:
            pdf_path: Path to the TRREB Market Watch PDF file.
        """
        self.pdf_path = pdf_path
        self._validate_path()

    def _validate_path(self) -> None:
        """Validate that the PDF path exists and is readable."""
        if not self.pdf_path.exists():
            raise FileNotFoundError(f"PDF not found: {self.pdf_path}")
        if not self.pdf_path.suffix.lower() == ".pdf":
            raise ValueError(f"Expected PDF file, got: {self.pdf_path.suffix}")

    def parse(self) -> TRREBMonthlyReport:
        """Parse the PDF and return structured data.

        Returns:
            TRREBMonthlyReport containing all extracted records.

        Raises:
            NotImplementedError: PDF parsing not yet implemented.
        """
        raise NotImplementedError(
            "PDF parsing requires pdfplumber/tabula-py. "
            "Implementation pending Sprint 4 data ingestion."
        )

    def _extract_tables(self) -> list[dict[str, Any]]:
        """Extract raw tables from PDF pages.

        Returns:
            List of dictionaries representing table data.
        """
        raise NotImplementedError("Table extraction not yet implemented.")

    def _parse_district_table(
        self, table_data: list[dict[str, Any]]
    ) -> list[TRREBMonthlyRecord]:
        """Parse district-level statistics table.

        Args:
            table_data: Raw table data extracted from PDF.

        Returns:
            List of validated TRREBMonthlyRecord objects.
        """
        raise NotImplementedError("District table parsing not yet implemented.")

    def _infer_report_date(self) -> tuple[int, int]:
        """Infer report year and month from PDF filename or content.

        Returns:
            Tuple of (year, month).
        """
        raise NotImplementedError("Date inference not yet implemented.")