studyforge-vocab 0.2.0__py3-none-any.whl

studyforge/__init__.py

@@ -0,0 +1,23 @@
+"""Reusable StudyForge PDF vocabulary extraction library."""
+
+__version__ = "0.2.0"
+
+from studyforge.api import StudyForge, analyze_pdf, analyze_pdf_bytes
+from studyforge.cefr import CEFR_LEVELS, CEFR_UNKNOWN, CEFRProfile
+from studyforge.exporter import export_rows, export_vocabulary
+from studyforge.models import AnalysisResult, PdfDocument, VocabularyItem
+
+__all__ = [
+    "AnalysisResult",
+    "CEFR_LEVELS",
+    "CEFR_UNKNOWN",
+    "CEFRProfile",
+    "PdfDocument",
+    "StudyForge",
+    "VocabularyItem",
+    "__version__",
+    "analyze_pdf",
+    "analyze_pdf_bytes",
+    "export_rows",
+    "export_vocabulary",
+]

studyforge/__main__.py

@@ -0,0 +1,4 @@
+from studyforge.cli import main
+
+
+raise SystemExit(main())

studyforge/api.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+from studyforge.cefr import CEFRProfile, default_cefr_profile
+from studyforge.dictionary import DictionaryStore
+from studyforge.models import AnalysisResult
+from studyforge.pdf_reader import MAX_PDF_BYTES, PdfReadError, extract_pdf_text
+from studyforge.resources import default_dictionary_path
+from studyforge.vocabulary import LEVEL_LABELS, analyze_vocabulary
+
+
+VALID_MODES = tuple(LEVEL_LABELS)
+
+
+class StudyForge:
+    """Reusable PDF vocabulary extraction service used by Web, CLI, and Python."""
+
+    def __init__(
+        self,
+        dictionary_path: str | PathLike[str] | None = None,
+        cefr_profile: CEFRProfile | None = None,
+    ):
+        self.dictionary = DictionaryStore(
+            Path(dictionary_path) if dictionary_path else default_dictionary_path()
+        )
+        self.cefr_profile = cefr_profile or default_cefr_profile()
+
+    def analyze_bytes(
+        self,
+        file_bytes: bytes,
+        *,
+        limit: int = 30,
+        mode: str = "balanced",
+        min_occurrences: int = 1,
+    ) -> AnalysisResult:
+        _validate_options(limit, mode, min_occurrences)
+        document = extract_pdf_text(file_bytes)
+        items = analyze_vocabulary(
+            document,
+            self.dictionary,
+            limit=limit,
+            level=mode,
+            min_occurrences=min_occurrences,
+            cefr_profile=self.cefr_profile,
+        )
+        return AnalysisResult(document=document, items=tuple(items), mode=mode)
+
+    def analyze_file(
+        self,
+        path: str | PathLike[str],
+        *,
+        limit: int = 30,
+        mode: str = "balanced",
+        min_occurrences: int = 1,
+    ) -> AnalysisResult:
+        pdf_path = Path(path).expanduser()
+        if not pdf_path.is_file():
+            raise FileNotFoundError(f"PDF file not found: {pdf_path}")
+        if pdf_path.stat().st_size > MAX_PDF_BYTES:
+            raise PdfReadError(
+                f"PDF exceeds the {MAX_PDF_BYTES // (1024 * 1024)} MB limit."
+            )
+        return self.analyze_bytes(
+            pdf_path.read_bytes(),
+            limit=limit,
+            mode=mode,
+            min_occurrences=min_occurrences,
+        )
+
+
+def analyze_pdf(
+    path: str | PathLike[str],
+    *,
+    limit: int = 30,
+    mode: str = "balanced",
+    min_occurrences: int = 1,
+    dictionary_path: str | PathLike[str] | None = None,
+    cefr_profile: CEFRProfile | None = None,
+) -> AnalysisResult:
+    """Analyze a PDF file with the bundled core library."""
+    return StudyForge(dictionary_path, cefr_profile).analyze_file(
+        path,
+        limit=limit,
+        mode=mode,
+        min_occurrences=min_occurrences,
+    )
+
+
+def analyze_pdf_bytes(
+    file_bytes: bytes,
+    *,
+    limit: int = 30,
+    mode: str = "balanced",
+    min_occurrences: int = 1,
+    dictionary_path: str | PathLike[str] | None = None,
+    cefr_profile: CEFRProfile | None = None,
+) -> AnalysisResult:
+    """Analyze in-memory PDF bytes with the bundled core library."""
+    return StudyForge(dictionary_path, cefr_profile).analyze_bytes(
+        file_bytes,
+        limit=limit,
+        mode=mode,
+        min_occurrences=min_occurrences,
+    )
+
+
+def _validate_options(limit: int, mode: str, min_occurrences: int) -> None:
+    if not isinstance(limit, int) or not 1 <= limit <= 500:
+        raise ValueError("limit must be an integer between 1 and 500.")
+    if mode not in VALID_MODES:
+        raise ValueError(f"mode must be one of: {', '.join(VALID_MODES)}.")
+    if not isinstance(min_occurrences, int) or not 1 <= min_occurrences <= 100:
+        raise ValueError("min_occurrences must be an integer between 1 and 100.")

studyforge/cefr.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Mapping
+
+from studyforge.resources import default_cefr_path
+
+
+CEFR_LEVELS = ("A1", "A2", "B1", "B2", "C1", "C2")
+CEFR_UNKNOWN = "unknown"
+_VALID_WORD = re.compile(r"^[a-z]+(?:['-][a-z]+)*$")
+
+
+def normalize_cefr_word(word: str) -> str:
+    return word.replace("’", "'").strip().lower()
+
+
+class CEFRProfile:
+    """Reliable word-level CEFR lookups with explicit unknown fallbacks."""
+
+    def __init__(self, levels: Mapping[str, str] | None = None):
+        normalized: dict[str, str] = {}
+        for word, level in (levels or {}).items():
+            normalized_word = normalize_cefr_word(word)
+            normalized_level = str(level).upper()
+            if _VALID_WORD.fullmatch(normalized_word) and normalized_level in CEFR_LEVELS:
+                normalized[normalized_word] = normalized_level
+        self._levels = normalized
+
+    @classmethod
+    def from_json(cls, path: str | Path) -> "CEFRProfile":
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        levels = data.get("levels", data)
+        if not isinstance(levels, dict):
+            raise ValueError("CEFR data must contain a 'levels' object.")
+        return cls(levels)
+
+    @classmethod
+    def from_mapping(cls, levels: Mapping[str, str]) -> "CEFRProfile":
+        return cls(levels)
+
+    def level_for(self, word: str) -> str:
+        """Return A1-C2 only for a known unambiguous entry; otherwise unknown."""
+        return self._levels.get(normalize_cefr_word(word), CEFR_UNKNOWN)
+
+    def classify_many(self, words: list[str] | tuple[str, ...]) -> dict[str, str]:
+        return {word: self.level_for(word) for word in words}
+
+    @property
+    def known_word_count(self) -> int:
+        return len(self._levels)
+
+
+@lru_cache(maxsize=1)
+def default_cefr_profile() -> CEFRProfile:
+    path = default_cefr_path()
+    if not path.is_file():
+        return CEFRProfile()
+    return CEFRProfile.from_json(path)

studyforge/cli.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from studyforge import __version__
+from studyforge.api import StudyForge, VALID_MODES
+from studyforge.exporter import EXPORT_FORMATS, export_vocabulary, output_suffix
+from studyforge.pdf_reader import PdfReadError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="studyforge",
+        description="Extract study vocabulary from English PDF files.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    extract = subparsers.add_parser(
+        "extract",
+        help="Extract vocabulary from a PDF.",
+    )
+    extract.add_argument("pdf", type=Path, help="Input PDF path.")
+    extract.add_argument("--limit", type=int, default=30, help="Maximum word count.")
+    extract.add_argument(
+        "--format",
+        choices=EXPORT_FORMATS,
+        default="anki",
+        help="Output format (default: anki).",
+    )
+    extract.add_argument(
+        "--mode",
+        choices=VALID_MODES,
+        default="balanced",
+        help="Vocabulary ranking mode, including ielts.",
+    )
+    extract.add_argument(
+        "--min-occurrences",
+        type=int,
+        default=1,
+        help="Minimum occurrences in the PDF.",
+    )
+    extract.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="Output path. Use '-' to write to stdout.",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command != "extract":
+        parser.error("A command is required.")
+
+    try:
+        result = StudyForge().analyze_file(
+            args.pdf,
+            limit=args.limit,
+            mode=args.mode,
+            min_occurrences=args.min_occurrences,
+        )
+        data = export_vocabulary(result.items, args.format)
+        output = args.output or _default_output_path(args.pdf, args.format)
+        if output == "-":
+            sys.stdout.buffer.write(data)
+            return 0
+
+        output_path = Path(output).expanduser()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(data)
+        print(f"Created {output_path} with {len(result.items)} vocabulary items.")
+        return 0
+    except (FileNotFoundError, PdfReadError, ValueError, OSError) as exc:
+        print(f"studyforge: error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _default_output_path(pdf_path: Path, export_format: str) -> str:
+    safe_stem = re.sub(r"[^\w.-]+", "_", pdf_path.stem, flags=re.UNICODE).strip("._")
+    suffix = output_suffix(export_format)
+    return f"{safe_stem or 'studyforge'}_{export_format}{suffix}"

studyforge/data/__init__.py

@@ -0,0 +1 @@
+"""Bundled, read-only StudyForge data files."""