figrecipe 0.7.4__py3-none-any.whl → 0.9.0__py3-none-any.whl

figrecipe/__init__.py

@@ -59,8 +59,31 @@ from numpy.typing import NDArray
 # Notebook utilities
 from ._api._notebook import enable_svg
 
+# Panel label
+from ._api._panel import panel_label
+
 # Seaborn proxy
 from ._api._seaborn_proxy import sns
+
+# Composition API
+from ._composition import (
+    AlignmentMode,
+    align_panels,
+    compose,
+    distribute_panels,
+    hide_panel,
+    import_axes,
+    show_panel,
+    smart_align,
+    toggle_panel,
+)
+
+# scitex.stats integration
+from ._integrations import (
+    SCITEX_STATS_AVAILABLE,
+    annotate_from_stats,
+    from_scitex_stats,
+)
 from ._recorder import CallRecord, FigureRecord
 from ._reproducer import get_recipe_info
 from ._reproducer import reproduce as _reproduce
@@ -78,14 +101,20 @@ from ._validator import ValidationResult
 from ._wrappers import RecordingAxes, RecordingFigure
 from .styles._style_applier import check_font, list_available_fonts
 
-__version__ = "0.7.2"
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("figrecipe")
+except Exception:
+    __version__ = "0.0.0"  # Fallback for development
 __all__ = [
     # Main API
     "subplots",
     "save",
     "reproduce",
+    "load",  # Alias for reproduce
     "info",
-    "load",
+    "load_record",
     "extract_data",
     "validate",
     # GUI Editor
@@ -120,6 +149,21 @@ __all__ = [
     "crop",
     # Panel labels
     "panel_label",
+    # Composition
+    "compose",
+    "import_axes",
+    "hide_panel",
+    "show_panel",
+    "toggle_panel",
+    # Alignment
+    "AlignmentMode",
+    "align_panels",
+    "distribute_panels",
+    "smart_align",
+    # scitex.stats integration
+    "from_scitex_stats",
+    "annotate_from_stats",
+    "SCITEX_STATS_AVAILABLE",
     # Version
     "__version__",
 ]
@@ -302,11 +346,15 @@ def info(path: Union[str, Path]) -> Dict[str, Any]:
     return get_recipe_info(path)
 
 
-def load(path: Union[str, Path]) -> FigureRecord:
-    """Load a recipe as a FigureRecord object."""
+def load_record(path: Union[str, Path]) -> FigureRecord:
+    """Load a recipe as a FigureRecord object (advanced use)."""
     return load_recipe(path)
 
 
+# Alias for intuitive save/load symmetry
+load = reproduce
+
+
 def extract_data(path: Union[str, Path]) -> Dict[str, Dict[str, Any]]:
     """Extract data arrays from a saved recipe.
 
@@ -390,26 +438,37 @@ def crop(
 
 
 def edit(
-    source,
+    source=None,
     style=None,
     port: int = 5050,
+    host: str = "127.0.0.1",
     open_browser: bool = True,
     hot_reload: bool = False,
+    working_dir=None,
+    desktop: bool = False,
 ):
     """Launch interactive GUI editor for figure styling.
 
     Parameters
     ----------
-    source : RecordingFigure, str, or Path
-        Either a live RecordingFigure object or path to a .yaml recipe file.
+    source : RecordingFigure, str, Path, or None
+        Either a live RecordingFigure object, path to a .yaml recipe file,
+        or None to create a new blank figure.
     style : str or dict, optional
         Style preset name or style dict.
     port : int, optional
         Flask server port (default: 5050).
+    host : str, optional
+        Host to bind Flask server (default: "127.0.0.1", use "0.0.0.0" for Docker).
     open_browser : bool, optional
         Whether to open browser automatically (default: True).
     hot_reload : bool, optional
         Enable hot reload (default: False).
+    working_dir : str or Path, optional
+        Working directory for file browser (default: directory containing source).
+    desktop : bool, optional
+        Launch as native desktop window using pywebview (default: False).
+        Requires: pip install figrecipe[desktop]
 
     Returns
     -------
@@ -419,73 +478,12 @@ def edit(
     from ._editor import edit as _edit
 
     return _edit(
-        source, style=style, port=port, open_browser=open_browser, hot_reload=hot_reload
+        source,
+        style=style,
+        port=port,
+        host=host,
+        open_browser=open_browser,
+        hot_reload=hot_reload,
+        working_dir=working_dir,
+        desktop=desktop,
     )
-
-
-def panel_label(
-    ax,
-    label: str,
-    loc: str = "upper left",
-    fontsize: Optional[float] = None,
-    fontweight: str = "bold",
-    offset: Tuple[float, float] = (-0.1, 1.05),
-    **kwargs,
-):
-    """Add a panel label (A, B, C, ...) to an axes.
-
-    Parameters
-    ----------
-    ax : Axes or RecordingAxes
-        The axes to label.
-    label : str
-        The label text (e.g., 'A', 'B', 'a)', '(1)').
-    loc : str, optional
-        Label location: 'upper left', 'upper right', etc.
-    fontsize : float, optional
-        Font size in points.
-    fontweight : str, optional
-        Font weight (default: 'bold').
-    offset : tuple of float, optional
-        (x, y) offset in axes coordinates.
-    **kwargs
-        Additional arguments passed to ax.text().
-
-    Returns
-    -------
-    Text
-        The matplotlib Text object.
-    """
-    import matplotlib.pyplot as mpl_plt
-
-    from ._api._panel import calculate_panel_position, get_panel_label_fontsize
-
-    fontsize = get_panel_label_fontsize(fontsize)
-    x, y = calculate_panel_position(loc, offset)
-
-    default_color = mpl_plt.rcParams.get("text.color", "black")
-
-    text_kwargs = {
-        "fontsize": fontsize,
-        "fontweight": fontweight,
-        "color": default_color,
-        "transform": "axes",
-        "va": "bottom",
-        "ha": "right" if "right" in loc else "left",
-    }
-    text_kwargs.update(kwargs)
-
-    mpl_ax = ax._ax if hasattr(ax, "_ax") else ax
-
-    render_kwargs = text_kwargs.copy()
-    render_kwargs["transform"] = mpl_ax.transAxes
-
-    if hasattr(ax, "_recorder") and hasattr(ax, "_position"):
-        ax._recorder.record_call(
-            ax_position=ax._position,
-            method_name="text",
-            args=(x, y, label),
-            kwargs=text_kwargs,
-        )
-
-    return mpl_ax.text(x, y, label, **render_kwargs)

figrecipe/__main__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""figrecipe CLI entry point.
+
+Allows running figrecipe as a module:
+    python -m figrecipe <command>
+"""
+
+from ._cli import main
+
+if __name__ == "__main__":
+    main()

figrecipe/_api/_panel.py

@@ -38,9 +38,76 @@ def calculate_panel_position(
     return x, y
 
 
+def panel_label(
+    ax,
+    label: str,
+    loc: str = "upper left",
+    fontsize: Optional[float] = None,
+    fontweight: str = "bold",
+    offset: Tuple[float, float] = (-0.1, 1.05),
+    **kwargs,
+):
+    """Add a panel label (A, B, C, ...) to an axes.
+
+    Parameters
+    ----------
+    ax : Axes or RecordingAxes
+        The axes to label.
+    label : str
+        The label text (e.g., 'A', 'B', 'a)', '(1)').
+    loc : str, optional
+        Label location: 'upper left', 'upper right', etc.
+    fontsize : float, optional
+        Font size in points.
+    fontweight : str, optional
+        Font weight (default: 'bold').
+    offset : tuple of float, optional
+        (x, y) offset in axes coordinates.
+    **kwargs
+        Additional arguments passed to ax.text().
+
+    Returns
+    -------
+    Text
+        The matplotlib Text object.
+    """
+    import matplotlib.pyplot as mpl_plt
+
+    fontsize = get_panel_label_fontsize(fontsize)
+    x, y = calculate_panel_position(loc, offset)
+
+    default_color = mpl_plt.rcParams.get("text.color", "black")
+
+    text_kwargs = {
+        "fontsize": fontsize,
+        "fontweight": fontweight,
+        "color": default_color,
+        "transform": "axes",
+        "va": "bottom",
+        "ha": "right" if "right" in loc else "left",
+    }
+    text_kwargs.update(kwargs)
+
+    mpl_ax = ax._ax if hasattr(ax, "_ax") else ax
+
+    render_kwargs = text_kwargs.copy()
+    render_kwargs["transform"] = mpl_ax.transAxes
+
+    if hasattr(ax, "_recorder") and hasattr(ax, "_position"):
+        ax._recorder.record_call(
+            ax_position=ax._position,
+            method_name="text",
+            args=(x, y, label),
+            kwargs=text_kwargs,
+        )
+
+    return mpl_ax.text(x, y, label, **render_kwargs)
+
+
 __all__ = [
     "get_panel_label_fontsize",
     "calculate_panel_position",
+    "panel_label",
 ]
 
 # EOF

figrecipe/_api/_save.py

@@ -2,6 +2,9 @@
 # -*- coding: utf-8 -*-
 """Save function helpers for the public API."""
 
+import shutil
+import tempfile
+import zipfile
 from pathlib import Path
 from typing import Optional, Tuple
 
@@ -17,6 +20,7 @@ IMAGE_EXTENSIONS = {
     ".tif",
 }
 YAML_EXTENSIONS = {".yaml", ".yml"}
+BUNDLE_RECIPE_NAME = "recipe.yaml"
 
 
 def resolve_save_paths(
@@ -101,6 +105,76 @@ def get_save_transparency() -> bool:
     return False
 
 
+def _is_bundle_path(path: Path) -> bool:
+    """Check if path represents a bundle (directory or ZIP)."""
+    suffix = path.suffix.lower()
+    # ZIP file
+    if suffix == ".zip":
+        return True
+    # Existing directory
+    if path.is_dir():
+        return True
+    # Path ending with / (explicit directory)
+    if str(path).endswith("/"):
+        return True
+    # No extension and doesn't look like a file
+    if not suffix and not path.exists():
+        return True
+    return False
+
+
+def _save_as_bundle(
+    fig,
+    path: Path,
+    include_data: bool,
+    data_format: str,
+    dpi: int,
+    transparent: bool,
+    image_format: str,
+    verbose: bool,
+) -> Tuple[Path, Path]:
+    """Save figure as a bundle (directory or ZIP)."""
+    suffix = path.suffix.lower()
+    is_zip = suffix == ".zip"
+
+    # Create temporary directory for bundle contents
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+
+        # Determine image format
+        img_format = image_format or _get_default_image_format()
+        image_name = f"figure.{img_format}"
+
+        # Save image
+        image_path = tmpdir / image_name
+        fig.fig.savefig(
+            image_path, dpi=dpi, bbox_inches="tight", transparent=transparent
+        )
+
+        # Save recipe
+        yaml_path = tmpdir / BUNDLE_RECIPE_NAME
+        fig.save_recipe(yaml_path, include_data=include_data, data_format=data_format)
+
+        if is_zip:
+            # Create ZIP bundle
+            zip_path = path.with_suffix(".zip")
+            with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.write(yaml_path, BUNDLE_RECIPE_NAME)
+                zf.write(image_path, image_name)
+            if verbose:
+                print(f"Saved: {zip_path} (ZIP bundle)")
+            return zip_path, zip_path
+        else:
+            # Create directory bundle
+            bundle_dir = Path(str(path).rstrip("/"))
+            bundle_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(yaml_path, bundle_dir / BUNDLE_RECIPE_NAME)
+            shutil.copy2(image_path, bundle_dir / image_name)
+            if verbose:
+                print(f"Saved: {bundle_dir}/ (directory bundle)")
+            return bundle_dir, bundle_dir / BUNDLE_RECIPE_NAME
+
+
 def save_figure(
     fig,
     path,
@@ -113,7 +187,14 @@ def save_figure(
     dpi: Optional[int] = None,
     image_format: Optional[str] = None,
 ):
-    """Core save implementation."""
+    """Core save implementation.
+
+    Supports multiple output formats:
+    - Image file (.png, .pdf, etc.): Saves image + .yaml recipe
+    - YAML file (.yaml): Saves recipe + image
+    - Directory (path/ or no extension): Saves as bundle directory
+    - ZIP file (.zip): Saves as ZIP bundle
+    """
     from .._wrappers import RecordingFigure
 
     path = Path(path)
@@ -124,9 +205,6 @@ def save_figure(
             "a recording-enabled figure."
         )
 
-    # Resolve paths
-    image_path, yaml_path, _ = resolve_save_paths(path, image_format)
-
     # Get DPI and transparency from style if not specified
     dpi = get_save_dpi(dpi)
     transparent = get_save_transparency()
@@ -145,6 +223,24 @@ def save_figure(
         finalize_ticks(ax)
         finalize_special_plots(ax, style_dict)
 
+    # Check if saving as bundle
+    if _is_bundle_path(path):
+        bundle_path, yaml_path = _save_as_bundle(
+            fig,
+            path,
+            include_data,
+            data_format,
+            dpi,
+            transparent,
+            image_format or _get_default_image_format(),
+            verbose,
+        )
+        # No validation for bundles (yet)
+        return bundle_path, yaml_path, None
+
+    # Resolve paths for standard save
+    image_path, yaml_path, _ = resolve_save_paths(path, image_format)
+
     # Save the image
     fig.fig.savefig(image_path, dpi=dpi, bbox_inches="tight", transparent=transparent)
 

figrecipe/_cli/__init__.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""figrecipe CLI - Command-line interface for figrecipe."""
+
+from ._main import main
+
+__all__ = ["main"]

figrecipe/_cli/_compose.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""compose command - Combine multiple figures."""
+
+from pathlib import Path
+from typing import Optional, Tuple
+
+import click
+
+
+@click.command()
+@click.argument("sources", nargs=-1, type=click.Path(exists=True), required=True)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(),
+    required=True,
+    help="Output path for composed figure.",
+)
+@click.option(
+    "--layout",
+    type=click.Choice(["horizontal", "vertical", "grid"]),
+    default="horizontal",
+    help="Layout arrangement (default: horizontal).",
+)
+@click.option(
+    "--cols",
+    type=int,
+    help="Number of columns for grid layout.",
+)
+@click.option(
+    "--dpi",
+    type=int,
+    default=300,
+    help="DPI for output (default: 300).",
+)
+def compose(
+    sources: Tuple[str, ...],
+    output: str,
+    layout: str,
+    cols: Optional[int],
+    dpi: int,
+) -> None:
+    """Compose multiple figures into one.
+
+    SOURCES are paths to .yaml recipe files or bundle directories.
+    """
+    from .. import compose as fr_compose
+    from .. import reproduce, save
+
+    if len(sources) < 2:
+        raise click.ClickException("At least 2 source figures required.")
+
+    source_paths = [Path(s) for s in sources]
+    output_path = Path(output)
+
+    # Determine grid dimensions
+    n = len(sources)
+    if layout == "horizontal":
+        nrows, ncols = 1, n
+    elif layout == "vertical":
+        nrows, ncols = n, 1
+    else:  # grid
+        if cols:
+            ncols = cols
+            nrows = (n + cols - 1) // cols
+        else:
+            # Auto-determine roughly square grid
+            import math
+
+            ncols = math.ceil(math.sqrt(n))
+            nrows = math.ceil(n / ncols)
+
+    # Reproduce and compose figures
+    try:
+        figures = []
+        for src in source_paths:
+            fig, _ = reproduce(src)
+            figures.append(fig)
+
+        composed = fr_compose(*figures, nrows=nrows, ncols=ncols)
+        save(composed, output_path, dpi=dpi)
+
+        click.echo(f"Composed {len(figures)} figures: {output_path}")
+
+    except Exception as e:
+        raise click.ClickException(f"Composition failed: {e}") from e

figrecipe/_cli/_convert.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""convert command - Convert between formats."""
+
+from pathlib import Path
+from typing import Optional
+
+import click
+
+
+@click.command()
+@click.argument("source", type=click.Path(exists=True))
+@click.option(
+    "-f",
+    "--format",
+    "fmt",
+    type=click.Choice(["png", "pdf", "svg", "yaml"]),
+    required=True,
+    help="Target format.",
+)
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(),
+    help="Output path.",
+)
+@click.option(
+    "--dpi",
+    type=int,
+    default=300,
+    help="DPI for raster output (default: 300).",
+)
+def convert(
+    source: str,
+    fmt: str,
+    output: Optional[str],
+    dpi: int,
+) -> None:
+    """Convert between figure formats.
+
+    SOURCE is a .yaml recipe or image file.
+    """
+    source_path = Path(source)
+
+    # Determine output path
+    if output:
+        output_path = Path(output)
+    else:
+        output_path = source_path.with_suffix(f".{fmt}")
+
+    # Handle different source types
+    if source_path.suffix in [".yaml", ".yml"]:
+        _convert_from_recipe(source_path, output_path, fmt, dpi)
+    elif source_path.suffix in [".png", ".pdf", ".svg"]:
+        _convert_image(source_path, output_path, fmt, dpi)
+    else:
+        raise click.ClickException(f"Unsupported source format: {source_path.suffix}")
+
+
+def _convert_from_recipe(source: Path, output: Path, fmt: str, dpi: int) -> None:
+    """Convert from YAML recipe to image format."""
+    import matplotlib.pyplot as plt
+
+    from .. import reproduce
+
+    try:
+        fig, _ = reproduce(source)
+
+        if fmt == "yaml":
+            # Already have YAML, just copy
+            import shutil
+
+            shutil.copy(source, output)
+        else:
+            fig.savefig(output, dpi=dpi, format=fmt)
+
+        # Close the figure (handle both regular and Recording figures)
+        try:
+            plt.close(fig)
+        except TypeError:
+            plt.close("all")
+
+        click.echo(f"Converted: {output}")
+
+    except Exception as e:
+        raise click.ClickException(f"Conversion failed: {e}") from e
+
+
+def _convert_image(source: Path, output: Path, fmt: str, dpi: int) -> None:
+    """Convert between image formats."""
+    if fmt == "yaml":
+        raise click.ClickException(
+            "Cannot convert image to YAML. Use a recipe file instead."
+        )
+
+    try:
+        from PIL import Image
+
+        img = Image.open(source)
+
+        if fmt == "pdf":
+            img.save(output, "PDF", resolution=dpi)
+        elif fmt == "svg":
+            raise click.ClickException(
+                "Cannot convert raster image to SVG. Use a recipe file instead."
+            )
+        else:
+            img.save(output, fmt.upper())
+
+        click.echo(f"Converted: {output}")
+
+    except ImportError:
+        raise click.ClickException(
+            "Image conversion requires Pillow. Install with: pip install figrecipe[imaging]"
+        ) from None
+    except Exception as e:
+        raise click.ClickException(f"Conversion failed: {e}") from e