bioguider 0.2.20__py3-none-any.whl → 0.2.22__py3-none-any.whl

bioguider/utils/notebook_utils.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Union, Dict, Any, List
+import json
+
+def extract_markdown_from_notebook(
+    ipynb_path: Union[str, Path],
+    out_path: Union[str, Path, None] = None,
+) -> Dict[str, Any]:
+    """
+    Extract markdown from a Jupyter notebook.
+    """
+    ipynb_path = Path(ipynb_path)
+    if not ipynb_path.exists():
+        raise FileNotFoundError(f"File {ipynb_path} does not exist")
+    try:
+        with ipynb_path.open("r", encoding="utf-8") as f:
+            nb = json.load(f)
+    except json.JSONDecodeError:
+        raise ValueError(f"File {ipynb_path} is not a valid JSON file")
+
+    markdown_txts = [
+        "\n".join(cell.get("source")) if isinstance(cell.get("source"), list) else cell.get("source") for cell in nb.get("cells", [])
+        if cell.get("cell_type") == "markdown"
+    ]
+    text = "\n".join(markdown_txts)
+    if out_path is not None:
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(text)
+    return text
+
+def strip_notebook_to_code_and_markdown(
+    ipynb_path: Union[str, Path],
+    out_path: Union[str, Path, None] = None,
+    keep_top_metadata: bool = True,
+) -> Dict[str, Any]:
+    """
+    Load a .ipynb and return a new notebook that:
+      - keeps ONLY 'code' and 'markdown' cells
+      - empties outputs and execution_count for code cells
+      - drops all other cell types (e.g., 'raw')
+      - preserves attachments on markdown cells
+      - optionally preserves top-level metadata (kernelspec, language_info, etc.)
+
+    Parameters
+    ----------
+    ipynb_path : str | Path
+        Path to the input .ipynb file.
+    out_path : str | Path | None, default None
+        If provided, write the cleaned notebook to this path.
+    keep_top_metadata : bool, default True
+        If True, copy top-level metadata as-is (useful for re-running).
+        If False, keep only minimal metadata.
+
+    Returns
+    -------
+    dict
+        The cleaned notebook (nbformat v4-style dict).
+    """
+    ipynb_path = Path(ipynb_path)
+    if not ipynb_path.exists():
+        raise FileNotFoundError(f"File {ipynb_path} does not exist")
+    try:
+        with ipynb_path.open("r", encoding="utf-8") as f:
+            nb = json.load(f)
+    except json.JSONDecodeError:
+        raise ValueError(f"File {ipynb_path} is not a valid JSON file")
+
+    nbformat = nb.get("nbformat", 4)
+    nbformat_minor = nb.get("nbformat_minor", 5)
+
+    def _to_text(src) -> str:
+        # nbformat allows str or list of lines
+        if isinstance(src, list):
+            return "".join(src)
+        return src or ""
+
+    new_cells: List[Dict[str, Any]] = []
+    for cell in nb.get("cells", []):
+        ctype = cell.get("cell_type")
+        if ctype == "markdown":
+            new_cell = {
+                "cell_type": "markdown",
+                "metadata": cell.get("metadata", {}),
+                "source": _to_text(cell.get("source", "")),
+            }
+            if "attachments" in cell:
+                new_cell["attachments"] = cell["attachments"]
+            new_cells.append(new_cell)
+
+        elif ctype == "code":
+            new_cells.append({
+                "cell_type": "code",
+                "metadata": cell.get("metadata", {}),
+                "source": _to_text(cell.get("source", "")),
+                "execution_count": None,   # clear execution count
+                "outputs": [],             # strip ALL outputs
+            })
+
+        # else: drop 'raw' and any other unknown cell types
+
+    # Build new notebook object
+    new_nb: Dict[str, Any] = {
+        "nbformat": nbformat,
+        "nbformat_minor": nbformat_minor,
+        "metadata": nb.get("metadata", {}) if keep_top_metadata else {},
+        "cells": new_cells,
+    }
+
+    if out_path is not None:
+        out_path = Path(out_path)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        with out_path.open("w", encoding="utf-8") as f:
+            json.dump(new_nb, f, ensure_ascii=False, indent=1)
+
+    return new_nb
+

bioguider/utils/{file_handler.py → python_file_handler.py}

@@ -1,7 +1,7 @@
 import ast
 import os
 
-class FileHandler:
+class PythonFileHandler:
     def __init__(self, file_path: str):
         self.file_path = file_path
 

bioguider/utils/r_file_handler.py

@@ -0,0 +1,549 @@
+import os
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+@dataclass
+class RSymbol:
+    name: str
+    parent: Optional[str]
+    start_line: int
+    end_line: int
+    docstring: Optional[str]
+    params: List[str]
+
+
+class RFileHandler:
+    # only up to "function("
+    FUNC_DEF_HEAD_RE = re.compile(
+        r'(?P<name>[A-Za-z.][\w.]*)\s*<-\s*function\s*\(',
+        re.MULTILINE,
+    )
+    
+    S3_METHOD_HEAD_RE = re.compile(
+        r'(?P<generic>[A-Za-z.][\w.]*)\.(?P<class>[A-Za-z.][\w.]*)\s*<-\s*function\s*\(',
+        re.MULTILINE,
+    )
+    
+    # R6 method head: "name = function("
+    R6_METHOD_HEAD_RE = re.compile(
+        r'(?P<mname>[A-Za-z.][\w.]*)\s*=\s*function\s*\(',
+        re.MULTILINE,
+    )
+    
+    # S4 method head inside setMethod(... function(
+    S4_METHOD_HEAD_RE = re.compile(
+        r'setMethod\s*\(\s*["\'](?P<generic>[^"\']+)["\']\s*,.*?function\s*\(',
+        re.MULTILINE | re.DOTALL,
+    )
+
+    FUNC_DEF_RE = re.compile(
+        # name <- function( ... ) {   with multi-line args allowed
+        r'(?P<name>[A-Za-z.][\w.]*)\s*<-\s*function\s*\((?P<args>[^)]*)\)\s*\{',
+        re.MULTILINE,
+    )
+    S3_METHOD_RE = re.compile(
+        r'(?P<generic>[A-Za-z.][\w.]*)\.(?P<class>[A-Za-z.][\w.]*)\s*<-\s*function\s*\((?P<args>[^)]*)\)\s*\{',
+        re.MULTILINE,
+    )
+    R6_CLASS_RE = re.compile(
+        r'(?P<varname>[A-Za-z.][\w.]*)\s*<-\s*R6Class\s*\(\s*["\'](?P<classname>[^"\']+)["\']',
+        re.MULTILINE | re.DOTALL,
+    )
+    R6_METHOD_RE = re.compile(
+        r'(?P<mname>[A-Za-z.][\w.]*)\s*=\s*function\s*\((?P<args>[^)]*)\)\s*\{',
+        re.MULTILINE,
+    )
+    S4_CLASS_RE = re.compile(
+        r'setClass\s*\(\s*["\'](?P<classname>[^"\']+)["\']',
+        re.MULTILINE,
+    )
+    S4_METHOD_RE = re.compile(
+        r'setMethod\s*\(\s*["\'](?P<generic>[^"\']+)["\']\s*,.*?function\s*\((?P<args>[^)]*)\)\s*\{',
+        re.MULTILINE | re.DOTALL,
+    )
+    S4_SIG_CLASS_RE = re.compile(
+        r'signature\s*=\s*(?:list\s*\(|\()\s*(?:[^)]*class\s*=\s*["\'](?P<classname>[^"\']+)["\']|["\'](?P<classname2>[^"\']+)["\'])',
+        re.MULTILINE,
+    )
+    LIB_REQUIRE_RE = re.compile(
+        r'\b(?:library|require)\s*\(\s*([A-Za-z.][\w.]*)\s*\)',
+        re.MULTILINE,
+    )
+    NS_USE_RE = re.compile(
+        r'(?P<pkg>[A-Za-z.][\w.]*):::{0,2}(?P<sym>[A-Za-z.][\w.]*)',
+        re.MULTILINE,
+    )
+
+    def __init__(self, file_path: str):
+        self.file_path = file_path
+        with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+            self.text = f.read()
+        self.lines = self.text.splitlines()
+        self._brace_map = self._build_brace_map_safely()  # FIX: ignore comments/strings
+
+    # ---------------- Public API ----------------
+
+    def get_functions_and_classes(self) -> List[Tuple[str, Optional[str], int, int, Optional[str], List[str]]]:
+        items: List[RSymbol] = []
+        items.extend(self._parse_functions())
+        items.extend(self._parse_s3_methods())
+        items.extend(self._parse_r6())
+        items.extend(self._parse_s4())
+        items.sort(key=lambda s: (s.start_line, s.end_line))
+        return [(i.name, i.parent, i.start_line, i.end_line, i.docstring, i.params) for i in items]
+
+    def get_imports(self) -> List[str]:
+        pkgs = set(self.LIB_REQUIRE_RE.findall(self.text))
+        for m in self.NS_USE_RE.finditer(self.text):
+            pkgs.add(m.group('pkg'))
+        return sorted(pkgs)
+
+    # ---------------- Parsers ----------------
+
+    def _parse_functions(self) -> List[RSymbol]:
+        syms: List[RSymbol] = []
+        for m in self.FUNC_DEF_HEAD_RE.finditer(self.text):
+            name = m.group('name')
+            open_paren = m.end() - 1  # points at '('
+            close_paren = self._matching_paren_pos_global(open_paren)
+            if close_paren is None:
+                continue
+            args_text = self.text[open_paren + 1: close_paren]
+            args = self._parse_params(args_text)
+    
+            block_open = self._find_next_code_brace_after(close_paren + 1)
+            if block_open is None:
+                continue
+            block_close = self._matching_brace_pos(block_open)
+    
+            start_line = self._pos_to_line(block_open)
+            end_line = self._pos_to_line(block_close)
+            doc = self._roxygen_before(m.start())
+    
+            syms.append(RSymbol(name=name, parent=None,
+                                start_line=start_line, end_line=end_line,
+                                docstring=doc, params=args))
+    
+            # nested
+            syms.extend(self._parse_nested_functions(block_open, block_close, parent=name))
+        return syms
+
+    def _parse_nested_functions(self, abs_start: int, abs_end: int, parent: str) -> List[RSymbol]:
+        sub = self.text[abs_start:abs_end+1]
+        syms: List[RSymbol] = []
+        for m in self.FUNC_DEF_HEAD_RE.finditer(sub):
+            open_rel = m.end() - 1
+            close_rel = self._matching_paren_pos_in_text(sub, open_rel)
+            if close_rel is None:
+                continue
+            args_text = sub[open_rel + 1: close_rel]
+            args = self._parse_params(args_text)
+    
+            # brace after ')' within the slice
+            func_open_rel = self._find_next_char_in_text(sub, '{', close_rel + 1)
+            if func_open_rel is None:
+                continue
+            func_close_rel = self._matching_brace_pos_in_text(sub, func_open_rel)
+            if func_close_rel is None:
+                continue
+    
+            block_open = abs_start + func_open_rel
+            block_close = abs_start + func_close_rel
+            name = m.group('name')
+            doc = self._roxygen_before(block_open)
+            syms.append(RSymbol(
+                name=name, parent=parent,
+                start_line=self._pos_to_line(block_open),
+                end_line=self._pos_to_line(block_close),
+                docstring=doc, params=args
+            ))
+        return syms
+
+
+    def _parse_s3_methods(self) -> List[RSymbol]:
+        syms: List[RSymbol] = []
+        for m in self.S3_METHOD_HEAD_RE.finditer(self.text):
+            generic = m.group('generic')
+            clazz = m.group('class')
+            name = f"{generic}.{clazz}"
+    
+            open_paren = m.end() - 1
+            close_paren = self._matching_paren_pos_global(open_paren)
+            if close_paren is None:
+                continue
+            args_text = self.text[open_paren + 1: close_paren]
+            args = self._parse_params(args_text)
+    
+            block_open = self._find_next_code_brace_after(close_paren + 1)
+            if block_open is None:
+                continue
+            block_close = self._matching_brace_pos(block_open)
+    
+            syms.append(RSymbol(
+                name=name, parent=generic,
+                start_line=self._pos_to_line(block_open),
+                end_line=self._pos_to_line(block_close),
+                docstring=self._roxygen_before(m.start()),
+                params=args
+            ))
+        return syms
+
+
+    def _parse_r6(self) -> List[RSymbol]:
+        syms: List[RSymbol] = []
+        for m in self.R6_CLASS_RE.finditer(self.text):
+            classname = m.group('classname')
+            # Find the first '{' after R6Class( — it's the class call's body brace
+            first_brace = self._find_next_code_brace_after(m.end())
+            if first_brace is None:
+                continue
+            class_end = self._matching_brace_pos(first_brace)
+            syms.append(RSymbol(
+                name=classname, parent=None,
+                start_line=self._pos_to_line(first_brace),
+                end_line=self._pos_to_line(class_end),
+                docstring=self._roxygen_before(m.start()),
+                params=[]
+            ))
+            # Methods within public/private/active lists
+            class_text = self.text[m.start():class_end+1]
+            base = m.start()
+            for sect in ('public', 'private', 'active'):
+                for meth in self._parse_r6_section_methods(class_text, base, sect, classname):
+                    syms.append(meth)
+        return syms
+
+    def _parse_r6_section_methods(self, class_text: str, base: int, section: str, parent_class: str) -> List[RSymbol]:
+        syms: List[RSymbol] = []
+        for sec in re.finditer(rf'{section}\s*=\s*list\s*\(', class_text):
+            lst_open = sec.end() - 1
+            lst_close = self._matching_paren_pos_in_text(class_text, lst_open)
+            if lst_close is None:
+                continue
+            list_text = class_text[lst_open:lst_close+1]
+            for m in self.R6_METHOD_HEAD_RE.finditer(list_text):
+                open_rel = m.end() - 1
+                close_rel = self._matching_paren_pos_in_text(list_text, open_rel)
+                if close_rel is None:
+                    continue
+                args_text = list_text[open_rel + 1: close_rel]
+                args = self._parse_params(args_text)
+    
+                func_open_rel = self._find_next_char_in_text(list_text, '{', close_rel + 1)
+                if func_open_rel is None:
+                    continue
+                func_close_rel = self._matching_brace_pos_in_text(list_text, func_open_rel)
+                if func_close_rel is None:
+                    continue
+    
+                block_open = base + lst_open + func_open_rel
+                block_close = base + lst_open + func_close_rel
+    
+                syms.append(RSymbol(
+                    name=f"{parent_class}${m.group('mname')}",
+                    parent=parent_class,
+                    start_line=self._pos_to_line(block_open),
+                    end_line=self._pos_to_line(block_close),
+                    docstring=self._roxygen_before(block_open),
+                    params=args
+                ))
+        return syms
+
+
+    def _parse_s4(self) -> List[RSymbol]:
+        syms: List[RSymbol] = []
+        for m in self.S4_CLASS_RE.finditer(self.text):
+            syms.append(RSymbol(
+                name=m.group('classname'), parent=None,
+                start_line=self._pos_to_line(m.start()),
+                end_line=self._pos_to_line(m.start()),
+                docstring=self._roxygen_before(m.start()),
+                params=[]
+            ))
+        for m in self.S4_METHOD_HEAD_RE.finditer(self.text):
+            generic = m.group('generic')
+        
+            open_paren = m.end() - 1
+            close_paren = self._matching_paren_pos_global(open_paren)
+            if close_paren is None:
+                continue
+            args_text = self.text[open_paren + 1: close_paren]
+            args = self._parse_params(args_text)
+        
+            block_open = self._find_next_code_brace_after(close_paren + 1)
+            block_close = self._matching_brace_pos(block_open) if block_open is not None else m.end()
+        
+            sig_slice = self.text[m.start(): block_open or m.end()]
+            cm = self.S4_SIG_CLASS_RE.search(sig_slice)
+            clazz = cm.group('classname') if cm and cm.group('classname') else (cm.group('classname2') if cm else None)
+            name = f"{generic}{'<' + clazz + '>' if clazz else ''}"
+        
+            syms.append(RSymbol(
+                name=name, parent=generic,
+                start_line=self._pos_to_line(block_open if block_open is not None else m.start()),
+                end_line=self._pos_to_line(block_close),
+                docstring=self._roxygen_before(m.start()),
+                params=args
+            ))
+
+        return syms
+
+    # ---------------- Utilities ----------------
+
+    def _parse_params(self, arg_str: str) -> List[str]:
+        params = []
+        depth = 0
+        token = []
+        in_s: Optional[str] = None
+        escape = False
+        for ch in arg_str:
+            if in_s:
+                token.append(ch)
+                if escape:
+                    escape = False
+                elif ch == '\\':
+                    escape = True
+                elif ch == in_s:
+                    in_s = None
+                continue
+            if ch in ('"', "'"):
+                in_s = ch
+                token.append(ch)
+                continue
+            if ch in '([{':
+                depth += 1
+                token.append(ch)
+            elif ch in ')]}':
+                depth -= 1
+                token.append(ch)
+            elif ch == ',' and depth == 0:
+                params.append(''.join(token).strip())
+                token = []
+            else:
+                token.append(ch)
+        if token:
+            params.append(''.join(token).strip())
+
+        cleaned = []
+        for p in params:
+            p = p.strip()
+            if not p:
+                continue
+            if p == '...':
+                cleaned.append('...')
+                continue
+            name = p.split('=')[0].strip()
+            if name:
+                cleaned.append(name)
+        return cleaned
+
+    def _roxygen_before(self, pos: int) -> Optional[str]:
+        line_idx = self._pos_to_line(pos) - 2
+        if line_idx < 0:
+            return None
+        buf = []
+        while line_idx >= 0:
+            line = self.lines[line_idx]
+            s = line.lstrip()
+            if s.startswith("#'"):
+                buf.append(s[2:].lstrip())
+                line_idx -= 1
+                continue
+            # stop at first non-roxygen line (don’t cross blank + NULL padding blocks)
+            break
+        if not buf:
+            return None
+        buf.reverse()
+        return '\n'.join(buf).strip() or None
+
+    # -------- Position / brace helpers (comment/string aware) --------
+
+    def _build_brace_map_safely(self):
+        """
+        Build a map of '{' -> matching '}' while ignoring braces inside:
+          - comments starting with '#'
+          - single- and double-quoted strings with escapes
+        """
+        stack = []
+        pairs = {}
+        in_string: Optional[str] = None
+        escape = False
+        in_comment = False
+
+        for i, ch in enumerate(self.text):
+            if in_comment:
+                if ch == '\n':
+                    in_comment = False
+                continue
+
+            if in_string:
+                if escape:
+                    escape = False
+                    continue
+                if ch == '\\':
+                    escape = True
+                    continue
+                if ch == in_string:
+                    in_string = None
+                continue
+
+            # not in string/comment
+            if ch == '#':
+                in_comment = True
+                continue
+            if ch == '"' or ch == "'":
+                in_string = ch
+                continue
+
+            if ch == '{':
+                stack.append(i)
+            elif ch == '}':
+                if stack:
+                    open_i = stack.pop()
+                    pairs[open_i] = i
+        return pairs
+
+    def _matching_brace_pos(self, open_brace_pos: int) -> int:
+        return self._brace_map.get(open_brace_pos, len(self.text) - 1)
+
+    def _find_next_code_brace_after(self, start: int) -> Optional[int]:
+        """Find next '{' after start, skipping ones in comments/strings by scanning forward again."""
+        in_string: Optional[str] = None
+        escape = False
+        in_comment = False
+        for i in range(start, len(self.text)):
+            ch = self.text[i]
+            if in_comment:
+                if ch == '\n':
+                    in_comment = False
+                continue
+            if in_string:
+                if escape:
+                    escape = False
+                    continue
+                if ch == '\\':
+                    escape = True
+                    continue
+                if ch == in_string:
+                    in_string = None
+                continue
+            if ch == '#':
+                in_comment = True
+                continue
+            if ch == '"' or ch == "'":
+                in_string = ch
+                continue
+            if ch == '{':
+                return i
+        return None
+
+    def _pos_to_line(self, pos: int) -> int:
+        return self.text.count('\n', 0, max(0, pos)) + 1
+
+    def _find_next_char_in_text(self, text: str, ch: str, start: int) -> Optional[int]:
+        idx = text.find(ch, start)
+        return idx if idx != -1 else None
+
+    # For nested parsing on a slice (already delimited correctly)
+    def _matching_brace_pos_in_text(self, text: str, open_idx: int) -> Optional[int]:
+        in_string: Optional[str] = None
+        escape = False
+        in_comment = False
+        depth = 0
+        for i in range(open_idx, len(text)):
+            ch = text[i]
+            if in_comment:
+                if ch == '\n':
+                    in_comment = False
+                continue
+            if in_string:
+                if escape:
+                    escape = False
+                elif ch == '\\':
+                    escape = True
+                elif ch == in_string:
+                    in_string = None
+                continue
+            if ch == '#':
+                in_comment = True
+                continue
+            if ch == '"' or ch == "'":
+                in_string = ch
+                continue
+            if ch == '{':
+                depth += 1
+            elif ch == '}':
+                depth -= 1
+                if depth == 0:
+                    return i
+        return None
+
+    def _matching_paren_pos_in_text(self, text: str, open_idx: int) -> Optional[int]:
+        in_string: Optional[str] = None
+        escape = False
+        in_comment = False
+        depth = 0
+        for i in range(open_idx, len(text)):
+            ch = text[i]
+            if in_comment:
+                if ch == '\n':
+                    in_comment = False
+                continue
+            if in_string:
+                if escape:
+                    escape = False
+                elif ch == '\\':
+                    escape = True
+                elif ch == in_string:
+                    in_string = None
+                continue
+            if ch == '#':
+                in_comment = True
+                continue
+            if ch == '"' or ch == "'":
+                in_string = ch
+                continue
+            if ch == '(':
+                depth += 1
+            elif ch == ')':
+                depth -= 1
+                if depth == 0:
+                    return i
+        return None
+    
+    def _matching_paren_pos_global(self, open_idx: int) -> Optional[int]:
+        """Given an index of '(' in self.text, return the matching ')' index,
+        ignoring parentheses inside strings/comments."""
+        in_string: Optional[str] = None
+        escape = False
+        in_comment = False
+        depth = 0
+        for i in range(open_idx, len(self.text)):
+            ch = self.text[i]
+            if in_comment:
+                if ch == '\n':
+                    in_comment = False
+                continue
+            if in_string:
+                if escape:
+                    escape = False
+                elif ch == '\\':
+                    escape = True
+                elif ch == in_string:
+                    in_string = None
+                continue
+            if ch == '#':
+                in_comment = True
+                continue
+            if ch == '"' or ch == "'":
+                in_string = ch
+                continue
+            if ch == '(':
+                depth += 1
+            elif ch == ')':
+                depth -= 1
+                if depth == 0:
+                    return i
+        return None
+