scitex 2.16.0__py3-none-any.whl → 2.16.2__py3-none-any.whl

scitex/writer/README.md

@@ -1,12 +1,12 @@
-<!-- ---
-!-- Timestamp: 2025-10-29 17:33:34
-!-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/writer/README.md
-!-- --- -->
-
 # SciTeX Writer
 
-Python interface for LaTeX manuscript compilation.
+Thin wrapper delegating to [scitex-writer](https://github.com/ywatanabe1989/scitex-writer) package.
+
+## Installation
+
+```bash
+pip install scitex-writer
+```
 
 ## Usage
 
@@ -14,422 +14,38 @@ Python interface for LaTeX manuscript compilation.
 from scitex.writer import Writer
 from pathlib import Path
 
- # Standalone manuscript (isolated git repository - default)
+# Create or attach to a writer project
 writer = Writer(Path("my_paper"))
 
-# # Project-integrated manuscript (use parent's git repository)
-# writer = Writer(Path("my_project/scitex/writer"), git_strategy='parent')
-#
-# # Clone specific branch of template
-# writer = Writer(Path("my_paper"), branch="develop")
-#
-# # No git (temporary work)
-# writer = Writer(Path("temp_work"), git_strategy=None)
-
-# Document operations (git-based version control)
-intro = writer.manuscript.contents.introduction
-lines = intro.read()            # Read file (uses scitex.io or fallback to plain text)
-intro.write(lines + ["# New"])  # Write file
-
-intro.commit("Update intro")     # Commit to git with message
-# intro.save() is not an alias - use commit() instead
-
-intro.history()                 # Show git log (returns list of commit messages)
-intro.diff()                    # Show uncommitted changes vs HEAD (returns diff string)
-intro.diff(ref="HEAD~1")        # Show uncommitted changes vs previous commit
-intro.diff(ref="main")          # Show uncommitted changes vs main branch
-
-intro.checkout("HEAD~1")        # Restore from previous version
-intro.checkout("HEAD")          # Restore from HEAD (returns bool: success)
-
-# Compilation
+# Compile manuscript
 result = writer.compile_manuscript()
 if result.success:
-    print(f"PDF: {result.output_pdf}")
-
-# Utilities
-pdf = writer.get_pdf()
-writer.watch()
-writer.delete()
-```
-
-**Git Strategies:**
-- **`'child'` (default)**: Isolated git repository in project directory
-  - Self-contained version history
-  - Can use git directly in project directory
-- **`'parent'`**: Use existing parent git repository
-  - Manuscript tracked in project's git repo
-  - Better for code + paper reproducibility
-- **`None`**: Disable git (for temporary work)
-
-## API Reference
-
-### Writer Class
-
-```python
-Writer(project_dir, name=None, git_strategy='child', branch=None)
-
-# Parameters:
-# - project_dir: Path to project directory
-# - name: Project name (optional, defaults to directory name)
-# - git_strategy: 'child' (default), 'parent', 'origin', or None
-# - branch: Specific branch of template to clone (optional)
-
-# Attributes:
-writer.project_dir       # Path to project
-writer.project_name      # Project name
-writer.git_root          # Git repository root (if using git)
-
-# Document trees:
-writer.manuscript        # ManuscriptTree with contents and sections
-writer.supplementary     # SupplementaryTree
-writer.revision          # RevisionTree
-writer.scripts           # ScriptsTree with compilation and utility scripts
-
-# Methods:
-writer.compile_manuscript(timeout=300)        # → CompilationResult
-writer.compile_supplementary(timeout=300)     # → CompilationResult
-writer.compile_revision(track_changes=False)  # → CompilationResult
-writer.watch(on_compile=None)                 # Auto-recompile on changes
-writer.get_pdf(doc_type='manuscript')         # → Path or None
-writer.delete()                               # → bool
-```
-
-### DocumentSection Class
-
-All manuscript/supplementary/revision sections are DocumentSection instances:
-
-```python
-section = writer.manuscript.contents.introduction  # Example
-
-# Methods:
-section.read()                     # → content (str or list)
-section.write(content)             # → bool
-section.commit(message)            # → bool (git add + commit)
-section.history()                  # → List[str] (git log messages)
-section.diff(ref="HEAD")          # → str (uncommitted changes vs ref, "" if none)
-section.diff_between(ref1, ref2)  # → str (compare any two git states)
-section.checkout(ref="HEAD")      # → bool (restore from git reference)
-
-# Attributes:
-section.path                       # → Path to file
-section.git_root                   # → Path to git root (if available)
-```
-
-### Available Sections
-
-**Manuscript Contents** (`writer.manuscript.contents.*`):
-- Core: abstract, introduction, methods, results, discussion
-- Metadata: title, authors, keywords, journal_name
-- Optional: graphical_abstract, highlights, data_availability, additional_info, wordcount
-- References: bibliography
-- Directories: figures/, tables/, latex_styles/
-
-**Supplementary & Revision**: Similar structure, customize as needed
-
-## Usage Examples
-
-### Basic Read/Write/Commit Workflow
-
-```python
-intro = writer.manuscript.contents.introduction
-
-# 1. Read current content
-lines = intro.read()
-
-# 2. Modify and write
-lines.append("New paragraph...")
-intro.write(lines)
-
-# 3. Check what changed (returns "" if no changes, diff string if changed)
-changes = intro.diff()
-if changes:
-    print("Changes detected:")
-    print(changes)
-
-    # 4. Commit when satisfied
-    intro.commit("Added new paragraph")
-else:
-    print("No changes to commit")
-```
-
-### Working with Git History
-
-```python
-# View full version history
-history = intro.history()
-for commit in history:
-    print(commit)  # Output: "abc1234 Commit message"
-
-# Compare uncommitted changes against different versions
-diff_prev = intro.diff(ref="HEAD~1")  # Uncommitted changes vs last commit
-diff_main = intro.diff(ref="main")    # Uncommitted changes vs main branch
-diff_tag = intro.diff(ref="v1.0")     # Uncommitted changes vs tag
-
-# Compare two arbitrary versions (no uncommitted changes needed)
-diff = intro.diff_between("v1.0", "v2.0")        # Between tags
-diff = intro.diff_between("HEAD~2", "HEAD")      # Between commits
-diff = intro.diff_between("main", "develop")     # Between branches
-
-# Time-based comparisons with human-readable timestamps
-diff = intro.diff_between("1 week ago", "now")   # Last week's changes
-diff = intro.diff_between("2 days ago", "HEAD")  # Last 2 days
-diff = intro.diff_between("2025-10-20", "2025-10-28")  # Between dates
-
-# Restore previous version
-intro.checkout("HEAD~1")  # Restore to last commit
-intro.checkout("main")    # Restore to main branch
-
-# After restore, commit if needed
-intro.commit("Reverted to previous version")
-```
-
-### Working with Scripts
-
-```python
-# Access compilation scripts
-scripts = writer.scripts
-
-# View script paths
-compile_script = scripts.compile_manuscript.path
-watch_script = scripts.watch_compile.path
-
-# Read script content
-content = scripts.compile_manuscript.read()
-
-# Modify scripts (with git tracking)
-new_content = scripts.compile_manuscript.read()
-# ... modify content ...
-scripts.compile_manuscript.write(new_content)
-scripts.compile_manuscript.commit("Update compilation script")
-
-# View script history
-history = scripts.compile_manuscript.history()
-diff = scripts.compile_manuscript.diff()
-```
-
-### Typical Edit Workflow
-
-```python
-# 1. Read current content
-content = intro.read()
-
-# 2. Make edits
-updated = content + "\n\nNew section..."
-intro.write(updated)
-
-# 3. Review changes
-print(intro.diff())
-
-# 4. Commit when satisfied
-if intro.diff():
-    intro.commit("Add new section")
-else:
-    print("No changes to commit")
-
-# 5. View history
-print(intro.history())
-```
-
-## CompilationResult
-
-```python
-result.success       # bool
-result.exit_code     # int
-result.output_pdf    # Path
-result.duration      # float (seconds)
-result.errors        # List[str]
-result.warnings      # List[str]
-result.stdout        # str
-result.stderr        # str
-result.log_file      # Path
-```
-
-## Project Structure
-
-Writer creates and manages the following directory structure:
-
-```
-project_dir/
-├── 01_manuscript/          # Main manuscript
-│   ├── abstract.tex
-│   ├── introduction.tex
-│   ├── methods.tex
-│   ├── results.tex
-│   ├── discussion.tex
-│   └── main.tex
-├── 02_supplementary/       # Supplementary materials
-│   ├── figures/
-│   └── tables/
-├── 03_revision/            # Revision/response documents
-└── .git/                   # Git repository (if using 'child' or 'parent' strategy)
-```
-
-## Error Handling
-
-Writer handles errors gracefully with clear logging:
-
-```python
-try:
-    writer = Writer("/path/to/project")
-except RuntimeError as e:
-    # Missing required directories (01_manuscript, 02_supplementary, 03_revision)
-    print(f"Invalid project structure: {e}")
-
-try:
-    result = writer.compile_manuscript()
-    if not result.success:
-        print(f"Compilation failed: {result.errors}")
-except Exception as e:
-    print(f"Compilation error: {e}")
-```
-
-**Common Issues:**
-- Invalid project structure: Ensure all 3 required directories exist
-- Git initialization failure: Check git installation and permissions
-- LaTeX compilation error: Check .tex files syntax and LaTeX installation
+    print(f"PDF created: {result.output_pdf}")
 
-## Testing
-
-Run the comprehensive test suite:
-
-```bash
-# Run all Writer tests
-python -m pytest src/scitex/writer/tests/test_writer_integration.py -v
+# Compile supplementary
+result = writer.compile_supplementary()
 
-# Run specific test class
-python -m pytest src/scitex/writer/tests/test_writer_integration.py::TestProjectAttachment -v
-
-# Run with coverage
-python -m pytest src/scitex/writer/tests/test_writer_integration.py --cov=scitex.writer
+# Compile revision with change tracking
+result = writer.compile_revision(track_changes=True)
 ```
 
-**Test Coverage:**
-- Project attachment and creation
-- Structure validation
-- Git strategy handling (child, parent, None)
-- Project name handling
-- Child git cleanup for parent strategy
+## Source of Truth
 
-## Recent Improvements
+The implementation lives in the `scitex-writer` package. This module (`scitex.writer`) simply re-exports from `scitex_writer`:
 
-### 2025-10-29: Live Streaming & Timeout Support
+- `Writer` - Main class for manuscript compilation
+- `CompilationResult` - Compilation result dataclass
+- `ManuscriptTree`, `SupplementaryTree`, `RevisionTree` - Document tree structures
+- `bib`, `compile`, `figures`, `guidelines`, `project`, `prompts`, `tables` - Submodules
 
-**Live Output Streaming** - See compilation progress in real-time:
-- **Real-time output**: View LaTeX compilation output as it happens, not buffered until completion
-- **ANSI color preservation**: Color-coded messages (INFO, SUCC, ERRO, WARNING) display correctly
-- **Progress visibility**: Know exactly which step is running and how long it takes
-- **Immediate error detection**: Errors appear instantly instead of after full compilation
-- **Stdbuf integration**: Forces line-buffered output for shell scripts
+## Direct Import
 
-**Timeout Support**:
-- **Configurable timeouts**: Default 300s (5 minutes), customizable per compilation
-- **Graceful termination**: Process killed cleanly on timeout
-- **Clear timeout messages**: Explicit notification when compilation exceeds time limit
-- **Works with streaming**: Timeout checks happen during execution, not after
+You can also import directly from scitex-writer:
 
-**Enhanced Compilation**:
 ```python
-# Compilation with default timeout (300s)
-result = writer.compile_manuscript()
-
-# Custom timeout
-result = writer.compile_manuscript(timeout=600)  # 10 minutes
-
-# Watch real-time output with color coding:
-# INFO: Running compilation...
-# SUCC: All required tools available
-# INFO: Pass 1/3: Initial (3s)
-# SUCC: PDF ready (828K)
-```
-
-**Implementation Details**:
-- Non-blocking I/O with `fcntl` for true streaming
-- Unbuffered subprocess execution (`bufsize=0`)
-- Environment variable propagation (`PYTHONUNBUFFERED=1`)
-- Progressive output reading without blocking
-- Separate stdout/stderr handling with immediate display
-
-**Test Coverage** - 64 comprehensive tests:
-- Real-time behavior verification (timing-based proofs)
-- ANSI color code preservation tests
-- Timeout during execution tests
-- Large output handling (100+ lines)
-- Stdbuf wrapper integration tests
-- Streaming vs buffered consistency tests
-
-**Benefits**:
-- 🔍 **Visibility**: See what's happening during long compilations (161s in example)
-- ⚡ **Responsiveness**: Decide to wait or interrupt based on live progress
-- 🎨 **Clarity**: Color-coded output for easy scanning
-- ⏱️ **Control**: Prevent runaway compilations with timeouts
-- 🐛 **Debugging**: Errors visible immediately with full context
-
-### 2025-10-28: Enhanced Git Integration & Temporal Queries
-
-**Bug Fixes**:
-- Fixed incomplete initialization that left `git_root` uninitialized
-- Removed blocking debug code (`ipdb.set_trace()`)
-- Fixed return type annotation in `_attach_or_create_project()`
-- Improved error handling with proper logging throughout
-
-**New Features**:
-- **Structure Validation**: Automatically verifies project has required directories (01_manuscript, 02_supplementary, 03_revision) when attaching
-- **Child Git Cleanup**: Automatically removes project's `.git/` when using `'parent'` strategy and parent repo is found, preventing nested git issues
-
-**Enhanced Logging**:
-- Detailed initialization logs with project name, directory, and git strategy
-- Clear strategy selection and progression messages
-- Explicit error messages with full context
-- Success confirmations for key operations
-
-**Enhanced diff() Capability**:
-- **New `diff_between()` method** for comparing any two arbitrary git states
-  - Compare commits: `diff_between("HEAD~2", "HEAD")`
-  - Compare releases: `diff_between("v1.0", "v2.0")`
-  - Compare branches: `diff_between("main", "develop")`
-  - **Time-aware ref resolution**: `diff_between("1 week ago", "now")`
-  - **Timestamp-based queries**: `diff_between("2025-10-20", "2025-10-28")`
-  - Supports human-readable specifications without breaking git functionality
-- **Reference resolution** (`_resolve_ref()`) handles:
-  - Standard git refs (HEAD, branches, tags, commit hashes)
-  - Relative time: "2 days ago", "1 week ago", "24 hours ago"
-  - Absolute dates: "2025-10-28", "2025-10-28 14:30"
-  - Timestamp-based commit finding with `git log --before`
-- 15 new tests for diff_between functionality (all passing)
-
-**Comprehensive Testing**:
-- 99 tests covering all Writer and DocumentSection functionality
-- DocumentSection operations fully tested (read/write/commit/history/diff/diff_between/checkout)
-- End-to-end workflow testing (project creation → document editing → git operations)
-- Temporal queries and reference resolution tested
-- Error handling and edge cases covered
-- All tests passing ✅
-
-**Test Coverage**:
-- Writer initialization and configuration
-- Project creation and attachment
-- Git strategy handling (child, parent, None)
-- Document section operations (read, write, commit)
-- Git operations (history, diff, checkout)
-- Tree structure verification
-- Error handling
-- Live streaming infrastructure
-- Timeout handling
-
-**Run tests**:
-```bash
-# Writer module tests
-pytest src/scitex/writer/tests/ -v
-
-# Shell/streaming infrastructure tests
-pytest tests/scitex/sh/ -v
+from scitex_writer import Writer, CompilationResult
 ```
 
-## Requirements
-
-- Python 3.8+
-- LaTeX distribution
-- Git (for version control)
+## Documentation
 
-<!-- EOF -->
+See [scitex-writer documentation](https://github.com/ywatanabe1989/scitex-writer) for full API reference.

scitex/writer/__init__.py

@@ -1,22 +1,62 @@
 #!/usr/bin/env python3
-"""
-SciTeX Writer - Thin wrapper delegating to scitex-writer package.
+# Timestamp: 2026-01-30
+# File: src/scitex/writer/__init__.py
+
+"""SciTeX Writer - LaTeX manuscript compilation system.
+
+This module provides a thin wrapper around scitex-writer, the core manuscript
+compilation package. It uses scitex branding and environment variable prefixes.
+
+Features
+--------
+- LaTeX manuscript compilation
+- Supplementary materials compilation
+- Revision response compilation with change tracking
+- BibTeX management
+- Figure/table management
+- Writing guidelines
+
+Usage
+-----
+    import scitex as stx
 
-Single source of truth: scitex-writer package
-This module re-exports scitex-writer as-is, without modifications.
+    # Create or attach to a project
+    writer = stx.writer.Writer("my_paper")
 
-Install: pip install scitex-writer
+    # Compile manuscript
+    result = writer.compile_manuscript()
+    if result.success:
+        print(f"PDF created: {result.output_pdf}")
+
+    # Compile supplementary
+    result = writer.compile_supplementary()
+
+    # Compile revision with change tracking
+    result = writer.compile_revision(track_changes=True)
+
+See Also
+--------
+- scitex-writer: https://github.com/ywatanabe1989/scitex-writer
+- scitex: https://scitex.ai
 """
 
 import os as _os
 
-# Set branding environment variables BEFORE importing scitex-writer
+# Set branding BEFORE importing scitex-writer
 _os.environ.setdefault("SCITEX_WRITER_BRAND", "scitex.writer")
 _os.environ.setdefault("SCITEX_WRITER_ALIAS", "sw")
 
-# Re-export from scitex-writer package (single source of truth)
+# Check scitex-writer availability
 try:
-    from scitex_writer import __version__ as writer_version
+    # Re-export main class and dataclasses
+    from scitex_writer import (
+        CompilationResult,
+        ManuscriptTree,
+        RevisionTree,
+        SupplementaryTree,
+        Writer,
+    )
+    from scitex_writer import __version__ as _writer_version
     from scitex_writer import (
         bib,
         compile,
@@ -27,11 +67,34 @@ try:
         tables,
     )
 
-    HAS_WRITER_PKG = True
+    WRITER_AVAILABLE = True
+    __writer_version__ = _writer_version
 
 except ImportError:
-    HAS_WRITER_PKG = False
-    writer_version = None
+    WRITER_AVAILABLE = False
+    __writer_version__ = None
+
+    # Provide helpful error on access
+    class _WriterNotAvailable:
+        """Placeholder when scitex-writer is not installed."""
+
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "scitex-writer is required for scitex.writer. "
+                "Install with: pip install scitex-writer"
+            )
+
+        def __getattr__(self, name):
+            raise ImportError(
+                "scitex-writer is required for scitex.writer. "
+                "Install with: pip install scitex-writer"
+            )
+
+    Writer = _WriterNotAvailable
+    CompilationResult = _WriterNotAvailable
+    ManuscriptTree = _WriterNotAvailable
+    SupplementaryTree = _WriterNotAvailable
+    RevisionTree = _WriterNotAvailable
     bib = None
     compile = None
     figures = None
@@ -40,9 +103,31 @@ except ImportError:
     prompts = None
     tables = None
 
+
+def has_writer() -> bool:
+    """Check if scitex-writer is available.
+
+    Returns
+    -------
+    bool
+        True if scitex-writer is installed and importable.
+    """
+    return WRITER_AVAILABLE
+
+
 __all__ = [
-    "HAS_WRITER_PKG",
-    "writer_version",
+    # Availability check
+    "WRITER_AVAILABLE",
+    "has_writer",
+    "__writer_version__",
+    # Main class
+    "Writer",
+    # Dataclasses
+    "CompilationResult",
+    "ManuscriptTree",
+    "SupplementaryTree",
+    "RevisionTree",
+    # Modules
     "bib",
     "compile",
     "figures",

{scitex-2.16.0.dist-info → scitex-2.16.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex
-Version: 2.16.0
+Version: 2.16.2
 Summary: A comprehensive Python library for scientific computing and data analysis
 Project-URL: Homepage, https://github.com/ywatanabe1989/scitex-python
 Project-URL: Documentation, https://scitex.readthedocs.io
@@ -62,6 +62,7 @@ Requires-Dist: catboost; extra == 'all'
 Requires-Dist: celery; extra == 'all'
 Requires-Dist: click; extra == 'all'
 Requires-Dist: crawl4ai; extra == 'all'
+Requires-Dist: crossref-local; extra == 'all'
 Requires-Dist: csv2latex; extra == 'all'
 Requires-Dist: dearpygui; extra == 'all'
 Requires-Dist: einops; extra == 'all'
@@ -102,6 +103,7 @@ Requires-Dist: nest-asyncio; extra == 'all'
 Requires-Dist: numcodecs; extra == 'all'
 Requires-Dist: obspy; extra == 'all'
 Requires-Dist: openai; extra == 'all'
+Requires-Dist: openalex-local; extra == 'all'
 Requires-Dist: opencv-python; extra == 'all'
 Requires-Dist: openpyxl; extra == 'all'
 Requires-Dist: optuna; extra == 'all'
@@ -140,6 +142,7 @@ Requires-Dist: scholarly; extra == 'all'
 Requires-Dist: scikit-image; extra == 'all'
 Requires-Dist: scikit-learn; extra == 'all'
 Requires-Dist: scipy; extra == 'all'
+Requires-Dist: scitex-writer; extra == 'all'
 Requires-Dist: seaborn; extra == 'all'
 Requires-Dist: selenium; extra == 'all'
 Requires-Dist: sktime; extra == 'all'
@@ -382,12 +385,14 @@ Requires-Dist: aiohttp; extra == 'scholar'
 Requires-Dist: beautifulsoup4; extra == 'scholar'
 Requires-Dist: bibtexparser; extra == 'scholar'
 Requires-Dist: crawl4ai; extra == 'scholar'
+Requires-Dist: crossref-local; extra == 'scholar'
 Requires-Dist: feedparser; extra == 'scholar'
 Requires-Dist: html2text; extra == 'scholar'
 Requires-Dist: httpx; extra == 'scholar'
 Requires-Dist: matplotlib; extra == 'scholar'
 Requires-Dist: natsort; extra == 'scholar'
 Requires-Dist: nest-asyncio; extra == 'scholar'
+Requires-Dist: openalex-local; extra == 'scholar'
 Requires-Dist: openpyxl; extra == 'scholar'
 Requires-Dist: pdfplumber; extra == 'scholar'
 Requires-Dist: pillow; extra == 'scholar'