scitex-template 0.1.0__py3-none-any.whl

scitex_template/README.md

@@ -0,0 +1,154 @@
+<!-- ---
+!-- Timestamp: 2025-10-29 05:56:40
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/template/README.md
+!-- --- -->
+
+# SciTeX Template Module
+
+Project template creation utilities for SciTeX ecosystem.
+
+## Available Templates
+
+### 1. Research Project (`clone_research`)
+Full scientific workflow structure for research projects.
+
+**Use case:** Scientific research with data analysis, experiments, and paper writing
+
+**Template:** [scitex_template_research](https://github.com/ywatanabe1989/scitex_template_research.git)
+
+**Features:**
+- `scripts/` - Analysis and preprocessing scripts
+- `data/` - Raw and processed data management
+- `docs/` - Manuscripts, notes, and references
+- `results/` - Analysis outputs and reports
+- `config/` - Project configuration files
+
+### 2. Python Package (`clone_pip_project`)
+Pip-installable Python package template.
+
+**Use case:** Creating distributable Python packages for PyPI
+
+**Template:** [pip-project-template](https://github.com/ywatanabe1989/pip-project-template.git)
+
+**Features:**
+- `src/` - Package source code
+- `tests/` - Unit and integration tests
+- `docs/` - Sphinx documentation
+- `setup.py` - Package configuration
+- CI/CD - GitHub Actions workflows
+
+### 3. Singularity Container (`clone_singularity`)
+Container-based project with Singularity.
+
+**Use case:** Reproducible computational environments with containers
+
+**Template:** [singularity-template](https://github.com/ywatanabe1989/singularity-template.git)
+
+**Features:**
+- Singularity definition files
+- Container build scripts
+- Environment specifications
+- Deployment configuration
+
+### 4. Paper Directory (`clone_writer_directory`)
+Academic paper writing template with scitex-writer.
+
+**Use case:** Writing academic papers with LaTeX and BibTeX management
+
+**Template:** [scitex-writer](git@github.com:ywatanabe1989/scitex-writer.git)
+
+**Features:**
+- LaTeX document structure
+- BibTeX bibliography management
+- Figure and table organization
+- Manuscript tracking
+
+## Git Strategy Options
+
+All template functions support a `git_strategy` parameter to control git initialization:
+
+- `"child"` (default): Creates new isolated git repository with initial commit and main/develop branches
+- `"parent"`: Uses existing parent git repository (degrades to "child" if not found)
+- `"origin"`: Preserves template's original git history for upstream tracking
+- `None`: Disables git initialization entirely
+
+## Usage
+
+### Python API
+
+```python
+from scitex.template import (
+    clone_research,
+    clone_pip_project,
+    clone_singularity,
+    clone_writer_directory,
+)
+
+# Create a research project
+clone_research("my_research_project")
+
+# Create with specific git strategy
+clone_pip_project("my_package", "~/projects", git_strategy="parent")
+
+# Preserve template git history
+clone_singularity("my_container", git_strategy="origin")
+
+# No git initialization
+clone_writer_directory("my_paper", "~/papers", git_strategy=None)
+```
+
+### Command Line
+
+```bash
+# Research project
+python -m scitex clone_research my_research_project
+python -m scitex clone_research my_project ~/projects
+
+# Python package
+python -m scitex clone_pip_project my_package
+python -m scitex clone_pip_project my_package ~/packages
+
+# Singularity container
+python -m scitex clone_singularity my_container
+python -m scitex clone_singularity my_container ~/containers
+
+# Paper directory
+python -m scitex clone_writer_directory my_paper
+python -m scitex clone_writer_directory my_paper ~/papers
+```
+
+### Get Template Information
+
+```python
+from scitex.template import get_available_templates_info
+
+templates = get_available_templates_info()
+for template in templates:
+    print(f"{template['name']}: {template['description']}")
+    print(f"  Use case: {template['use_case']}")
+    print(f"  GitHub: {template['github_url']}")
+```
+
+## What Happens When You Create a Project
+
+1. **Clone Template**: Downloads the template repository to a temporary directory
+2. **Handle Git History**: Based on git_strategy:
+   - `"child"`: Removes template's `.git` directory
+   - `"origin"`: Preserves template's `.git` directory
+   - `"parent"`: Removes template's `.git` directory
+3. **Copy to Target**: Copies template files to your target directory
+4. **Customize**: Renames template package/directories to match your project name
+5. **Update References**: Updates all references to the template name in files
+6. **Initialize Git**: Based on git_strategy:
+   - `"child"`: Creates new git repository with initial commit and `main`/`develop` branches
+   - `"parent"`: Uses existing parent repository
+   - `"origin"`: Keeps template's git history
+   - `None`: Skips git initialization
+
+## Requirements
+
+- Git must be installed and accessible in PATH
+- SSH keys configured for GitHub (for templates using SSH URLs)
+
+<!-- EOF -->

scitex_template/__init__.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# File: /home/ywatanabe/proj/scitex_repo/src/scitex/template/__init__.py
+
+"""
+Template management for SciTeX projects.
+"""
+
+from pathlib import Path
+
+from scitex.git import (
+    create_child_git,
+    find_parent_git,
+    init_git_repo,
+    remove_child_git,
+)
+
+from ._code._code_templates import (
+    CODE_TEMPLATES,
+    get_all_templates,
+    get_code_template,
+    list_code_templates,
+)
+from ._project._clone_template import clone_template
+from ._project._customize import customize_minimal_template, customize_template
+from ._project._directory_structure import (
+    PROJECT_STRUCTURE,
+    build_directory_tree,
+)
+from ._project._generate_configs import (
+    create_env_template,
+    create_paths_config,
+    create_project_config,
+    create_requirements_file,
+)
+from ._project._generate_readme import create_minimal_readme, create_project_readme
+from ._project._scholar_writer_integration import (
+    ensure_integration,
+    setup_scholar_writer_integration,
+)
+from ._project.clone_module import clone_module
+from ._project.clone_pip_project import TEMPLATE_REPO_URL as PIP_PROJECT_URL
+from ._project.clone_pip_project import clone_pip_project
+from ._project.clone_research import TEMPLATE_REPO_URL as RESEARCH_URL
+from ._project.clone_research import clone_research
+from ._project.clone_research_minimal import (
+    MINIMAL_INCLUDE_DIRS,
+    clone_research_minimal,
+)
+from ._project.clone_scitex_minimal import clone_scitex_minimal
+from ._project.clone_singularity import TEMPLATE_REPO_URL as SINGULARITY_URL
+from ._project.clone_singularity import clone_singularity
+from ._project.clone_writer_directory import TEMPLATE_REPO_URL as PAPER_DIRECTORY_URL
+from ._project.clone_writer_directory import clone_writer_directory
+
+
+def get_template_tree(template_id):
+    """Create template in a tempdir and return its ``tree`` output.
+
+    Actually runs the template's directory-creation logic in a
+    temporary directory on the fly, then captures the real ``tree``
+    output. This guarantees the displayed tree always matches
+    the current template code.
+
+    Parameters
+    ----------
+    template_id : str
+        Template identifier (e.g. 'minimal', 'research').
+
+    Returns
+    -------
+    str
+        ``tree`` output string, or empty string if unknown.
+    """
+    import shutil
+    import subprocess
+    import tempfile
+
+    from scitex.scholar.ensure_workspace import SCHOLAR_SUBDIRS
+
+    tmpdir = tempfile.mkdtemp(prefix="scitex_tree_")
+    try:
+        project_dir = Path(tmpdir) / "project"
+        project_dir.mkdir()
+
+        if template_id == "minimal":
+            # Reproduce scitex_minimal directory scaffold without git clone
+            writer_dir = project_dir / "scitex" / "writer"
+            for name in MINIMAL_INCLUDE_DIRS:
+                (writer_dir / name).mkdir(parents=True, exist_ok=True)
+            scholar_dir = project_dir / "scitex" / "scholar"
+            for name in SCHOLAR_SUBDIRS:
+                (scholar_dir / name).mkdir(parents=True, exist_ok=True)
+
+        elif template_id == "research":
+            build_directory_tree(str(project_dir), PROJECT_STRUCTURE)
+
+        elif template_id == "app":
+            # Reproduce pip-project-template structure
+            src_dir = project_dir / "src" / "package_name"
+            src_dir.mkdir(parents=True)
+            (src_dir / "__init__.py").touch()
+            tests_dir = project_dir / "tests"
+            tests_dir.mkdir()
+            (tests_dir / "__init__.py").touch()
+            (tests_dir / "test_main.py").touch()
+            (project_dir / "pyproject.toml").touch()
+            (project_dir / "README.md").touch()
+            (project_dir / "LICENSE").touch()
+
+        else:
+            return ""
+
+        result = subprocess.run(
+            ["tree", "--noreport", "--dirsfirst", str(project_dir)],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            # Replace the temp path prefix with "."
+            tree_output = result.stdout.strip()
+            first_newline = tree_output.find("\n")
+            if first_newline != -1:
+                return "." + tree_output[first_newline:]
+            return "."
+        return ""
+
+    except Exception:
+        return ""
+    finally:
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def get_available_templates_info():
+    """
+    Get information about all available SciTeX project templates.
+
+    Returns
+    -------
+    list[dict]
+        List of template information dictionaries, each containing:
+        - id: Template identifier (used in code)
+        - name: Human-readable template name
+        - description: Template description
+        - github_url: GitHub repository URL
+        - use_case: When to use this template
+        - tree: Tree-command-style directory listing
+
+    Example
+    -------
+    >>> from scitex.template import get_available_templates_info
+    >>> templates = get_available_templates_info()
+    >>> for template in templates:
+    ...     print(f"{template['name']}: {template['description']}")
+    """
+    return [
+        {
+            "id": "minimal",
+            "name": "SciTeX Minimal",
+            "description": "Minimal project with writer + scholar workspaces",
+            "github_url": RESEARCH_URL,
+            "use_case": "Manuscript writing with integrated bibliography management",
+            "tree": get_template_tree("minimal"),
+        },
+        {
+            "id": "research",
+            "name": "SciTeX Full",
+            "description": "Full scientific workflow with data analysis, experiments, and paper writing",
+            "github_url": RESEARCH_URL,
+            "use_case": "End-to-end scientific research projects",
+            "tree": get_template_tree("research"),
+        },
+        {
+            "id": "app",
+            "name": "SciTeX App",
+            "description": "Pip-installable Python package for building reusable SciTeX apps",
+            "github_url": PIP_PROJECT_URL,
+            "use_case": "Creating reusable tools and apps for the SciTeX ecosystem",
+            "tree": get_template_tree("app"),
+        },
+    ]
+
+
+__all__ = [
+    "clone_template",
+    "clone_module",
+    "clone_research",
+    "clone_research_minimal",
+    "clone_scitex_minimal",
+    "MINIMAL_INCLUDE_DIRS",
+    "clone_pip_project",
+    "clone_singularity",
+    "clone_writer_directory",
+    "get_available_templates_info",
+    "get_code_template",
+    "list_code_templates",
+    "get_all_templates",
+    "CODE_TEMPLATES",
+    "init_git_repo",
+    "find_parent_git",
+    "create_child_git",
+    "remove_child_git",
+    # Template customization (moved from Django)
+    "customize_template",
+    "customize_minimal_template",
+    "create_project_config",
+    "create_paths_config",
+    "create_env_template",
+    "create_requirements_file",
+    "create_minimal_readme",
+    "create_project_readme",
+    "build_directory_tree",
+    "PROJECT_STRUCTURE",
+    # Scholar-Writer integration
+    "setup_scholar_writer_integration",
+    "ensure_integration",
+]
+
+# EOF

scitex_template/_code/_code_templates.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Code templates for common SciTeX patterns.
+
+Provides ready-to-use code snippets for scripts and modules.
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# Import templates from subdirectory
+from .templates import CODE_TEMPLATES
+
+
+def get_code_template(
+    template_id: str,
+    filepath: Optional[str] = None,
+    docstring: Optional[str] = None,
+) -> str:
+    """
+    Get a code template by ID.
+
+    Parameters
+    ----------
+    template_id : str
+        Template identifier (session, session-minimal, session-plot, etc.)
+    filepath : str, optional
+        File path to include in template header.
+    docstring : str, optional
+        Custom docstring for the template.
+
+    Returns
+    -------
+    str
+        Formatted template content.
+    """
+    if template_id not in CODE_TEMPLATES:
+        available = ", ".join(CODE_TEMPLATES.keys())
+        raise ValueError(f"Unknown template: '{template_id}'. Available: {available}")
+
+    template = CODE_TEMPLATES[template_id]
+    content = template["content"]
+
+    # Format placeholders
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    filepath = filepath or template["filename"]
+    docstring = docstring or "Description of this script/module"
+
+    filename = Path(filepath).name
+    filename_stem = Path(filepath).stem
+
+    return content.format(
+        timestamp=timestamp,
+        filepath=filepath,
+        filename=filename,
+        filename_stem=filename_stem,
+        docstring=docstring,
+    )
+
+
+def list_code_templates():
+    """
+    List all available code templates.
+
+    Returns
+    -------
+    list[dict]
+        List of template info dictionaries.
+    """
+    return [
+        {
+            "id": tid,
+            "name": info["name"],
+            "description": info["description"],
+            "filename": info["filename"],
+            "usage": info.get("usage", ""),
+        }
+        for tid, info in CODE_TEMPLATES.items()
+    ]
+
+
+def get_all_templates() -> str:
+    """
+    Get all templates combined into one string.
+
+    Returns
+    -------
+    str
+        All templates with headers, ordered by priority:
+        1. session - Main workflow template
+        2. io - File I/O patterns
+        3. Others (config, module, etc.)
+    """
+    # Priority order
+    priority_order = [
+        # Core templates (priority 1-3)
+        "session",
+        "io",
+        "config",
+        # Session variants
+        "session-minimal",
+        "session-plot",
+        "session-stats",
+        "module",
+        # Module usage templates
+        "plt",
+        "stats",
+        "scholar",
+        "audio",
+        "capture",
+        "diagram",
+        "canvas",
+        "writer",
+    ]
+
+    sections = []
+    sections.append("=" * 70)
+    sections.append("SCITEX CODE TEMPLATES")
+    sections.append("=" * 70)
+
+    for tid in priority_order:
+        if tid not in CODE_TEMPLATES:
+            continue
+        info = CODE_TEMPLATES[tid]
+        sections.append("")
+        sections.append("-" * 70)
+        sections.append(f"TEMPLATE: {tid}")
+        sections.append(f"  {info['name']} - {info['description']}")
+        sections.append("-" * 70)
+        if info.get("usage"):
+            sections.append(info["usage"].strip())
+        sections.append("")
+        sections.append("```python" if not tid == "config" else "```yaml")
+        sections.append(info["content"].strip())
+        sections.append("```")
+
+    return "\n".join(sections)
+
+
+__all__ = [
+    "get_code_template",
+    "list_code_templates",
+    "get_all_templates",
+    "CODE_TEMPLATES",
+]
+
+# EOF

scitex_template/_code/templates/__init__.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Code templates registry - loads all template definitions."""
+
+# Core templates (priority 1-3)
+from .audio import TEMPLATE as AUDIO
+from .canvas import TEMPLATE as CANVAS
+from .capture import TEMPLATE as CAPTURE
+from .config import TEMPLATE as CONFIG
+from .diagram import TEMPLATE as DIAGRAM
+from .io import TEMPLATE as IO
+
+# Module template
+from .module import TEMPLATE as MODULE
+
+# Module usage templates (priority 4+)
+from .plt import TEMPLATE as PLT
+from .scholar import TEMPLATE as SCHOLAR
+from .session import TEMPLATE as SESSION
+
+# Session variants
+from .session_minimal import TEMPLATE as SESSION_MINIMAL
+from .session_plot import TEMPLATE as SESSION_PLOT
+from .session_stats import TEMPLATE as SESSION_STATS
+from .stats import TEMPLATE as STATS
+from .writer import TEMPLATE as WRITER
+
+CODE_TEMPLATES = {
+    # Priority 1-3: Core templates
+    "session": SESSION,
+    "io": IO,
+    "config": CONFIG,
+    # Session variants
+    "session-minimal": SESSION_MINIMAL,
+    "session-plot": SESSION_PLOT,
+    "session-stats": SESSION_STATS,
+    # Module template
+    "module": MODULE,
+    # Module usage templates
+    "plt": PLT,
+    "stats": STATS,
+    "scholar": SCHOLAR,
+    "audio": AUDIO,
+    "capture": CAPTURE,
+    "diagram": DIAGRAM,
+    "canvas": CANVAS,
+    "writer": WRITER,
+}
+
+__all__ = ["CODE_TEMPLATES"]
+
+# EOF