philoch-bib-sdk 0.3.9__cp313-cp313-macosx_10_12_x86_64.whl

philoch_bib_sdk/adapters/io/__init__.py

@@ -0,0 +1,115 @@
+"""IO adapters with automatic format detection.
+
+This module provides format-agnostic wrappers that detect file formats
+and delegate to appropriate format-specific adapters.
+"""
+
+from pathlib import Path
+from typing import Dict, Tuple
+
+from aletk.ResultMonad import Err, Ok
+
+from philoch_bib_sdk.adapters.io.csv import (
+    load_bibliography_csv,
+    load_staged_csv,
+    write_report_csv,
+)
+from philoch_bib_sdk.adapters.io.ods import (
+    load_bibliography_ods,
+    load_staged_ods,
+)
+from philoch_bib_sdk.logic.models import BibItem
+from philoch_bib_sdk.logic.models_staging import BibItemStaged
+
+
+def load_bibliography(filename: str, max_rows: int | None = None) -> Ok[Dict[str, BibItem]] | Err:
+    """Load bibliography with automatic format detection.
+
+    Detects format based on file extension and delegates to appropriate adapter.
+
+    Supported formats:
+    - .csv: CSV format
+    - .ods: OpenDocument Spreadsheet format
+
+    Args:
+        filename: Path to bibliography file
+        max_rows: Optional limit on number of rows (for testing large files)
+
+    Returns:
+        Ok[Dict[str, BibItem]] with bibkey as key, or Err on failure
+    """
+    file_path = Path(filename)
+    suffix = file_path.suffix.lower()
+
+    match suffix:
+        case ".csv":
+            return load_bibliography_csv(filename)
+        case ".ods":
+            return load_bibliography_ods(filename, max_rows=max_rows)
+        case _:
+            return Err(
+                message=f"Unsupported bibliography format: {suffix}. Supported: .csv, .ods",
+                code=-1,
+                error_type="UnsupportedFormatError",
+            )
+
+
+def load_staged(filename: str, max_rows: int | None = None) -> Ok[Tuple[BibItem, ...]] | Err:
+    """Load staged items with automatic format detection.
+
+    Detects format based on file extension and delegates to appropriate adapter.
+
+    Supported formats:
+    - .csv: CSV format
+    - .ods: OpenDocument Spreadsheet format
+
+    Args:
+        filename: Path to staged items file
+        max_rows: Optional limit on number of rows (for testing large files)
+
+    Returns:
+        Ok[Tuple[BibItem, ...]] or Err on failure
+    """
+    file_path = Path(filename)
+    suffix = file_path.suffix.lower()
+
+    match suffix:
+        case ".csv":
+            return load_staged_csv(filename)
+        case ".ods":
+            return load_staged_ods(filename, max_rows=max_rows)
+        case _:
+            return Err(
+                message=f"Unsupported staged items format: {suffix}. Supported: .csv, .ods",
+                code=-1,
+                error_type="UnsupportedFormatError",
+            )
+
+
+def write_report(filename: str, staged: Tuple[BibItemStaged, ...], output_format: str = "csv") -> Ok[None] | Err:
+    """Write fuzzy matching report with format selection.
+
+    Args:
+        filename: Path to output file (extension will be added based on format)
+        staged: Tuple of staged items with matches
+        output_format: Output format ("csv", etc.)
+
+    Returns:
+        Ok[None] on success, Err on failure
+    """
+    match output_format.lower():
+        case "csv":
+            return write_report_csv(filename, staged)
+        case _:
+            return Err(
+                message=f"Unsupported output format: {output_format}. Supported: csv",
+                code=-1,
+                error_type="UnsupportedFormatError",
+            )
+
+
+__all__ = [
+    "load_bibliography",
+    "load_staged",
+    "write_report",
+]

philoch_bib_sdk/adapters/io/csv/__init__.py

@@ -0,0 +1,308 @@
+"""CSV adapters for reading and writing bibliographic data.
+
+This module provides CSV-specific implementations for loading bibliographies,
+staged items, and writing fuzzy matching reports.
+"""
+
+import csv
+import traceback
+from pathlib import Path
+from typing import Any, Dict, Tuple
+
+from aletk.ResultMonad import Err, Ok
+from aletk.utils import get_logger
+
+from philoch_bib_sdk.converters.plaintext.bibitem.bibkey_formatter import format_bibkey
+from philoch_bib_sdk.converters.plaintext.bibitem.parser import (
+    ParsedBibItemData,
+    parse_bibitem,
+)
+from philoch_bib_sdk.logic.models import BibItem
+from philoch_bib_sdk.logic.models_staging import BibItemStaged
+
+logger = get_logger(__name__)
+
+
+def _csv_row_to_parsed_data(row: dict[str, Any]) -> ParsedBibItemData:
+    """Convert CSV row to ParsedBibItemData, filtering empty values.
+
+    Args:
+        row: Dictionary from csv.DictReader
+
+    Returns:
+        ParsedBibItemData with empty values removed
+    """
+    # Filter out empty values and create ParsedBibItemData
+    # TypedDict with total=False allows any subset of fields
+    return {k: v for k, v in row.items() if v}  # type: ignore[return-value]
+
+
+def load_bibliography_csv(filename: str) -> Ok[Dict[str, BibItem]] | Err:
+    """Load bibliography from CSV file.
+
+    Expected CSV format: Standard CSV with headers matching ParsedBibItemData fields.
+    Required columns: entry_type, author, title, date
+    Optional columns: journal, volume, number, pages, doi, etc.
+
+    Args:
+        filename: Path to CSV file
+
+    Returns:
+        Ok[Dict[str, BibItem]] with bibkey as key, or Err on failure
+    """
+    try:
+        file_path = Path(filename)
+        if not file_path.exists():
+            return Err(
+                message=f"File not found: {filename}",
+                code=-1,
+                error_type="FileNotFoundError",
+            )
+
+        bibliography: Dict[str, BibItem] = {}
+        errors = []
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+
+            if reader.fieldnames is None:
+                return Err(
+                    message=f"CSV file has no headers: {filename}",
+                    code=-1,
+                    error_type="CSVFormatError",
+                )
+
+            for row_num, row in enumerate(reader, start=2):  # Start at 2 (header is row 1)
+                # Convert CSV row to ParsedBibItemData
+                parsed_data = _csv_row_to_parsed_data(row)
+
+                # Parse the row into a BibItem
+                parse_result = parse_bibitem(parsed_data, bibstring_type="simplified")
+
+                if isinstance(parse_result, Err):
+                    errors.append(f"Row {row_num}: {parse_result.message}")
+                    continue
+
+                bibitem = parse_result.out
+                bibkey = format_bibkey(bibitem.bibkey)
+
+                # Check for duplicate bibkeys
+                if bibkey in bibliography:
+                    errors.append(f"Row {row_num}: Duplicate bibkey '{bibkey}' (first seen in earlier row)")
+                    continue
+
+                bibliography[bibkey] = bibitem
+
+        # Report results
+        if errors:
+            error_summary = f"Loaded {len(bibliography)} items with {len(errors)} errors:\n" + "\n".join(
+                errors[:10]  # Show first 10 errors
+            )
+            if len(errors) > 10:
+                error_summary += f"\n... and {len(errors) - 10} more errors"
+
+            logger.warning(error_summary)
+
+        if not bibliography:
+            return Err(
+                message=f"No valid items loaded from {filename}. Errors: {len(errors)}",
+                code=-1,
+                error_type="EmptyBibliographyError",
+            )
+
+        logger.info(f"Successfully loaded {len(bibliography)} items from {filename}")
+        return Ok(bibliography)
+
+    except Exception as e:
+        return Err(
+            message=f"Failed to load bibliography from {filename}: {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type=e.__class__.__name__,
+            error_trace=traceback.format_exc(),
+        )
+
+
+def load_staged_csv_allow_empty_bibkeys(filename: str) -> Ok[Tuple[BibItem, ...]] | Err:
+    """Load staged items from CSV file, allowing empty bibkeys.
+
+    This is useful for staging files where bibkeys haven't been assigned yet.
+    Items without bibkeys will be assigned temporary sequential keys.
+
+    Args:
+        filename: Path to CSV file
+
+    Returns:
+        Ok[Tuple[BibItem, ...]] or Err on failure
+    """
+    try:
+        file_path = Path(filename)
+
+        if not file_path.exists():
+            return Err(
+                message=f"File not found: {filename}",
+                code=-1,
+                error_type="FileNotFoundError",
+            )
+
+        staged_items: list[BibItem] = []
+        errors = []
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+
+            if reader.fieldnames is None:
+                return Err(
+                    message=f"CSV file has no headers: {filename}",
+                    code=-1,
+                    error_type="CSVFormatError",
+                )
+
+            for row_num, row in enumerate(reader, start=2):  # Start at 2 (header is row 1)
+                # Convert CSV row to ParsedBibItemData
+                parsed_data = _csv_row_to_parsed_data(row)
+
+                # If bibkey is empty, assign a temporary one
+                if not parsed_data.get("bibkey"):
+                    parsed_data["bibkey"] = f"temp:{row_num}"
+
+                # Parse the row into a BibItem
+                parse_result = parse_bibitem(parsed_data, bibstring_type="simplified")
+
+                if isinstance(parse_result, Err):
+                    errors.append(f"Row {row_num}: {parse_result.message}")
+                    continue
+
+                bibitem = parse_result.out
+                staged_items.append(bibitem)
+
+        # Report results
+        if errors:
+            error_summary = f"Loaded {len(staged_items)} items with {len(errors)} errors:\n" + "\n".join(
+                errors[:10]  # Show first 10 errors
+            )
+            if len(errors) > 10:
+                error_summary += f"\n... and {len(errors) - 10} more errors"
+
+            logger.warning(error_summary)
+
+        if not staged_items:
+            return Err(
+                message=f"No valid items loaded from {filename}. Errors: {len(errors)}",
+                code=-1,
+                error_type="EmptyFileError",
+            )
+
+        logger.info(f"Successfully loaded {len(staged_items)} staged items from {filename}")
+
+        return Ok(tuple(staged_items))
+
+    except Exception as e:
+        return Err(
+            message=f"Failed to load staged items from {filename}: {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type=e.__class__.__name__,
+            error_trace=traceback.format_exc(),
+        )
+
+
+def load_staged_csv(filename: str) -> Ok[Tuple[BibItem, ...]] | Err:
+    """Load staged items from CSV file.
+
+    Uses the same format as load_bibliography_csv - standard CSV with ParsedBibItemData fields.
+    Additional score-related columns (if present) are ignored during loading.
+
+    Args:
+        filename: Path to CSV file
+
+    Returns:
+        Ok[Tuple[BibItem, ...]] or Err on failure
+    """
+    try:
+        # Load as bibliography first
+        result = load_bibliography_csv(filename)
+
+        if isinstance(result, Err):
+            return result
+
+        bibliography = result.out
+
+        # Convert dict values to tuple
+        staged_items = tuple(bibliography.values())
+
+        logger.info(f"Successfully loaded {len(staged_items)} staged items from {filename}")
+        return Ok(staged_items)
+
+    except Exception as e:
+        return Err(
+            message=f"Failed to load staged items from {filename}: {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type=e.__class__.__name__,
+            error_trace=traceback.format_exc(),
+        )
+
+
+def write_report_csv(filename: str, staged: Tuple[BibItemStaged, ...]) -> Ok[None] | Err:
+    """Write fuzzy matching report to CSV file.
+
+    Output format: Uses BibItemStaged.to_csv_row() with columns:
+    - staged_bibkey, staged_title, staged_author, staged_year
+    - num_matches, best_match_score, best_match_bibkey
+    - top_matches_json (JSON-encoded match details)
+    - search_time_ms, candidates_searched
+
+    Args:
+        filename: Path to output CSV file (without extension)
+        staged: Tuple of staged items with matches
+
+    Returns:
+        Ok[None] on success, Err on failure
+    """
+    try:
+        # Add .csv extension if not present
+        output_path = Path(filename)
+        if output_path.suffix != ".csv":
+            output_path = output_path.with_suffix(".csv")
+
+        if not staged:
+            logger.warning("No staged items to write")
+            # Create empty file with headers
+            with open(output_path, "w", encoding="utf-8", newline="") as f:
+                simple_writer = csv.writer(f)
+                simple_writer.writerow(
+                    [
+                        "staged_bibkey",
+                        "staged_title",
+                        "staged_author",
+                        "staged_year",
+                        "num_matches",
+                        "best_match_score",
+                        "best_match_bibkey",
+                        "top_matches_json",
+                        "search_time_ms",
+                        "candidates_searched",
+                    ]
+                )
+            logger.info(f"Created empty report at {output_path}")
+            return Ok(None)
+
+        # Convert to CSV rows
+        rows = tuple(item.to_csv_row() for item in staged)
+
+        # Write to CSV
+        with open(output_path, "w", encoding="utf-8", newline="") as f:
+            if rows:
+                fieldnames = list(rows[0].keys())
+                dict_writer = csv.DictWriter(f, fieldnames=fieldnames)
+                dict_writer.writeheader()
+                dict_writer.writerows(rows)
+
+        logger.info(f"Successfully wrote {len(staged)} items to {output_path}")
+        return Ok(None)
+
+    except Exception as e:
+        return Err(
+            message=f"Failed to write report to {filename}: {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type=e.__class__.__name__,
+            error_trace=traceback.format_exc(),
+        )

philoch_bib_sdk/adapters/io/ods/__init__.py

@@ -0,0 +1,145 @@
+"""ODS (OpenDocument Spreadsheet) adapters for bibliography I/O operations."""
+
+import traceback
+from typing import Dict, Tuple, Any
+from pathlib import Path
+
+from aletk.ResultMonad import Ok, Err
+from aletk.utils import get_logger
+
+from philoch_bib_sdk.logic.models import BibItem
+from philoch_bib_sdk.converters.plaintext.bibitem.parser import parse_bibitem, ParsedBibItemData
+from philoch_bib_sdk.converters.plaintext.bibitem.bibkey_formatter import format_bibkey
+
+lgr = get_logger(__name__)
+
+__all__: list[str] = [
+    "load_bibliography_ods",
+    "load_staged_ods",
+]
+
+
+def _normalize_column_name(name: str) -> str:
+    """
+    Normalize column names from ODS to match ParsedBibItemData keys.
+
+    ODS columns use hyphens (e.g., 'journal-id') while ParsedBibItemData uses underscores.
+    """
+    return name.replace("-", "_")
+
+
+def _ods_row_to_parsed_data(row: dict[str, Any]) -> ParsedBibItemData:
+    """
+    Convert an ODS row (dict) to ParsedBibItemData.
+
+    This helper exists to isolate the type: ignore directive.
+    Polars returns dict[str, Any] while ParsedBibItemData is a TypedDict.
+    We filter out None/empty values and normalize column names.
+    """
+    normalized = {_normalize_column_name(k): str(v) if v is not None else "" for k, v in row.items()}
+    return {k: v for k, v in normalized.items() if v}  # type: ignore[return-value]
+
+
+def load_bibliography_ods(
+    filename: str, max_rows: int | None = None, bibstring_type: str = "simplified"
+) -> Ok[Dict[str, BibItem]] | Err:
+    """
+    Load a bibliography from an ODS file.
+
+    Args:
+        filename: Path to the ODS file
+        max_rows: Optional limit on number of rows to read (for testing)
+        bibstring_type: Type of bibstring to use ('simplified', 'latex', 'unicode')
+
+    Returns:
+        Ok with dict mapping bibkey -> BibItem, or Err with details
+    """
+    try:
+        import polars as pl
+
+        if not Path(filename).exists():
+            return Err(message=f"File not found: {filename}", code=1)
+
+        # Read ODS file
+        df = pl.read_ods(source=filename, has_header=True)
+
+        if df.is_empty():
+            return Err(message=f"ODS file is empty: {filename}", code=1)
+
+        # Limit rows if requested
+        if max_rows is not None:
+            df = df.head(max_rows)
+
+        # Convert to list of dicts
+        rows = df.to_dicts()
+
+        bibliography: dict[str, BibItem] = {}
+        errors: list[str] = []
+        seen_bibkeys: dict[str, int] = {}
+
+        for i, row in enumerate(rows, start=2):  # Start at 2 because row 1 is header
+            try:
+                parsed_data = _ods_row_to_parsed_data(row)
+                result = parse_bibitem(parsed_data, bibstring_type=bibstring_type)  # type: ignore[arg-type]
+
+                if isinstance(result, Err):
+                    errors.append(f"Row {i}: {result.message}")
+                    continue
+
+                bibitem = result.out
+                bibkey_str = format_bibkey(bibitem.bibkey)
+
+                # Check for duplicates
+                if bibkey_str in seen_bibkeys:
+                    first_row = seen_bibkeys[bibkey_str]
+                    errors.append(f"Row {i}: Duplicate bibkey '{bibkey_str}' (first seen in row {first_row})")
+                    continue
+
+                bibliography[bibkey_str] = bibitem
+                seen_bibkeys[bibkey_str] = i
+
+            except Exception as e:
+                errors.append(f"Row {i}: Unexpected error: {e}")
+                continue
+
+        if errors:
+            lgr.warning(f"Loaded {len(bibliography)} items with {len(errors)} errors:\n" + "\n".join(errors[:10]))
+
+        if not bibliography:
+            error_summary = "\n".join(errors[:5])
+            return Err(message=f"No valid items loaded from {filename}. Errors: {len(errors)}\n{error_summary}", code=1)
+
+        lgr.info(f"Successfully loaded {len(bibliography)} items from {filename}")
+        return Ok(bibliography)
+
+    except Exception as e:
+        return Err(
+            message=f"Failed to load bibliography from {filename}: {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type=e.__class__.__name__,
+            error_trace=traceback.format_exc(),
+        )
+
+
+def load_staged_ods(filename: str, max_rows: int | None = None) -> Ok[Tuple[BibItem, ...]] | Err:
+    """
+    Load staged BibItems from an ODS file.
+
+    Args:
+        filename: Path to the ODS file
+        max_rows: Optional limit on number of rows to read (for testing)
+
+    Returns:
+        Ok with tuple of BibItems, or Err with details
+    """
+    result = load_bibliography_ods(filename, max_rows=max_rows)
+
+    if isinstance(result, Err):
+        return result
+
+    bibliography = result.out
+    staged_items = tuple(bibliography.values())
+
+    lgr.info(f"Successfully loaded {len(staged_items)} staged items from {filename}")
+
+    return Ok(staged_items)

philoch_bib_sdk/adapters/tabular_data/read_journal_volume_number_index.py

@@ -0,0 +1,58 @@
+from functools import partial
+from typing import Callable, NamedTuple
+
+import polars as pl
+
+from philoch_bib_sdk.converters.plaintext.bibitem.bibkey_parser import hard_parse_bibkey
+from philoch_bib_sdk.logic.functions.journal_article_matcher import (
+    TJournalBibkeyIndex,
+    TReadIndex,
+)
+
+
+class ColumnNames(NamedTuple):
+    bibkey: str
+    journal: str
+    volume: str
+    number: str
+
+
+def _read_from_ods(
+    column_names: ColumnNames,
+    file_path: str,
+) -> TJournalBibkeyIndex:
+    """
+    Reads the specified columns from an ODS file and returns a TJournalBibkeyIndex dictionary.
+    Args:
+        column_names (ColumnNames): The names of the columns to read (journal, volume, number, bibkey).
+        file_path (str): The path to the ODS file.
+    Returns:
+        TJournalBibkeyIndex: A dictionary mapping (journal, volume, number) tuples to bibkey values.
+    """
+    df = pl.read_ods(
+        source=file_path,
+        has_header=True,
+        columns=[column_names.journal, column_names.volume, column_names.number, column_names.bibkey],
+        schema_overrides={
+            column_names.journal: pl.Utf8,
+            column_names.volume: pl.Utf8,
+            column_names.number: pl.Utf8,
+            column_names.bibkey: pl.Utf8,
+        },
+    )
+
+    if df.is_empty():
+        raise ValueError(
+            f"Tabular data at '{file_path}' is empty or does not contain the expected columns: {column_names}"
+        )
+
+    return {
+        (row[column_names.journal], row[column_names.volume], row[column_names.number]): hard_parse_bibkey(
+            row[column_names.bibkey]
+        )
+        for row in df.to_dicts()
+    }
+
+
+type THOFReadFromOds = Callable[[ColumnNames], TReadIndex]
+hof_read_from_ods: THOFReadFromOds = lambda column_names: partial(_read_from_ods, column_names)

philoch_bib_sdk/converters/latex.py

@@ -0,0 +1,6 @@
+def unicode_to_latex(unicode_str: str) -> str:
+    raise NotImplementedError("This function is not implemented yet.")
+
+
+def latex_to_unicode(latex_str: str) -> str:
+    raise NotImplementedError("This function is not implemented yet.")

philoch_bib_sdk/converters/plaintext/author/formatter.py

@@ -0,0 +1,34 @@
+from typing import Tuple
+from aletk.utils import get_logger
+from philoch_bib_sdk.logic.models import Author, TBibString
+
+lgr = get_logger(__name__)
+
+
+def _full_name_generic(given_name: str, family_name: str, mononym: str) -> str:
+    if mononym:
+        return mononym
+
+    if not given_name and family_name:
+        return family_name
+
+    if not given_name:
+        return ""
+
+    if not family_name:
+        return given_name
+
+    return f"{family_name}, {given_name}"
+
+
+def _format_single(author: Author, bibstring_type: TBibString) -> str:
+    given_name = f"{getattr(author.given_name, bibstring_type)}"
+    family_name = f"{getattr(author.family_name, bibstring_type)}"
+    mononym = f"{getattr(author.mononym, bibstring_type)}"
+
+    return _full_name_generic(given_name, family_name, mononym)
+
+
+def format_author(authors: Tuple[Author, ...], bibstring_type: TBibString) -> str:
+    names = (_format_single(author, bibstring_type=bibstring_type) for author in authors)
+    return " and ".join(name for name in names if name)