scitex 2.1.3__py3-none-any.whl → 2.3.0__py3-none-any.whl

scitex/gen/_deprecated_close.py

@@ -16,7 +16,7 @@ This module provides backward compatibility by forwarding calls to the new
 scitex.session.close function while showing deprecation warnings.
 """
 
-from ..decorators._deprecated import deprecated
+from scitex.decorators._deprecated import deprecated
 
 
 @deprecated(
@@ -42,7 +42,7 @@ def close(*args, **kwargs):
         Same return value as scitex.session.close()
     """
     # Import here to avoid circular dependencies
-    from ..session import close as session_close
+    from scitex.session import close as session_close
 
     return session_close(*args, **kwargs)
 
@@ -70,7 +70,7 @@ def running2finished(*args, **kwargs):
         Same return value as scitex.session.running2finished()
     """
     # Import here to avoid circular dependencies
-    from ..session import running2finished as session_running2finished
+    from scitex.session import running2finished as session_running2finished
 
     return session_running2finished(*args, **kwargs)
 

scitex/gen/_deprecated_start.py

@@ -9,7 +9,7 @@ This module provides backward compatibility by forwarding calls to the new
 scitex.session.start function while showing deprecation warnings.
 """
 
-from ..decorators._deprecated import deprecated
+from scitex.decorators._deprecated import deprecated
 
 
 @deprecated(

scitex/gen/_norm.py

@@ -7,8 +7,8 @@ THIS_FILE = "/home/ywatanabe/proj/scitex_repo/src/scitex/gen/_norm.py"
 
 import torch
 
-from ..decorators import torch_fn
-from ..torch import nanstd
+from scitex.decorators import torch_fn
+from scitex.torch import nanstd
 
 
 @torch_fn

scitex/gen/_norm_cache.py

@@ -14,7 +14,7 @@ from functools import lru_cache
 from typing import Union, Tuple, Optional
 import hashlib
 
-from ..decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 # Cache for normalized data

scitex/gen/_symlink.py

@@ -4,7 +4,7 @@
 # File: ./scitex_repo/src/scitex/gen/_symlink.py
 
 import os
-from ..str._color_text import color_text
+from scitex.str._color_text import color_text
 
 
 def symlink(tgt, src, force=False):

scitex/gen/_to_rank.py

@@ -10,7 +10,7 @@
 import torch
 
 # from .._converters import
-from ..decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 @torch_fn

scitex/gen/_transpose.py

@@ -3,7 +3,7 @@
 # Time-stamp: "2024-08-24 09:47:16 (ywatanabe)"
 # ./src/scitex/gen/_transpose.py
 
-from ..decorators import numpy_fn
+from scitex.decorators import numpy_fn
 import numpy as np
 
 

scitex/git/_branch.py

@@ -16,7 +16,7 @@ Examples
 
 from pathlib import Path
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._utils import _in_directory
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 from ._validation import validate_branch_name, validate_path
@@ -76,7 +76,8 @@ def git_branch_rename(repo_path: Path, new_name: str, verbose: bool = True) -> b
             logger.error(f"Failed to rename branch in {repo_path}: {error_msg}")
             return False
 
-        logger.info(f"Branch renamed to {new_name}")
+        if verbose:
+            logger.info(f"Branch renamed to {new_name}")
         return True
 
 
@@ -132,7 +133,8 @@ def git_checkout_new_branch(repo_path: Path, branch_name: str, verbose: bool = T
             logger.error(f"Failed to create branch {branch_name} in {repo_path}: {error_msg}")
             return False
 
-        logger.info(f"Switched to new branch: {branch_name}")
+        if verbose:
+            logger.info(f"Switched to new branch: {branch_name}")
         return True
 
 

scitex/git/_clone.py

@@ -8,13 +8,13 @@ Git clone operations.
 
 from pathlib import Path
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 
 logger = getLogger(__name__)
 
 
-def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
+def clone_repo(url: str, target_path: Path, branch: str = None, tag: str = None, verbose: bool = True) -> bool:
     """
     Safely clone a git repository.
 
@@ -24,6 +24,12 @@ def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
         Git repository URL
     target_path : Path
         Destination path for cloning
+    branch : str, optional
+        Specific branch to clone. If None, clones the default branch.
+        Mutually exclusive with tag parameter.
+    tag : str, optional
+        Specific tag/release to clone. If None, clones the default branch.
+        Mutually exclusive with branch parameter.
     verbose : bool
         Enable verbose output
 
@@ -31,15 +37,34 @@ def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
     -------
     bool
         True if successful, False otherwise
+
+    Raises
+    ------
+    ValueError
+        If both branch and tag are specified
     """
     from ._remote import _validate_git_url
 
+    # Validate mutual exclusivity
+    if branch and tag:
+        raise ValueError("Cannot specify both 'branch' and 'tag' parameters. They are mutually exclusive.")
+
     if not _validate_git_url(url):
         logger.error(f"Invalid git URL: {url}")
         return False
 
+    cmd = ["git", "clone"]
+    ref_info = ""
+    if branch:
+        cmd.extend(["--branch", branch])
+        ref_info = f" (branch: {branch})"
+    elif tag:
+        cmd.extend(["--branch", tag])
+        ref_info = f" (tag: {tag})"
+    cmd.extend([url, str(target_path)])
+
     result = sh(
-        ["git", "clone", url, str(target_path)],
+        cmd,
         verbose=verbose,
         return_as="dict"
     )
@@ -48,7 +73,8 @@ def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
         logger.error(f"Failed to clone repository: {result['stderr']}")
         return False
 
-    logger.info("Repository cloned successfully")
+    if verbose:
+        logger.info(f"Repository cloned successfully{ref_info}")
     return True
 
 
@@ -85,7 +111,8 @@ def git_init(repo_path: Path, verbose: bool = True) -> bool:
             logger.warning(f"Failed to initialize git repository: {result['stderr']}")
             return False
 
-        logger.info("Git repository initialized")
+        if verbose:
+            logger.info("Git repository initialized")
         return True
 
 
@@ -94,7 +121,7 @@ def main(args):
         if not args.url:
             logger.error("URL required for clone action")
             return EXIT_FAILURE
-        success = clone_repo(args.url, args.path, args.verbose)
+        success = clone_repo(args.url, args.path, branch=args.branch, tag=args.tag, verbose=args.verbose)
         return EXIT_SUCCESS if success else EXIT_FAILURE
     elif args.action == "init":
         success = git_init(args.path, args.verbose)
@@ -108,6 +135,8 @@ def parse_args():
     parser.add_argument("--action", choices=["clone", "init"], required=True)
     parser.add_argument("--url", help="Repository URL for cloning")
     parser.add_argument("--path", type=Path, required=True)
+    parser.add_argument("--branch", help="Branch to clone (mutually exclusive with --tag)")
+    parser.add_argument("--tag", help="Tag/release to clone (mutually exclusive with --branch)")
     parser.add_argument("--verbose", action="store_true")
     return parser.parse_args()
 

scitex/git/_commit.py

@@ -17,7 +17,7 @@ Examples
 
 from pathlib import Path
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._utils import _in_directory
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 from ._validation import validate_commit_message, validate_path
@@ -126,7 +126,8 @@ def git_commit(repo_path: Path, message: str, verbose: bool = True) -> bool:
             logger.error(f"Failed to commit in {repo_path}: {error_msg}")
             return False
 
-        logger.info("Commit created successfully")
+        if verbose:
+            logger.info("Commit created successfully")
         return True
 
 

scitex/git/_remote.py

@@ -9,7 +9,7 @@ Git remote operations.
 from pathlib import Path
 from typing import Optional
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._utils import _in_directory
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 

scitex/git/_session.py

@@ -32,7 +32,7 @@ def run_with_session(parse_args_func, main_func):
 
     args = parse_args_func()
 
-    CONFIG, sys.stdout, sys.stderr, plt_obj, CC, rng = stx.session.start(
+    CONFIG, sys.stdout, sys.stderr, plt_obj, CC, rng_manager = stx.session.start(
         sys,
         plt,
         args=args,

scitex/git/_workflow.py

@@ -62,7 +62,7 @@ def _rollback_commit(repo_path: Path, verbose: bool = True) -> None:
     verbose : bool
         Enable verbose output
     """
-    from scitex._sh import sh
+    from scitex.sh import sh
     from ._utils import _in_directory
     from scitex.logging import getLogger
 

scitex/io/README.md

@@ -79,7 +79,7 @@ scitex.io.save(model.state_dict(), 'model.pth')
 
 # Save an image using PIL
 image = Image.new('RGB', (100, 100), color='red')
-scitex.io.save(image, 'image.jpg')
+scitex.io.save(image, 'image.png')  # Use PNG for lossless quality
 
 # Save a dictionary as a JSON file
 data = {'name': 'Alice', 'age': 30}
@@ -90,7 +90,71 @@ text = "Hello, World!"
 scitex.io.save(text, 'hello.txt')
 ```
 
+## ⚠️ File Format Best Practices for Scientific Figures
 
+### **NEVER use JPEG for scientific figures!**
+
+JPEG uses lossy compression that creates artifacts around text, lines, and sharp edges, making it unsuitable for scientific figures.
+
+#### Recommended Formats:
+
+1. **PNG (Portable Network Graphics)** ✅ BEST for raster figures
+   - **Lossless compression** - no quality loss
+   - Perfect for figures with text, lines, and solid colors
+   - Supports transparency
+   - Metadata preserved (scitex stores full metadata in PNG tEXt chunks)
+   - Auto-cropping preserves quality and DPI
+   ```python
+   scitex.io.save(fig, 'figure.png', dpi=300, auto_crop=True)
+   ```
+
+2. **PDF (Portable Document Format)** ✅ BEST for vector graphics
+   - **Vector format** - infinite zoom without quality loss
+   - Required by most scientific journals
+   - Smaller file size for line art
+   - Metadata preserved (scitex stores metadata in PDF Subject field)
+   ```python
+   scitex.io.save(fig, 'figure.pdf')
+   ```
+
+3. **JPEG (Joint Photographic Experts Group)** ❌ NEVER for scientific figures
+   - **Lossy compression** - creates visible artifacts
+   - Degrades quality around text and lines
+   - Not suitable for graphs, plots, or diagrams
+   - Only use for photographs
+
+#### Example - Publication-Ready Figure Saving:
+
+```python
+import scitex as stx
+
+# Create publication figure
+fig, ax = stx.plt.subplots(**stx.plt.presets.SCITEX_STYLE)
+ax.plot(x, y, label='Data')
+ax.set_xlabel('Time [s]')
+ax.set_ylabel('Amplitude [a.u.]')
+ax.legend()
+
+# Save in publication formats (PNG + PDF)
+stx.io.save(fig, 'figure1.png', dpi=300, auto_crop=True)  # Lossless raster
+stx.io.save(fig, 'figure1.pdf')                           # Vector format
+
+# DO NOT save as JPEG - it creates artifacts!
+# stx.io.save(fig, 'figure1.jpg')  # ❌ WRONG - lossy compression!
+```
+
+#### Auto-Cropping Feature:
+
+By default (`auto_crop=True`), figures are automatically cropped to content with 1mm margin:
+- Removes excess whitespace
+- Preserves image quality (PNG: lossless, PDF: vector)
+- Preserves DPI metadata (300 DPI for publication)
+- Preserves scitex metadata (version, style, dimensions, etc.)
+
+```python
+# Auto-crop is enabled by default
+stx.io.save(fig, 'figure.png')  # Automatically cropped, metadata preserved
+```
 
 <summary>Advanced Usage</summary>
 

scitex/io/__init__.py

@@ -69,6 +69,14 @@ except ImportError:
     migrate_h5_to_zarr = None
     migrate_h5_to_zarr_batch = None
 
+# Import metadata functions
+try:
+    from ._metadata import read_metadata, embed_metadata, has_metadata
+except ImportError:
+    read_metadata = None
+    embed_metadata = None
+    has_metadata = None
+
 __all__ = [
     "save",
     "load",
@@ -99,6 +107,10 @@ __all__ = [
     "get_cache_info",
     "configure_cache",
     "clear_load_cache",
+    # Metadata functions
+    "read_metadata",
+    "embed_metadata",
+    "has_metadata",
 ]
 
 # EOF

scitex/io/_glob.py

@@ -9,7 +9,7 @@ import re as _re
 from glob import glob as _glob
 from pathlib import Path
 from typing import Union
-from ..str._parse import parse as _parse
+from scitex.str._parse import parse as _parse
 from natsort import natsorted as _natsorted
 
 

scitex/io/_load.py

@@ -13,8 +13,8 @@ import glob
 from pathlib import Path
 from typing import Any, Union
 
-from ..decorators import preserve_doc
-from ..str._clean_path import clean_path
+from scitex.decorators import preserve_doc
+from scitex.str._clean_path import clean_path
 from ._load_cache import (
     cache_data,
     configure_cache,
@@ -52,6 +52,7 @@ def load(
     show: bool = False,
     verbose: bool = False,
     cache: bool = True,
+    metadata: bool = None,  # None = auto-detect (True for images)
     **kwargs,
 ) -> Any:
     """
@@ -73,14 +74,30 @@ def load(
         If True, print verbose output during loading. Default is False.
     cache : bool, optional
         If True, enable caching for faster repeated loads. Default is True.
+    metadata : bool or None, optional
+        If True, return tuple (data, metadata_dict) for images and PDFs.
+        If False, return data only.
+        If None (default), automatically True for images, False for PDFs and other formats.
+        Works for image files (.png, .jpg, .jpeg, .tiff, .tif) and PDF files.
+        For PDFs, metadata_dict contains embedded scitex metadata from PDF Subject field.
     **kwargs : dict
         Additional keyword arguments to be passed to the specific loading function.
+        For PDFs, can include: mode='full'|'text'|'scientific', etc.
 
     Returns
     -------
     object
         The loaded data object, which can be of various types depending on the input file format.
 
+        For images with metadata=True (default):
+            Returns tuple (image, metadata_dict). metadata_dict is None if no metadata found.
+
+        For PDFs with metadata=False (default):
+            Returns dict with keys: 'full_text', 'sections', 'metadata', 'pages', etc.
+
+        For PDFs with metadata=True:
+            Returns tuple (pdf_data_dict, metadata_dict). Enables consistent API with images.
+
     Raises
     ------
     ValueError
@@ -100,9 +117,27 @@ def load(
 
     Examples
     --------
+    >>> # Load CSV data
     >>> data = load('data.csv')
-    >>> image = load('image.png')
-    >>> model = load('model.pth')
+
+    >>> # Load image with metadata (default behavior)
+    >>> img, meta = load('figure.png')
+    >>> print(meta['scitex']['version'])
+
+    >>> # Load image without metadata
+    >>> img = load('figure.png', metadata=False)
+
+    >>> # Load PDF with default extraction (no metadata tuple)
+    >>> pdf = load('paper.pdf')
+    >>> print(pdf['full_text'])
+
+    >>> # Load PDF with metadata tuple (consistent API with images)
+    >>> pdf, meta = load('paper.pdf', metadata=True)
+    >>> print(meta['scitex']['version'])
+
+    >>> # Load PDF with specific mode
+    >>> text = load('paper.pdf', mode='text')
+
     >>> # Load file without extension (e.g., UUID PDF)
     >>> pdf = load('f2694ccb-1b6f-4994-add8-5111fd4d52f1', ext='pdf')
     """
@@ -156,8 +191,8 @@ def load(
             except Exception:
                 raise FileNotFoundError(f"File not found: {lpath}")
 
-    # Try to get from cache first
-    if cache:
+    # Try to get from cache first (skip cache if metadata is requested for images)
+    if cache and not metadata:
         cached_data = get_cached_data(lpath)
         if cached_data is not None:
             if verbose:
@@ -233,6 +268,14 @@ def load(
         # Auto-detect from filename
         detected_ext = lpath.split(".")[-1] if "." in lpath else ""
 
+    # Auto-detect metadata for images and PDFs
+    is_image = detected_ext in ["jpg", "jpeg", "png", "tiff", "tif"]
+    is_pdf = detected_ext == "pdf"
+
+    if metadata is None:
+        # Default: True for images, False for other formats (PDFs default to False for backward compatibility)
+        metadata = is_image
+
     # Special handling for numpy files with caching
     if cache and detected_ext in ["npy", "npz"]:
         return load_npy_cached(lpath, **kwargs)
@@ -240,10 +283,17 @@ def load(
     loader = preserve_doc(loaders_dict.get(detected_ext, _load_txt))
 
     try:
-        result = loader(lpath, **kwargs)
+        # Pass metadata parameter for images and PDFs
+        if is_image:
+            result = loader(lpath, metadata=metadata, verbose=verbose, **kwargs)
+        elif is_pdf:
+            # Pass metadata parameter to PDF loader for API consistency
+            result = loader(lpath, metadata=metadata, **kwargs)
+        else:
+            result = loader(lpath, **kwargs)
 
-        # Cache the result if caching is enabled
-        if cache:
+        # Cache the result if caching is enabled (skip if metadata was used)
+        if cache and not metadata:
             cache_data(lpath, result)
             if verbose:
                 print(f"[Cache STORED] Cached data for: {lpath}")

scitex/io/_load_configs.py

@@ -14,7 +14,7 @@ __DIR__ = os.path.dirname(__FILE__)
 from pathlib import Path
 from typing import Optional, Union
 
-from ..dict import DotDict
+from scitex.dict import DotDict
 from ._glob import glob
 from ._load import load
 
@@ -78,14 +78,17 @@ def load_configs(
             )
         )
 
-        # Load and merge configs
+        # Load and merge configs (namespaced by filename)
         CONFIGS = {}
 
         # Load from main config directory
         config_pattern = f"{config_dir}/*.yaml"
         for lpath in glob(config_pattern):
             if config := load(lpath):
-                CONFIGS.update(apply_debug_values(config, IS_DEBUG))
+                # Extract filename without extension as namespace
+                filename = Path(lpath).stem
+                # Apply debug values and namespace under filename
+                CONFIGS[filename] = apply_debug_values(config, IS_DEBUG)
 
         # Load from categories subdirectory if it exists
         categories_dir = f"{config_dir}/categories"
@@ -93,7 +96,9 @@ def load_configs(
             categories_pattern = f"{categories_dir}/*.yaml"
             for lpath in glob(categories_pattern):
                 if config := load(lpath):
-                    CONFIGS.update(apply_debug_values(config, IS_DEBUG))
+                    # Extract filename without extension as namespace
+                    filename = Path(lpath).stem
+                    CONFIGS[filename] = apply_debug_values(config, IS_DEBUG)
 
         return DotDict(CONFIGS)
 

scitex/io/_load_modules/_image.py

@@ -3,17 +3,61 @@
 # Time-stamp: "2024-11-14 07:55:38 (ywatanabe)"
 # File: ./scitex_repo/src/scitex/io/_load_modules/_image.py
 
-from typing import Any
+import logging
+from typing import Any, Dict, Optional, Tuple, Union
 
 from PIL import Image
 
+logger = logging.getLogger(__name__)
 
-def _load_image(lpath: str, **kwargs) -> Any:
-    """Load image file."""
+
+def _load_image(lpath: str, metadata: bool = True, verbose: bool = False, **kwargs) -> Union[Any, Tuple[Any, Optional[Dict]]]:
+    """
+    Load image file.
+
+    Args:
+        lpath: Path to image file
+        metadata: If True, return (image, metadata_dict) tuple. Default True.
+        verbose: If True, log information about metadata loading. Default False.
+        **kwargs: Additional arguments passed to Image.open()
+
+    Returns:
+        By default (metadata=True): (PIL.Image, dict) tuple
+        If metadata=False: PIL.Image object only
+        If no metadata found, returns (PIL.Image, None)
+    """
     supported_exts = [".jpg", ".jpeg", ".png", ".tiff", ".tif"]
     if not any(lpath.lower().endswith(ext) for ext in supported_exts):
         raise ValueError("Unsupported image format")
-    return Image.open(lpath, **kwargs)
+
+    img = Image.open(lpath, **kwargs)
+
+    if not metadata:
+        return img
+
+    # Try to read metadata
+    if verbose:
+        logger.info(f"✅ Loading image with metadata from: {lpath}")
+
+    try:
+        from .._metadata import read_metadata
+        metadata_dict = read_metadata(lpath)
+
+        if verbose:
+            if metadata_dict:
+                logger.info(f"  • Embedded metadata found:")
+                for key, value in metadata_dict.items():
+                    logger.info(f"    - {key}: {value}")
+            else:
+                logger.info("  • No embedded metadata found")
+
+        return img, metadata_dict
+
+    except Exception as e:
+        # If metadata reading fails, return None
+        import warnings
+        warnings.warn(f"Failed to read metadata: {e}")
+        return img, None
 
 
 # EOF