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

scitex/cloud/_matplotlib_hook.py

@@ -49,18 +49,18 @@ def _cloud_show(*args, **kwargs):
                 return None
 
             # Use timestamp for this session's outputs
-            timestamp = time.strftime('%Y%m%d_%H%M%S')
-            output_dir = project_root / 'scitex' / 'temp' / timestamp
+            timestamp = time.strftime("%Y%m%d_%H%M%S")
+            output_dir = project_root / "scitex" / "temp" / timestamp
             output_dir.mkdir(parents=True, exist_ok=True)
 
             for fignum in fignums:
                 fig = plt.figure(fignum)
 
-                filename = f'figure_{fignum}.png'
+                filename = f"figure_{fignum}.png"
                 output_path = output_dir / filename
 
                 # Save figure
-                fig.savefig(output_path, dpi=150, bbox_inches='tight')
+                fig.savefig(output_path, dpi=150, bbox_inches="tight")
 
                 # Emit inline image marker with project-relative path
                 relative_path = output_path.relative_to(project_root)
@@ -139,8 +139,8 @@ if is_cloud_environment():
 
 
 __all__ = [
-    'install_matplotlib_hook',
-    'uninstall_matplotlib_hook',
+    "install_matplotlib_hook",
+    "uninstall_matplotlib_hook",
 ]
 
 # EOF

scitex/config/README.md

@@ -0,0 +1,313 @@
+<!-- ---
+!-- Timestamp: 2025-12-09
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/config/README.md
+!-- --- -->
+
+# SciTeX Configuration Module
+
+Centralized configuration management for the SciTeX ecosystem.
+
+## Overview
+
+This module provides:
+- **ScitexConfig**: YAML-based configuration with env var substitution (Scholar pattern)
+- **ScitexPaths**: Centralized path manager for all SciTeX directories
+- **PriorityConfig**: Dict-based configuration resolver (for programmatic use)
+- **CLI**: `scitex config list` command to view configuration
+
+## Priority Resolution Patterns
+
+### ScitexConfig (YAML-based, Recommended)
+
+Follows the Scholar module's `CascadeConfig` pattern:
+
+```
+1. Direct value (highest) - Thread-safe, explicit parameter
+2. Config (YAML)         - Values from default.yaml
+3. Environment variable  - SCITEX_*, etc.
+4. Default value         - Fallback (lowest)
+```
+
+**Key feature**: YAML can reference env vars using `${VAR:-default}` syntax.
+
+### PriorityConfig (Dict-based)
+
+For programmatic use with a dictionary:
+
+```
+1. Direct value (highest) - Explicit parameter
+2. Config dict           - From passed dictionary
+3. Environment variable  - SCITEX_*, etc.
+4. Default value         - Fallback (lowest)
+```
+
+## Quick Start
+
+### Using ScitexConfig (YAML-based)
+
+```python
+from scitex.config import get_config
+
+# Load default configuration
+config = get_config()
+
+# Resolve values with precedence: direct → config → env → default
+log_level = config.resolve("logging.level", default="INFO")
+debug = config.resolve("debug.enabled", default=False, type=bool)
+
+# Access raw config values
+print(config.get("scitex_dir"))  # Value from YAML
+
+# Load custom config
+custom_config = get_config("/path/to/custom.yaml")
+```
+
+### Using ScitexPaths (Recommended for paths)
+
+```python
+import scitex
+
+# Access via global PATHS constant
+print(scitex.PATHS.logs)           # ~/.scitex/logs
+print(scitex.PATHS.capture)        # ~/.scitex/capture
+print(scitex.PATHS.scholar_library) # ~/.scitex/scholar/library
+
+# Or import directly
+from scitex.config import get_paths
+
+paths = get_paths()  # Cached singleton
+
+# Use resolve() for configurable paths in modules
+cache_dir = paths.resolve("cache", user_provided_value)  # direct → default
+```
+
+### Using get_scitex_dir()
+
+```python
+from scitex.config import get_scitex_dir
+
+# Simple usage - respects SCITEX_DIR env var
+base_dir = get_scitex_dir()  # Returns Path
+
+# With direct override (thread-safe)
+base_dir = get_scitex_dir("/custom/path")
+```
+
+### Using PriorityConfig
+
+```python
+from scitex.config import PriorityConfig
+
+config = PriorityConfig(
+    config_dict={"port": 3000, "debug": True},
+    env_prefix="SCITEX_"
+)
+
+# Resolves: direct → env (SCITEX_PORT) → config_dict → default
+port = config.resolve("port", direct_val=None, default=8000, type=int)
+```
+
+## Pattern for Module Implementation
+
+When implementing a module that needs configurable paths, use the `resolve()` method:
+
+```python
+from typing import Optional
+from scitex.config import get_paths
+
+class MyModule:
+    def __init__(self, cache_dir: Optional[str] = None):
+        """
+        Args:
+            cache_dir: Custom cache directory. If None, uses default
+                      from SCITEX_DIR environment variable.
+        """
+        # resolve() handles: direct value → default (from SCITEX_DIR env → ~/.scitex)
+        self.cache_dir = get_paths().resolve("cache", cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+```
+
+The `resolve(path_name, direct_val)` method:
+- Returns `direct_val` if provided (highest priority)
+- Otherwise returns the default path from `SCITEX_DIR` environment variable
+- Falls back to `~/.scitex/<path>` if `SCITEX_DIR` is not set
+
+This pattern ensures:
+- **Thread-safety**: Direct values allow multi-user/multi-project scenarios
+- **Configurability**: Environment variables for deployment flexibility
+- **Sensible defaults**: Works out-of-the-box with `~/.scitex`
+- **Consistency**: Same pattern as `PriorityConfig.resolve()`
+
+## Directory Structure
+
+```
+$SCITEX_DIR/                    # Default: ~/.scitex
+├── browser/                    # Browser module data
+│   ├── screenshots/            # Browser debugging screenshots
+│   ├── sessions/               # Shared browser sessions
+│   └── persistent/             # Persistent browser profiles
+├── cache/                      # General cache
+│   └── functions/              # Function cache (joblib)
+├── capture/                    # Screen captures
+├── impact_factor_cache/        # Impact factor data
+├── logs/                       # Log files
+├── openathens_cache/           # OpenAthens auth cache
+├── rng/                        # Random number generator state
+├── scholar/                    # Scholar module
+│   ├── cache/                  # Scholar-specific cache
+│   └── library/                # PDF library
+├── screenshots/                # General screenshots
+├── test_monitor/               # Test monitoring screenshots
+└── writer/                     # Writer module data
+```
+
+## CLI Commands
+
+```bash
+# List all configured paths
+scitex config list
+
+# Include environment variable info
+scitex config list --env
+
+# Show only existing directories
+scitex config list --exists
+
+# Output as JSON
+scitex config list --json
+
+# Initialize all directories
+scitex config init
+scitex config init --dry-run
+
+# Show a specific path
+scitex config show logs
+scitex config show scholar_library
+```
+
+## YAML Configuration
+
+### default.yaml Format
+
+The `default.yaml` file supports environment variable substitution using `${VAR:-default}` syntax:
+
+```yaml
+# Base directory
+scitex_dir: ${SCITEX_DIR:-"~/.scitex"}
+
+# Nested configuration
+logging:
+  level: ${SCITEX_LOG_LEVEL:-"INFO"}
+  file_logging: ${SCITEX_FILE_LOGGING:-true}
+
+debug:
+  enabled: ${SCITEX_DEBUG:-false}
+```
+
+### Environment Variable Substitution
+
+| Syntax | Description | Example |
+|--------|-------------|---------|
+| `${VAR}` | Use env var (null if not set) | `${SCITEX_DIR}` |
+| `${VAR:-default}` | Use env var or default | `${SCITEX_DIR:-"~/.scitex"}` |
+
+### How It Works
+
+1. **YAML loads with substitution**: When YAML is loaded, `${VAR:-default}` expressions are replaced with environment variable values or defaults
+2. **Resolution respects priority**: When you call `config.resolve()`, it checks: direct → config (from YAML) → env → default
+
+Example:
+```yaml
+# In default.yaml
+log_level: ${SCITEX_LOG_LEVEL:-"INFO"}
+```
+
+```python
+# If SCITEX_LOG_LEVEL is not set:
+config.get("logging.level")  # Returns "INFO" (from YAML default)
+
+# If SCITEX_LOG_LEVEL=DEBUG:
+config.get("logging.level")  # Returns "DEBUG" (substituted at load time)
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SCITEX_DIR` | Base directory for all SciTeX data | `~/.scitex` |
+| `SCITEX_LOG_LEVEL` | Logging level | `INFO` |
+| `SCITEX_DEBUG` | Enable debug mode | `false` |
+
+## .env File Support
+
+The module automatically loads `.env` files from:
+1. Current working directory (`./.env`)
+2. Home directory (`~/.env`)
+
+Example `.env`:
+```bash
+SCITEX_DIR=/data/scitex
+SCITEX_LOG_LEVEL=DEBUG
+```
+
+Note: Environment variables set in shell take precedence over `.env` values.
+
+## Available Paths
+
+Access via `scitex.PATHS.<name>` or `get_paths().<name>`:
+
+| Property | Path |
+|----------|------|
+| `base` | `$SCITEX_DIR` |
+| `logs` | `$SCITEX_DIR/logs` |
+| `cache` | `$SCITEX_DIR/cache` |
+| `function_cache` | `$SCITEX_DIR/cache/functions` |
+| `capture` | `$SCITEX_DIR/capture` |
+| `screenshots` | `$SCITEX_DIR/screenshots` |
+| `rng` | `$SCITEX_DIR/rng` |
+| `browser` | `$SCITEX_DIR/browser` |
+| `browser_screenshots` | `$SCITEX_DIR/browser/screenshots` |
+| `browser_sessions` | `$SCITEX_DIR/browser/sessions` |
+| `browser_persistent` | `$SCITEX_DIR/browser/persistent` |
+| `test_monitor` | `$SCITEX_DIR/test_monitor` |
+| `impact_factor_cache` | `$SCITEX_DIR/impact_factor_cache` |
+| `openathens_cache` | `$SCITEX_DIR/openathens_cache` |
+| `scholar` | `$SCITEX_DIR/scholar` |
+| `scholar_cache` | `$SCITEX_DIR/scholar/cache` |
+| `scholar_library` | `$SCITEX_DIR/scholar/library` |
+| `writer` | `$SCITEX_DIR/writer` |
+
+## Thread-Safe Usage
+
+For multi-user or multi-project scenarios, pass explicit paths:
+
+```python
+from scitex.config import ScitexPaths
+
+# Each user/project gets isolated paths
+user1_paths = ScitexPaths(base_dir="/data/user1/.scitex")
+user2_paths = ScitexPaths(base_dir="/data/user2/.scitex")
+
+# Use in module initialization
+processor = DataProcessor(cache_dir=user1_paths.cache)
+```
+
+## Migration from Hardcoded Paths
+
+If you have code with hardcoded paths like:
+
+```python
+# Old (hardcoded)
+cache_dir = Path.home() / ".scitex" / "cache"
+```
+
+Replace with:
+
+```python
+# New (configurable)
+from scitex.config import get_paths
+cache_dir = get_paths().cache
+```
+
+<!-- EOF -->

scitex/config/{PriorityConfig.py → _PriorityConfig.py}

@@ -1,36 +1,133 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-# Timestamp: "2025-12-01 18:53:13 (ywatanabe)"
+# Timestamp: "2025-12-09 (ywatanabe)"
 # File: /home/ywatanabe/proj/scitex-code/src/scitex/config/PriorityConfig.py
 
 
 """
 Priority-based configuration resolver.
 
-Provides clean precedence hierarchy: direct → env → config → default
+Provides clean precedence hierarchy: direct → config_dict → env → default
 
 Based on priority-config by ywatanabe (https://github.com/ywatanabe1989/priority-config)
 Incorporated into scitex for self-contained configuration management.
+
+Note: config_dict values (from YAML or passed dict) take priority over
+environment variables. This follows the Scholar module's CascadeConfig pattern.
 """
 
 import os
+from pathlib import Path
 from typing import Dict
 from typing import List
 from typing import Optional, Type, Any
 
 
+def load_dotenv(dotenv_path: Optional[str] = None) -> bool:
+    """Load environment variables from .env file.
+
+    Searches for .env file in the following order:
+    1. Explicit dotenv_path if provided
+    2. Current working directory
+    3. User home directory
+
+    Parameters
+    ----------
+    dotenv_path : str, optional
+        Path to .env file. If None, searches default locations.
+
+    Returns
+    -------
+    bool
+        True if .env file was found and loaded, False otherwise.
+    """
+    paths_to_try = []
+
+    if dotenv_path:
+        paths_to_try.append(Path(dotenv_path))
+    else:
+        # Default search paths
+        paths_to_try.extend(
+            [
+                Path.cwd() / ".env",
+                Path.home() / ".env",
+            ]
+        )
+
+    for path in paths_to_try:
+        if path.exists() and path.is_file():
+            try:
+                with open(path, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        # Skip empty lines and comments
+                        if not line or line.startswith("#"):
+                            continue
+                        # Handle export prefix
+                        if line.startswith("export "):
+                            line = line[7:]
+                        # Parse key=value
+                        if "=" in line:
+                            key, _, value = line.partition("=")
+                            key = key.strip()
+                            value = value.strip()
+                            # Remove quotes if present
+                            if (value.startswith('"') and value.endswith('"')) or (
+                                value.startswith("'") and value.endswith("'")
+                            ):
+                                value = value[1:-1]
+                            # Only set if not already in environment (env takes precedence)
+                            if key not in os.environ:
+                                os.environ[key] = value
+                return True
+            except Exception:
+                continue
+    return False
+
+
+def get_scitex_dir(direct_val: Optional[str] = None) -> Path:
+    """Get SCITEX_DIR with priority: direct → env → default.
+
+    This is a convenience function for the most common use case.
+
+    Parameters
+    ----------
+    direct_val : str, optional
+        Direct value (highest precedence)
+
+    Returns
+    -------
+    Path
+        Resolved SCITEX_DIR path
+    """
+    # Try to load .env first (won't override existing env vars)
+    load_dotenv()
+
+    if direct_val is not None:
+        return Path(direct_val).expanduser()
+
+    env_val = os.getenv("SCITEX_DIR")
+    if env_val:
+        return Path(env_val).expanduser()
+
+    return Path.home() / ".scitex"
+
+
 class PriorityConfig:
-    """Universal config resolver with precedence: direct → env → config → default
+    """Universal config resolver with precedence: direct → config_dict → env → default
+
+    Config dict (from YAML or passed dict) takes priority over env variables.
+    This follows the Scholar module's CascadeConfig pattern.
 
     Examples
     --------
     >>> from scitex.config import PriorityConfig
     >>> config = PriorityConfig(config_dict={"port": 3000}, env_prefix="SCITEX_")
     >>> port = config.resolve("port", None, default=8000, type=int)
-    3000  # from config_dict (env not set)
-    >>> # With env: PORT=5000 python script.py
+    3000  # from config_dict (highest after direct)
+    >>> # With env: SCITEX_PORT=5000 python script.py
     >>> port = config.resolve("port", None, default=8000, type=int)
-    5000  # env takes precedence over config
+    3000  # config_dict takes precedence over env
     >>> port = config.resolve("port", 9000, default=8000, type=int)
     9000  # direct value takes highest precedence
     """
@@ -87,7 +184,10 @@ class PriorityConfig:
     ) -> Any:
         """Get value with precedence hierarchy.
 
-        Precedence: direct → env → config → default
+        Precedence: direct → config_dict → env → default
+
+        This follows the Scholar module's CascadeConfig pattern where
+        config dict takes higher priority than environment variables.
 
         Parameters
         ----------
@@ -115,16 +215,16 @@ class PriorityConfig:
         env_key = f"{self.env_prefix}{normalized_key.upper() if self.auto_uppercase else normalized_key}"
         env_val = os.getenv(env_key)
 
-        # Priority: direct → env → config → default
+        # Priority: direct → config_dict → env → default
         if direct_val is not None:
             source = "direct"
             final_value = direct_val
+        elif key in self.config_dict:
+            source = "config_dict"
+            final_value = self.config_dict[key]
         elif env_val:
             source = f"env:{env_key}"
             final_value = self._convert_type(env_val, type)
-        elif key in self.config_dict:
-            source = "config"
-            final_value = self.config_dict[key]
         else:
             source = "default"
             final_value = default
@@ -134,9 +234,7 @@ class PriorityConfig:
         else:
             should_mask = self._is_sensitive(key)
 
-        display_value = (
-            self._mask_value(final_value) if should_mask else final_value
-        )
+        display_value = self._mask_value(final_value) if should_mask else final_value
 
         self.resolution_log.append(
             {
@@ -158,9 +256,7 @@ class PriorityConfig:
         print("Configuration Resolution Log:")
         print("-" * 50)
         for entry in self.resolution_log:
-            print(
-                f"{entry['key']:<20} = {entry['value']:<20} ({entry['source']})"
-            )
+            print(f"{entry['key']:<20} = {entry['value']:<20} ({entry['source']})")
 
     def clear_log(self) -> None:
         """Clear resolution log."""
@@ -192,4 +288,5 @@ class PriorityConfig:
             return "****"
         return value_str[:2] + "*" * (len(value_str) - 4) + value_str[-2:]
 
+
 # EOF