scitex 2.7.0__py3-none-any.whl → 2.8.1__py3-none-any.whl

scitex/msword/utils.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-11 16:45:00
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/msword/utils.py
+
+"""
+Utility functions for processing MS Word documents.
+
+These functions can be used as post_import_hooks or called directly
+to process document structures.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+
+def link_captions_to_images(doc: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Link figure captions to images by matching order.
+
+    This function pairs figure captions with images based on their
+    sequential order in the document. Each figure caption is assigned
+    an `image_hash` that corresponds to the image at the same position.
+
+    Parameters
+    ----------
+    doc : dict
+        SciTeX writer document with 'blocks' and 'images' keys.
+
+    Returns
+    -------
+    dict
+        The same document with image_hash added to figure captions.
+
+    Examples
+    --------
+    >>> from scitex.msword import load_docx
+    >>> from scitex.msword.utils import link_captions_to_images
+    >>> doc = load_docx("manuscript.docx")
+    >>> doc = link_captions_to_images(doc)
+    >>> # Now captions have image_hash for LaTeX export
+    """
+    blocks = doc.get("blocks", [])
+    images = doc.get("images", [])
+
+    # Find all figure captions
+    figure_captions = [
+        b for b in blocks
+        if b.get("type") == "caption" and b.get("caption_type") == "figure"
+    ]
+
+    # Link by order (figure 1 -> image 0, figure 2 -> image 1, etc.)
+    for caption in figure_captions:
+        fig_num = caption.get("number")
+        if fig_num is not None and isinstance(fig_num, int):
+            # Figure numbers are typically 1-indexed
+            img_idx = fig_num - 1
+            if 0 <= img_idx < len(images):
+                caption["image_hash"] = images[img_idx].get("hash")
+
+    return doc
+
+
+def link_captions_to_images_by_proximity(doc: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Link figure captions to images by document proximity.
+
+    This function uses the image blocks (type="image") that are inserted
+    at their actual positions in the document body. It finds the nearest
+    unlinked image block to each figure caption.
+
+    Parameters
+    ----------
+    doc : dict
+        SciTeX writer document.
+
+    Returns
+    -------
+    dict
+        Document with image_hash added to captions.
+    """
+    blocks = doc.get("blocks", [])
+
+    # Collect image blocks and figure captions with their indices
+    image_blocks = []
+    figure_captions = []
+
+    for i, block in enumerate(blocks):
+        if block.get("type") == "image":
+            image_blocks.append((i, block))
+        elif block.get("type") == "caption" and block.get("caption_type") == "figure":
+            figure_captions.append((i, block))
+
+    if not image_blocks:
+        # Fallback to old behavior using doc["images"] list
+        images = doc.get("images", [])
+        if not images:
+            return doc
+        image_hashes = [img.get("hash") for img in images]
+        for idx, (_, caption) in enumerate(figure_captions):
+            if idx < len(image_hashes):
+                caption["image_hash"] = image_hashes[idx]
+        return doc
+
+    used_images = set()
+
+    # For each caption, find the nearest preceding image block
+    for cap_idx, caption in figure_captions:
+        best_img_idx = None
+        best_img_hash = None
+        best_distance = float("inf")
+
+        for img_idx, img_block in image_blocks:
+            img_hash = img_block.get("image_hash")
+            if img_hash in used_images:
+                continue
+
+            # Prefer images that come before the caption (typical layout)
+            distance = cap_idx - img_idx
+            if distance >= 0 and distance < best_distance:
+                best_distance = distance
+                best_img_idx = img_idx
+                best_img_hash = img_hash
+
+        # If no preceding image, try following images
+        if best_img_hash is None:
+            for img_idx, img_block in image_blocks:
+                img_hash = img_block.get("image_hash")
+                if img_hash in used_images:
+                    continue
+
+                distance = abs(cap_idx - img_idx)
+                if distance < best_distance:
+                    best_distance = distance
+                    best_img_idx = img_idx
+                    best_img_hash = img_hash
+
+        if best_img_hash:
+            caption["image_hash"] = best_img_hash
+            used_images.add(best_img_hash)
+
+    return doc
+
+
+def normalize_section_headings(doc: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Normalize section headings for consistency.
+
+    Converts common section titles to standard academic format:
+    - "intro" -> "Introduction"
+    - "method" -> "Methods"
+    - etc.
+
+    Parameters
+    ----------
+    doc : dict
+        SciTeX writer document.
+
+    Returns
+    -------
+    dict
+        Document with normalized headings.
+    """
+    blocks = doc.get("blocks", [])
+
+    # Common normalizations
+    normalizations = {
+        "intro": "Introduction",
+        "introduction": "Introduction",
+        "method": "Methods",
+        "methods": "Methods",
+        "materials and methods": "Materials and Methods",
+        "result": "Results",
+        "results": "Results",
+        "discussion": "Discussion",
+        "conclusion": "Conclusions",
+        "conclusions": "Conclusions",
+        "acknowledgement": "Acknowledgements",
+        "acknowledgements": "Acknowledgements",
+        "reference": "References",
+        "references": "References",
+        "bibliography": "References",
+    }
+
+    for block in blocks:
+        if block.get("type") == "heading" and block.get("level") == 1:
+            text = block.get("text", "").strip().lower()
+            if text in normalizations:
+                block["text"] = normalizations[text]
+
+    return doc
+
+
+def validate_document(doc: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Validate document structure and add warnings.
+
+    Checks for common issues:
+    - Missing required sections
+    - Unmatched caption numbers
+    - Empty references section
+    - Duplicate figure numbers
+
+    Parameters
+    ----------
+    doc : dict
+        SciTeX writer document.
+
+    Returns
+    -------
+    dict
+        Document with warnings added.
+    """
+    blocks = doc.get("blocks", [])
+    warnings = doc.get("warnings", [])
+
+    # Check for required sections
+    headings = [b.get("text", "").lower() for b in blocks if b.get("type") == "heading"]
+
+    required_sections = ["introduction", "methods", "results", "discussion", "references"]
+    for section in required_sections:
+        if not any(section in h for h in headings):
+            warnings.append(f"Missing section: {section.title()}")
+
+    # Check for duplicate figure numbers
+    figure_numbers = [
+        b.get("number") for b in blocks
+        if b.get("type") == "caption" and b.get("caption_type") == "figure"
+    ]
+    seen = set()
+    for num in figure_numbers:
+        if num in seen:
+            warnings.append(f"Duplicate figure number: {num}")
+        seen.add(num)
+
+    # Check for missing references
+    references = doc.get("references", [])
+    if not references:
+        ref_blocks = [b for b in blocks if b.get("type") == "reference-paragraph"]
+        if not ref_blocks:
+            warnings.append("No references found in document")
+
+    doc["warnings"] = warnings
+    return doc
+
+
+def create_post_import_hook(*functions):
+    """
+    Create a composite post_import_hook from multiple functions.
+
+    Parameters
+    ----------
+    *functions : callable
+        Functions to apply in sequence.
+
+    Returns
+    -------
+    callable
+        A single hook that applies all functions.
+
+    Examples
+    --------
+    >>> from scitex.msword.utils import (
+    ...     link_captions_to_images,
+    ...     normalize_section_headings,
+    ...     create_post_import_hook,
+    ... )
+    >>> hook = create_post_import_hook(
+    ...     link_captions_to_images,
+    ...     normalize_section_headings,
+    ... )
+    >>> # Use with custom profile
+    >>> profile.post_import_hooks = [hook]
+    """
+    def composite_hook(doc: Dict[str, Any]) -> Dict[str, Any]:
+        for func in functions:
+            doc = func(doc)
+        return doc
+    return composite_hook
+
+
+__all__ = [
+    "link_captions_to_images",
+    "link_captions_to_images_by_proximity",
+    "normalize_section_headings",
+    "validate_document",
+    "create_post_import_hook",
+]

scitex/msword/writer.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-11 15:15:00
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/msword/writer.py
+
+"""
+SciTeX writer document -> DOCX converter.
+
+This module exports SciTeX documents to MS Word .docx files,
+applying journal-specific styles and formatting.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .profiles import BaseWordProfile
+
+# Lazy import for python-docx
+try:
+    import docx
+    from docx.document import Document as DocxDocument
+    from docx.shared import Inches, Pt, Cm
+    from docx.enum.text import WD_ALIGN_PARAGRAPH
+    from docx.enum.style import WD_STYLE_TYPE
+
+    DOCX_AVAILABLE = True
+    _DOCX_IMPORT_ERROR = None
+except ImportError as exc:
+    DOCX_AVAILABLE = False
+    _DOCX_IMPORT_ERROR = exc
+
+
+class WordWriter:
+    """
+    Export a SciTeX writer document to a DOCX file.
+
+    This writer handles:
+    - Section headings with proper styles
+    - Paragraphs with formatting
+    - Figure and table captions
+    - References section
+    - Image embedding
+    - Journal-specific template application
+    """
+
+    def __init__(
+        self,
+        profile: BaseWordProfile,
+        template_path: Optional[Path] = None,
+    ):
+        """
+        Parameters
+        ----------
+        profile : BaseWordProfile
+            Mapping from writer structures to Word styles.
+        template_path : Path | None
+            Optional path to a Word template (.dotx/.docx) to use as base.
+        """
+        if not DOCX_AVAILABLE:
+            raise ImportError(
+                "python-docx is required for scitex.msword.WordWriter. "
+                "Install it via `pip install python-docx`."
+            ) from _DOCX_IMPORT_ERROR
+        self.profile = profile
+        self.template_path = template_path
+
+    def write(
+        self,
+        writer_doc: Dict[str, Any] | Any,
+        path: Path,
+    ) -> None:
+        """
+        Write a SciTeX writer document to a DOCX file.
+
+        Parameters
+        ----------
+        writer_doc : dict | Any
+            Writer document or intermediate structure.
+        path : Path
+            Output path for the DOCX file.
+        """
+        # Create document (from template if specified)
+        if self.template_path and Path(self.template_path).exists():
+            doc = docx.Document(str(self.template_path))
+            # Clear existing content but keep styles
+            self._clear_document_content(doc)
+        else:
+            doc = docx.Document()
+
+        # Run pre-export hooks
+        for hook in self.profile.pre_export_hooks:
+            writer_doc = hook(writer_doc)
+
+        # Extract blocks from writer_doc
+        if isinstance(writer_doc, dict) and "blocks" in writer_doc:
+            blocks = writer_doc["blocks"]
+            images = writer_doc.get("images", [])
+        else:
+            blocks = list(writer_doc)
+            images = []
+
+        # Build image lookup by hash
+        image_lookup = {img.get("hash"): img for img in images if "hash" in img}
+
+        # Process each block
+        for block in blocks:
+            self._add_block(doc, block, image_lookup)
+
+        # Apply double-anonymous processing if needed
+        if self.profile.double_anonymous:
+            self._apply_double_anonymous(doc, writer_doc)
+
+        # Save document
+        doc.save(str(path))
+
+    def _clear_document_content(self, doc: DocxDocument) -> None:
+        """Clear document content while preserving styles."""
+        for element in doc.element.body[:]:
+            doc.element.body.remove(element)
+
+    def _add_block(
+        self,
+        doc: DocxDocument,
+        block: Dict[str, Any],
+        image_lookup: Dict[str, Any],
+    ) -> None:
+        """Add a single block to the document."""
+        btype = block.get("type", "paragraph")
+        text = block.get("text", "")
+
+        if not text and btype not in ("table", "image"):
+            return
+
+        if btype == "heading":
+            level = block.get("level", 1)
+            self._add_heading(doc, text, level)
+
+        elif btype == "caption":
+            self._add_caption(doc, block)
+
+        elif btype == "reference-paragraph":
+            self._add_reference(doc, block)
+
+        elif btype == "table":
+            self._add_table(doc, block)
+
+        elif btype == "image":
+            self._add_image(doc, block, image_lookup)
+
+        elif btype == "list-item":
+            self._add_list_item(doc, block)
+
+        else:
+            # Default: paragraph
+            self._add_paragraph(doc, text, block.get("runs"))
+
+    def _add_heading(
+        self,
+        doc: DocxDocument,
+        text: str,
+        level: int,
+    ) -> None:
+        """Add a heading paragraph at the given logical level."""
+        style_name = self.profile.heading_styles.get(level)
+
+        if style_name and self._style_exists(doc, style_name):
+            p = doc.add_paragraph(text)
+            p.style = style_name
+        else:
+            # Fallback to built-in heading
+            doc.add_heading(text, level=min(level, 9))
+
+    def _add_paragraph(
+        self,
+        doc: DocxDocument,
+        text: str,
+        runs: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Add a paragraph with optional formatted runs."""
+        p = doc.add_paragraph()
+
+        if runs:
+            # Add formatted runs
+            for run_data in runs:
+                run = p.add_run(run_data.get("text", ""))
+                if run_data.get("bold"):
+                    run.bold = True
+                if run_data.get("italic"):
+                    run.italic = True
+                if run_data.get("underline"):
+                    run.underline = True
+                if run_data.get("font_size"):
+                    run.font.size = Pt(run_data["font_size"])
+                if run_data.get("font_name"):
+                    run.font.name = run_data["font_name"]
+        else:
+            p.add_run(text)
+
+        # Apply normal style
+        if self._style_exists(doc, self.profile.normal_style):
+            try:
+                p.style = self.profile.normal_style
+            except Exception:
+                pass
+
+    def _add_caption(
+        self,
+        doc: DocxDocument,
+        block: Dict[str, Any],
+    ) -> None:
+        """Add a figure or table caption."""
+        caption_type = block.get("caption_type", "")
+        number = block.get("number", "")
+        caption_text = block.get("caption_text", block.get("text", ""))
+
+        # Build caption text
+        if caption_type == "figure" and number:
+            full_text = f"Figure {number}. {caption_text}"
+        elif caption_type == "table" and number:
+            full_text = f"Table {number}. {caption_text}"
+        else:
+            full_text = block.get("text", caption_text)
+
+        p = doc.add_paragraph(full_text)
+
+        if self._style_exists(doc, self.profile.caption_style):
+            try:
+                p.style = self.profile.caption_style
+            except Exception:
+                pass
+
+    def _add_reference(
+        self,
+        doc: DocxDocument,
+        block: Dict[str, Any],
+    ) -> None:
+        """Add a reference entry."""
+        ref_number = block.get("ref_number")
+        ref_text = block.get("ref_text", block.get("text", ""))
+
+        if ref_number is not None:
+            full_text = f"[{ref_number}] {ref_text}"
+        else:
+            full_text = ref_text
+
+        p = doc.add_paragraph(full_text)
+
+        if self._style_exists(doc, self.profile.normal_style):
+            try:
+                p.style = self.profile.normal_style
+            except Exception:
+                pass
+
+    def _add_table(
+        self,
+        doc: DocxDocument,
+        block: Dict[str, Any],
+    ) -> None:
+        """Add a table."""
+        rows = block.get("rows", [])
+        if not rows:
+            return
+
+        num_rows = len(rows)
+        num_cols = len(rows[0]) if rows else 0
+
+        table = doc.add_table(rows=num_rows, cols=num_cols)
+        table.style = "Table Grid"
+
+        for i, row_data in enumerate(rows):
+            row = table.rows[i]
+            for j, cell_text in enumerate(row_data):
+                if j < len(row.cells):
+                    row.cells[j].text = str(cell_text)
+
+    def _add_image(
+        self,
+        doc: DocxDocument,
+        block: Dict[str, Any],
+        image_lookup: Dict[str, Any],
+    ) -> None:
+        """Add an image."""
+        image_hash = block.get("image_hash")
+        image_data = block.get("data")
+
+        if image_hash and image_hash in image_lookup:
+            image_info = image_lookup[image_hash]
+            image_data = image_info.get("data")
+
+        if image_data:
+            from io import BytesIO
+
+            image_stream = BytesIO(image_data)
+            width = block.get("width_inches", 5.0)
+            doc.add_picture(image_stream, width=Inches(width))
+
+    def _add_list_item(
+        self,
+        doc: DocxDocument,
+        block: Dict[str, Any],
+    ) -> None:
+        """Add a list item (bullet or numbered)."""
+        text = block.get("text", "")
+        list_type = block.get("list_type", "bullet")
+
+        p = doc.add_paragraph(text)
+
+        style_key = "bullet" if list_type == "bullet" else "numbered"
+        style_name = self.profile.list_styles.get(style_key)
+
+        if style_name and self._style_exists(doc, style_name):
+            try:
+                p.style = style_name
+            except Exception:
+                pass
+
+    def _style_exists(self, doc: DocxDocument, style_name: str) -> bool:
+        """Check if a style exists in the document."""
+        try:
+            _ = doc.styles[style_name]
+            return True
+        except KeyError:
+            return False
+
+    def _apply_double_anonymous(
+        self,
+        doc: DocxDocument,
+        writer_doc: Dict[str, Any],
+    ) -> None:
+        """
+        Apply double-anonymous formatting.
+
+        This removes or masks author-identifying information.
+        """
+        # Get author info to mask
+        metadata = writer_doc.get("metadata", {})
+        author = metadata.get("author", "")
+
+        if not author:
+            return
+
+        # Search and replace author names with placeholder
+        # This is a simple implementation; more sophisticated
+        # masking may be needed for real use
+        for para in doc.paragraphs:
+            if author.lower() in para.text.lower():
+                for run in para.runs:
+                    if author.lower() in run.text.lower():
+                        # Mask author name
+                        import re
+
+                        run.text = re.sub(
+                            re.escape(author),
+                            "[Author]",
+                            run.text,
+                            flags=re.IGNORECASE,
+                        )
+
+
+__all__ = ["WordWriter"]

scitex/plt/__init__.py

@@ -31,6 +31,10 @@ import matplotlib.font_manager as fm
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 
+from scitex import logging as _logging
+
+_logger = _logging.getLogger(__name__)
+
 # =============================================================================
 # Auto-configure matplotlib with SciTeX style on import
 # =============================================================================
@@ -316,7 +320,6 @@ def load(path, apply_manual=True):
     """
     from pathlib import Path
     import hashlib
-    import warnings
     import scitex as stx
 
     path = Path(path)
@@ -345,7 +348,7 @@ def load(path, apply_manual=True):
         if "base_hash" in manual_data:
             current_hash = _compute_file_hash(json_path)
             if manual_data["base_hash"] != current_hash:
-                warnings.warn(
+                _logger.warning(
                     f"Manual overrides may be stale: base data changed since manual edits.\n"
                     f"  Expected hash: {manual_data['base_hash'][:16]}...\n"
                     f"  Current hash:  {current_hash[:16]}...\n"

scitex/plt/_subplots/_AxesWrapper.py

@@ -14,6 +14,10 @@ from functools import wraps
 import numpy as np
 import pandas as pd
 
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
 
 class AxesWrapper:
     def __init__(self, fig_scitex, axes_scitex):
@@ -124,14 +128,10 @@ class AxesWrapper:
         Returns:
             np.ndarray: Array of wrapped axes with the same shape
         """
-        import warnings
-
         # Show a warning to help users avoid common mistakes
-        warnings.warn(
+        logger.warning(
             "Converting AxesWrapper to numpy array. If you're trying to flatten "
-            "the axes, use 'list(axes.flatten())' instead of 'np.array(axes).flatten()'.",
-            UserWarning,
-            stacklevel=2,
+            "the axes, use 'list(axes.flatten())' instead of 'np.array(axes).flatten()'."
         )
 
         # Convert the underlying axes to a compatible numpy array representation