cv-study-utils 0.1.0__py3-none-any.whl

cv_study_utils/__init__.py

@@ -0,0 +1,25 @@
+"""Convenient helpers for the computer vision exam materials."""
+
+from .api import (
+    all_practice,
+    all_theory,
+    copy_practice,
+    copy_theory,
+    find,
+    list_practice,
+    list_theory,
+    practice,
+    theory,
+)
+
+__all__ = [
+    "all_practice",
+    "all_theory",
+    "copy_practice",
+    "copy_theory",
+    "find",
+    "list_practice",
+    "list_theory",
+    "practice",
+    "theory",
+]

cv_study_utils/api.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import difflib
+import html
+import json
+import re
+import textwrap
+from typing import Any, Iterable
+
+from .practice_solutions import PRACTICE
+from .theory_answers import THEORY
+from .theory_extras import THEORY_EXTRAS
+
+
+def _normalize(text: str) -> str:
+    return re.sub(r"\s+", " ", text.casefold()).strip()
+
+
+def _score(query: str, item_text: str) -> float:
+    q = _normalize(query)
+    hay = _normalize(item_text)
+    if not q:
+        return 0.0
+    if q in hay:
+        return 1.0
+    words = [w for w in re.split(r"\W+", q) if len(w) > 2]
+    if words:
+        overlap = sum(1 for w in words if w in hay) / len(words)
+    else:
+        overlap = 0.0
+    ratio = difflib.SequenceMatcher(None, q, hay[: max(200, len(q) * 4)]).ratio()
+    return max(overlap, ratio)
+
+
+def _item_text(item: dict[str, Any], kind: str) -> str:
+    if kind == "theory":
+        extra = THEORY_EXTRAS.get(item["id"], {})
+        formulae = " ".join(extra.get("formulae", []))
+        structure = " ".join(extra.get("structure", []))
+        return f"{item['question']} {item['answer']} {formulae} {structure}"
+    return f"{item['task']} {item['description']} {item['code']}"
+
+
+def _title_text(item: dict[str, Any]) -> str:
+    return item.get("question") or item.get("task") or ""
+
+
+def _rank_score(query: str, item: dict[str, Any], kind: str) -> float:
+    base = _score(query, _item_text(item, kind))
+    q = _normalize(query)
+    title = _normalize(_title_text(item))
+    if q and q in title:
+        base += 0.75
+    return base
+
+
+def _get_by_number(items: list[dict[str, Any]], number: int) -> dict[str, Any]:
+    for item in items:
+        if item["id"] == number:
+            return item
+    raise ValueError(f"Нет элемента с номером {number}.")
+
+
+def _best_match(items: list[dict[str, Any]], query: str, kind: str) -> dict[str, Any]:
+    ranked = sorted(
+        ((_rank_score(query, item, kind), item) for item in items),
+        key=lambda pair: pair[0],
+        reverse=True,
+    )
+    if not ranked or ranked[0][0] < 0.18:
+        raise ValueError(f"Ничего не найдено по запросу: {query!r}.")
+    return ranked[0][1]
+
+
+def _display_markdown(markdown: str) -> None:
+    try:
+        from IPython.display import Markdown, display
+
+        display(Markdown(markdown))
+    except Exception:
+        print(markdown)
+
+
+def _display_code(code: str) -> None:
+    try:
+        from IPython.display import Markdown, display
+
+        display(Markdown("```python\n" + code.strip() + "\n```"))
+    except Exception:
+        print(code)
+
+
+def copy_text(text: str) -> str:
+    """Copy text if possible; in notebooks, fall back to a Copy button."""
+    try:
+        import pyperclip
+
+        pyperclip.copy(text)
+        return "clipboard"
+    except Exception:
+        pass
+
+    try:
+        from IPython.display import HTML, display
+
+        payload = json.dumps(text)
+        display(
+            HTML(
+                """
+                <button style="padding:6px 10px;border:1px solid #888;border-radius:6px"
+                        onclick='navigator.clipboard.writeText(%s); this.textContent="Copied";'>
+                    Copy answer
+                </button>
+                """
+                % payload
+            )
+        )
+        return "button"
+    except Exception as exc:
+        raise RuntimeError(
+            "Не удалось скопировать текст. Установите pyperclip или используйте Jupyter/Colab."
+        ) from exc
+
+
+def _format_theory_item(item: dict[str, Any]) -> str:
+    extra = THEORY_EXTRAS.get(item["id"], {})
+    parts = [f"### {item['id']}. {item['question']}", "", item["answer"]]
+    if extra.get("formulae"):
+        parts.extend(["", "**Формулы:**"])
+        parts.extend(f"- {line}" for line in extra["formulae"])
+    if extra.get("structure"):
+        parts.extend(["", "**Структура / схема:**"])
+        parts.extend(f"- {line}" for line in extra["structure"])
+    sources = ", ".join([*item.get("sources", []), *extra.get("sources", [])])
+    source_line = f"\n\nИсточники: {sources}" if sources else ""
+    return "\n".join(parts) + source_line
+
+
+def _format_practice_item(item: dict[str, Any], include_task: bool = True) -> str:
+    header = ""
+    if include_task:
+        header = (
+            f"# Практика {item['id']}. {item['task']}\n"
+            f"# {item['description']}\n\n"
+        )
+    return header + item["code"].strip() + "\n"
+
+
+def list_theory(display: bool = True) -> str:
+    text = "\n".join(f"{item['id']}. {item['question']}" for item in THEORY)
+    if display:
+        _display_markdown(text)
+    return text
+
+
+def list_practice(display: bool = True) -> str:
+    text = "\n".join(f"{item['id']}. {item['task']}" for item in PRACTICE)
+    if display:
+        _display_markdown(text)
+    return text
+
+
+def theory(
+    number: int | str | None = None,
+    *,
+    query: str | None = None,
+    copy: bool = False,
+    display: bool = True,
+) -> str:
+    """Show a theory answer by number or approximate query."""
+    if isinstance(number, str) and query is None:
+        query = number
+        number = None
+    if number is None and query is None:
+        return list_theory(display=display)
+    item = _best_match(THEORY, query, "theory") if query else _get_by_number(THEORY, int(number))
+    text = _format_theory_item(item)
+    if copy:
+        copy_text(text)
+    if display:
+        _display_markdown(text)
+    return text
+
+
+def practice(
+    number: int | str | None = None,
+    *,
+    query: str | None = None,
+    copy: bool = False,
+    display: bool = True,
+    include_task: bool = True,
+) -> str:
+    """Show a practical code template by number or approximate query."""
+    if isinstance(number, str) and query is None:
+        query = number
+        number = None
+    if number is None and query is None:
+        return list_practice(display=display)
+    item = _best_match(PRACTICE, query, "practice") if query else _get_by_number(PRACTICE, int(number))
+    code = _format_practice_item(item, include_task=include_task)
+    if copy:
+        copy_text(code)
+    if display:
+        _display_code(code)
+    return code
+
+
+def find(query: str, *, kind: str = "all", limit: int = 8, display: bool = True) -> list[dict[str, Any]]:
+    """Search theory and/or practice by a text fragment."""
+    pools: list[tuple[str, list[dict[str, Any]]]] = []
+    if kind in {"all", "theory"}:
+        pools.append(("theory", THEORY))
+    if kind in {"all", "practice"}:
+        pools.append(("practice", PRACTICE))
+    if not pools:
+        raise ValueError("kind должен быть 'all', 'theory' или 'practice'.")
+
+    found: list[dict[str, Any]] = []
+    for pool_kind, items in pools:
+        for item in items:
+            score = _rank_score(query, item, pool_kind)
+            if score >= 0.18:
+                found.append(
+                    {
+                        "kind": pool_kind,
+                        "id": item["id"],
+                        "title": _title_text(item),
+                        "score": round(score, 3),
+                    }
+                )
+    found.sort(key=lambda row: row["score"], reverse=True)
+    found = found[:limit]
+    if display:
+        if found:
+            lines = [
+                f"- `{row['kind']}({row['id']})` - {html.escape(row['title'])} "
+                f"(score {row['score']})"
+                for row in found
+            ]
+            _display_markdown("\n".join(lines))
+        else:
+            _display_markdown("Ничего не найдено.")
+    return found
+
+
+def all_theory(*, copy: bool = False, display: bool = True) -> str:
+    text = "\n\n".join(_format_theory_item(item) for item in THEORY)
+    if copy:
+        copy_text(text)
+    if display:
+        _display_markdown(text)
+    return text
+
+
+def all_practice(*, copy: bool = False, display: bool = True) -> str:
+    text = "\n\n".join(
+        "```python\n" + _format_practice_item(item).strip() + "\n```" for item in PRACTICE
+    )
+    if copy:
+        copy_text(text)
+    if display:
+        _display_markdown(text)
+    return text
+
+
+def copy_theory(number: int) -> str:
+    return theory(number, copy=True, display=False)
+
+
+def copy_practice(number: int) -> str:
+    return practice(number, copy=True, display=False)

cv_study_utils/cli.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import argparse
+
+from .api import all_practice, all_theory, find, list_practice, list_theory, practice, theory
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="cvstudy")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_theory = sub.add_parser("theory", help="Show a theory answer")
+    p_theory.add_argument("number", nargs="?")
+    p_theory.add_argument("--query", "-q")
+    p_theory.add_argument("--copy", action="store_true")
+    p_theory.add_argument("--all", action="store_true")
+
+    p_practice = sub.add_parser("practice", help="Show a practical code template")
+    p_practice.add_argument("number", nargs="?")
+    p_practice.add_argument("--query", "-q")
+    p_practice.add_argument("--copy", action="store_true")
+    p_practice.add_argument("--all", action="store_true")
+
+    p_find = sub.add_parser("find", help="Search theory and practice")
+    p_find.add_argument("query")
+    p_find.add_argument("--kind", choices=["all", "theory", "practice"], default="all")
+    p_find.add_argument("--limit", type=int, default=8)
+
+    args = parser.parse_args()
+    if args.command == "theory":
+        if args.all:
+            print(all_theory(copy=args.copy, display=False))
+        elif args.number is None and args.query is None:
+            print(list_theory(display=False))
+        else:
+            number = int(args.number) if args.number and args.number.isdigit() else args.number
+            print(theory(number, query=args.query, copy=args.copy, display=False))
+    elif args.command == "practice":
+        if args.all:
+            print(all_practice(copy=args.copy, display=False))
+        elif args.number is None and args.query is None:
+            print(list_practice(display=False))
+        else:
+            number = int(args.number) if args.number and args.number.isdigit() else args.number
+            print(practice(number, query=args.query, copy=args.copy, display=False))
+    elif args.command == "find":
+        rows = find(args.query, kind=args.kind, limit=args.limit, display=False)
+        for row in rows:
+            print(f"{row['kind']}({row['id']}): {row['title']} [score={row['score']}]")
+
+
+if __name__ == "__main__":
+    main()