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

scitex/config/_ScitexConfig.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-09 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/config/ScitexConfig.py
+
+"""
+YAML-based configuration for SciTeX with environment variable substitution.
+
+Similar to ScholarConfig, provides:
+- YAML configuration loading
+- Environment variable substitution (${VAR:-default} syntax)
+- Cascade resolution (direct → config → env → default)
+
+Usage:
+    from scitex.config import ScitexConfig
+
+    # Load default configuration
+    config = ScitexConfig()
+
+    # Load custom configuration
+    config = ScitexConfig(config_path="/path/to/config.yaml")
+
+    # Resolve values with precedence
+    log_level = config.resolve("logging.level", default="INFO")
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional, Type, Union
+
+from ._PriorityConfig import PriorityConfig, load_dotenv
+
+
+def load_yaml(path: Path) -> dict:
+    """Load YAML file with environment variable substitution.
+
+    Supports ${VAR:-default} syntax for environment variable expansion.
+
+    Parameters
+    ----------
+    path : Path
+        Path to YAML file
+
+    Returns
+    -------
+    dict
+        Parsed YAML with environment variables substituted
+    """
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError(
+            "PyYAML required for YAML config. Install with: pip install pyyaml"
+        )
+
+    try:
+        with open(path) as f:
+            content = f.read()
+
+        def env_replacer(match):
+            """Replace ${VAR:-default} with environment variable or default."""
+            env_expr = match.group(1)
+            if ":-" in env_expr:
+                var_name, default_value = env_expr.split(":-", 1)
+                value = os.getenv(var_name, default_value.strip('"'))
+            else:
+                value = os.getenv(env_expr)
+
+            # Handle special values
+            if value in ["true", "false"]:
+                return value
+            elif value == "null":
+                return "null"
+            elif value and not (value.startswith('"') and value.endswith('"')):
+                return f'"{value}"'
+            else:
+                return value or "null"
+
+        content = re.sub(r"\$\{([^}]+)\}", env_replacer, content)
+        return yaml.safe_load(content)
+    except Exception as e:
+        raise ValueError(f"Failed to load YAML config from {path}: {e}")
+
+
+class ScitexConfig:
+    """YAML-based configuration manager for SciTeX.
+
+    Loads configuration from YAML files with environment variable substitution.
+    Values can be resolved with priority: direct → config → env → default.
+
+    Examples
+    --------
+    >>> from scitex.config import ScitexConfig
+    >>> config = ScitexConfig()
+    >>> config.resolve("logging.level", default="INFO")
+    'INFO'
+    >>> config.get("debug.enabled")
+    False
+    """
+
+    def __init__(
+        self,
+        config_path: Optional[Union[str, Path]] = None,
+        env_prefix: str = "SCITEX_",
+    ):
+        """Initialize ScitexConfig.
+
+        Parameters
+        ----------
+        config_path : str or Path, optional
+            Path to custom YAML config file. If None, uses default.yaml.
+        env_prefix : str
+            Prefix for environment variables (default: "SCITEX_")
+        """
+        # Load .env file first
+        load_dotenv()
+
+        # Load YAML configuration
+        if config_path and Path(config_path).exists():
+            self._config_data = load_yaml(Path(config_path))
+            self._config_path = Path(config_path)
+        else:
+            default_path = Path(__file__).parent / "default.yaml"
+            if default_path.exists():
+                self._config_data = load_yaml(default_path)
+            else:
+                self._config_data = {}
+            self._config_path = default_path
+
+        # Flatten nested config for easy access
+        self._flat_config = self._flatten_dict(self._config_data)
+
+        # Initialize PriorityConfig for resolution
+        self._priority_config = PriorityConfig(
+            config_dict=self._flat_config,
+            env_prefix=env_prefix,
+        )
+
+    def _flatten_dict(self, d: dict, parent_key: str = "", sep: str = ".") -> dict:
+        """Flatten nested dictionary with dot notation keys.
+
+        Parameters
+        ----------
+        d : dict
+            Dictionary to flatten
+        parent_key : str
+            Parent key for recursion
+        sep : str
+            Separator for nested keys
+
+        Returns
+        -------
+        dict
+            Flattened dictionary
+        """
+        items = []
+        for k, v in d.items():
+            new_key = f"{parent_key}{sep}{k}" if parent_key else k
+            if isinstance(v, dict):
+                items.extend(self._flatten_dict(v, new_key, sep).items())
+            else:
+                items.append((new_key, v))
+        return dict(items)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get value from config directly (no precedence resolution).
+
+        Supports dot notation for nested keys.
+
+        Parameters
+        ----------
+        key : str
+            Configuration key (e.g., "logging.level" or "debug.enabled")
+        default : Any
+            Default value if key not found
+
+        Returns
+        -------
+        Any
+            Configuration value
+        """
+        return self._flat_config.get(key, default)
+
+    def resolve(
+        self,
+        key: str,
+        direct_val: Any = None,
+        default: Any = None,
+        type: Type = str,
+    ) -> Any:
+        """Resolve value with precedence: direct → config → env → default.
+
+        This follows the Scholar module's CascadeConfig pattern where
+        YAML config takes higher priority than environment variables.
+
+        Parameters
+        ----------
+        key : str
+            Configuration key (e.g., "logging.level")
+        direct_val : Any
+            Direct value (highest precedence)
+        default : Any
+            Default value (lowest precedence)
+        type : Type
+            Type conversion (str, int, float, bool, list)
+
+        Returns
+        -------
+        Any
+            Resolved value
+        """
+        # Priority: direct → config → env → default
+        # (Same as Scholar's CascadeConfig pattern)
+        if direct_val is not None:
+            return direct_val
+
+        # Config (YAML) takes priority over env
+        config_val = self._flat_config.get(key)
+        if config_val is not None:
+            return config_val
+
+        # Then check environment variable
+        normalized_key = key.replace(".", "_")
+        env_key = f"SCITEX_{normalized_key.upper()}"
+        env_val = os.getenv(env_key)
+        if env_val:
+            return self._convert_type(env_val, type)
+
+        return default
+
+    def _convert_type(self, value: str, type: Type) -> Any:
+        """Convert string value to specified type."""
+        if type == int:
+            return int(value)
+        elif type == float:
+            return float(value)
+        elif type == bool:
+            return value.lower() in ("true", "1", "yes")
+        elif type == list:
+            return value.split(",")
+        return value
+
+    def get_nested(self, *keys: str, default: Any = None) -> Any:
+        """Get nested value from original config structure.
+
+        Parameters
+        ----------
+        *keys : str
+            Keys to traverse (e.g., "browser", "screenshots_dir")
+        default : Any
+            Default value if not found
+
+        Returns
+        -------
+        Any
+            Nested value
+        """
+        current = self._config_data
+        for key in keys:
+            if isinstance(current, dict) and key in current:
+                current = current[key]
+            else:
+                return default
+        return current
+
+    @property
+    def config_path(self) -> Path:
+        """Get the path to the loaded config file."""
+        return self._config_path
+
+    @property
+    def raw(self) -> dict:
+        """Get raw configuration data (original nested structure)."""
+        return self._config_data
+
+    @property
+    def flat(self) -> dict:
+        """Get flattened configuration data."""
+        return self._flat_config
+
+    def print(self) -> None:
+        """Print configuration resolution log."""
+        self._priority_config.print_resolutions()
+
+    def __repr__(self) -> str:
+        return f"ScitexConfig(path='{self._config_path}')"
+
+
+# Module-level convenience functions
+
+_default_config: Optional[ScitexConfig] = None
+
+
+def get_config(config_path: Optional[Union[str, Path]] = None) -> ScitexConfig:
+    """Get ScitexConfig instance.
+
+    Parameters
+    ----------
+    config_path : str or Path, optional
+        Path to custom config. If None, returns cached default instance.
+
+    Returns
+    -------
+    ScitexConfig
+        Configuration instance
+    """
+    global _default_config
+
+    if config_path is not None:
+        return ScitexConfig(config_path)
+
+    if _default_config is None:
+        _default_config = ScitexConfig()
+
+    return _default_config
+
+
+# EOF

scitex/config/__init__.py

@@ -1,24 +1,56 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-# Timestamp: "2025-12-01 21:00:00 (ywatanabe)"
+# Timestamp: "2025-12-09 (ywatanabe)"
 # File: ./src/scitex/config/__init__.py
 
 """
 SciTeX configuration module.
 
-Provides priority-based configuration resolution with clean precedence:
-direct → config → env → default
+Provides two configuration patterns (both use same priority order):
+
+1. **ScitexConfig** (YAML-based, recommended):
+   - Loads configuration from YAML files
+   - YAML supports env var substitution: ${VAR:-default}
+
+2. **PriorityConfig** (dict-based, for programmatic use):
+   - Uses a Python dictionary for configuration
+
+**Priority Order** (same for both):
+   direct → config (YAML/dict) → env → default
 
 Usage:
-    from scitex.config import PriorityConfig
+    from scitex.config import ScitexConfig, ScitexPaths, get_config, get_paths
 
-    config = PriorityConfig(config_dict={"port": 3000}, env_prefix="SCITEX_")
-    port = config.resolve("port", None, default=8000, type=int)
-"""
+    # YAML-based configuration (Scholar pattern)
+    config = get_config()
+    log_level = config.resolve("logging.level", default="INFO")
+
+    # Centralized path manager
+    paths = get_paths()
+    print(paths.logs)      # ~/.scitex/logs
+    print(paths.cache)     # ~/.scitex/cache
 
-from .PriorityConfig import PriorityConfig
+    # Use resolve() pattern in modules
+    cache_dir = paths.resolve("cache", user_provided_path)
+"""
 
-__all__ = ["PriorityConfig"]
+from ._PriorityConfig import PriorityConfig, get_scitex_dir, load_dotenv
+from ._paths import ScitexPaths, get_paths
+from ._ScitexConfig import ScitexConfig, get_config, load_yaml
+
+__all__ = [
+    # YAML-based config (Scholar pattern)
+    "ScitexConfig",
+    "get_config",
+    "load_yaml",
+    # Path management
+    "ScitexPaths",
+    "get_paths",
+    # Legacy/utility
+    "PriorityConfig",
+    "get_scitex_dir",
+    "load_dotenv",
+]
 
 
 # EOF

scitex/config/_paths.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-12-09 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/config/paths.py
+
+"""
+Centralized path management for SciTeX.
+
+Provides a single source of truth for all directory paths used across
+the SciTeX ecosystem. All paths respect the SCITEX_DIR environment variable.
+
+Usage:
+    from scitex.config import ScitexPaths
+
+    paths = ScitexPaths()
+
+    # Method 1: Direct property access (uses default)
+    print(paths.logs)           # ~/.scitex/logs
+    print(paths.cache)          # ~/.scitex/cache
+
+    # Method 2: resolve() with direct value override (recommended for modules)
+    cache_dir = paths.resolve("cache", direct_val=user_provided_path)
+    # If user_provided_path is None -> uses default from SCITEX_DIR
+
+    # Thread-safe: pass explicit base_dir
+    paths = ScitexPaths(base_dir="/custom/path")
+"""
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+from ._PriorityConfig import get_scitex_dir, load_dotenv
+
+
+class ScitexPaths:
+    """Centralized path manager for SciTeX directories.
+
+    All paths are derived from SCITEX_DIR (default: ~/.scitex).
+    Priority: direct_val → SCITEX_DIR env → .env file → default
+
+    Directory Structure:
+        $SCITEX_DIR/
+        ├── browser/              # Browser profiles and 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 cache
+        ├── logs/                 # Log files
+        ├── openathens_cache/     # OpenAthens auth cache
+        ├── rng/                  # Random number generator state
+        ├── scholar/              # Scholar module data
+        │   ├── cache/            # Scholar-specific cache
+        │   └── library/          # PDF library
+        ├── screenshots/          # General screenshots
+        ├── test_monitor/         # Test monitoring screenshots
+        └── writer/               # Writer module data
+    """
+
+    def __init__(self, base_dir: Optional[str] = None):
+        """Initialize ScitexPaths.
+
+        Parameters
+        ----------
+        base_dir : str, optional
+            Explicit base directory. If None, uses SCITEX_DIR env var
+            or falls back to ~/.scitex.
+        """
+        self._base_dir = get_scitex_dir(base_dir)
+
+    @property
+    def base(self) -> Path:
+        """Base SciTeX directory ($SCITEX_DIR or ~/.scitex)."""
+        return self._base_dir
+
+    # ========== Core directories ==========
+
+    @property
+    def logs(self) -> Path:
+        """Log files directory."""
+        return self._base_dir / "logs"
+
+    @property
+    def cache(self) -> Path:
+        """General cache directory."""
+        return self._base_dir / "cache"
+
+    @property
+    def capture(self) -> Path:
+        """Screen capture directory."""
+        return self._base_dir / "capture"
+
+    @property
+    def screenshots(self) -> Path:
+        """General screenshots directory."""
+        return self._base_dir / "screenshots"
+
+    @property
+    def rng(self) -> Path:
+        """Random number generator state directory."""
+        return self._base_dir / "rng"
+
+    # ========== Browser directories ==========
+
+    @property
+    def browser(self) -> Path:
+        """Browser module base directory."""
+        return self._base_dir / "browser"
+
+    @property
+    def browser_screenshots(self) -> Path:
+        """Browser debugging screenshots."""
+        return self.browser / "screenshots"
+
+    @property
+    def browser_sessions(self) -> Path:
+        """Shared browser sessions."""
+        return self.browser / "sessions"
+
+    @property
+    def browser_persistent(self) -> Path:
+        """Persistent browser profiles."""
+        return self.browser / "persistent"
+
+    @property
+    def test_monitor(self) -> Path:
+        """Test monitoring screenshots directory."""
+        return self._base_dir / "test_monitor"
+
+    # ========== Cache directories ==========
+
+    @property
+    def function_cache(self) -> Path:
+        """Function cache (joblib memory)."""
+        return self.cache / "functions"
+
+    @property
+    def impact_factor_cache(self) -> Path:
+        """Impact factor data cache."""
+        return self._base_dir / "impact_factor_cache"
+
+    @property
+    def openathens_cache(self) -> Path:
+        """OpenAthens authentication cache."""
+        return self._base_dir / "openathens_cache"
+
+    # ========== Scholar directories ==========
+
+    @property
+    def scholar(self) -> Path:
+        """Scholar module base directory."""
+        return self._base_dir / "scholar"
+
+    @property
+    def scholar_cache(self) -> Path:
+        """Scholar-specific cache directory."""
+        return self.scholar / "cache"
+
+    @property
+    def scholar_library(self) -> Path:
+        """Scholar PDF library directory."""
+        return self.scholar / "library"
+
+    # ========== Writer directories ==========
+
+    @property
+    def writer(self) -> Path:
+        """Writer module directory."""
+        return self._base_dir / "writer"
+
+    # ========== Resolve method (recommended for modules) ==========
+
+    def resolve(
+        self,
+        path_name: str,
+        direct_val: Optional[Union[str, Path]] = None,
+    ) -> Path:
+        """Resolve a path with priority: direct_val → default from SCITEX_DIR.
+
+        This is the recommended method for modules that accept optional path
+        parameters. It follows the same pattern as PriorityConfig.resolve().
+
+        Parameters
+        ----------
+        path_name : str
+            Name of the path property (e.g., "cache", "logs", "scholar_library")
+        direct_val : str or Path, optional
+            Direct value (highest precedence). If None, uses default.
+
+        Returns
+        -------
+        Path
+            Resolved path
+
+        Examples
+        --------
+        >>> paths = ScitexPaths()
+        >>> # User didn't provide path -> use default
+        >>> cache_dir = paths.resolve("cache", None)
+        >>> # User provided custom path -> use it
+        >>> cache_dir = paths.resolve("cache", "/custom/cache")
+
+        Usage in modules:
+        >>> class MyModule:
+        ...     def __init__(self, cache_dir=None):
+        ...         self.cache_dir = get_paths().resolve("cache", cache_dir)
+        """
+        if direct_val is not None:
+            return Path(direct_val).expanduser()
+
+        # Get the default path from property
+        if hasattr(self, path_name):
+            return getattr(self, path_name)
+
+        raise ValueError(
+            f"Unknown path name: {path_name}. Available: {list(self.list_all().keys())}"
+        )
+
+    # ========== Utility methods ==========
+
+    def ensure_dir(self, path: Path) -> Path:
+        """Ensure directory exists, creating if necessary.
+
+        Parameters
+        ----------
+        path : Path
+            Directory path to ensure exists.
+
+        Returns
+        -------
+        Path
+            The same path, guaranteed to exist.
+        """
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def ensure_all(self) -> None:
+        """Create all standard directories."""
+        dirs = [
+            self.logs,
+            self.cache,
+            self.function_cache,
+            self.capture,
+            self.screenshots,
+            self.rng,
+            self.browser,
+            self.browser_screenshots,
+            self.browser_sessions,
+            self.browser_persistent,
+            self.test_monitor,
+            self.impact_factor_cache,
+            self.openathens_cache,
+            self.scholar,
+            self.scholar_cache,
+            self.scholar_library,
+            self.writer,
+        ]
+        for d in dirs:
+            d.mkdir(parents=True, exist_ok=True)
+
+    def list_all(self) -> dict:
+        """List all configured paths.
+
+        Returns
+        -------
+        dict
+            Dictionary of path names to Path objects.
+        """
+        return {
+            "base": self.base,
+            "logs": self.logs,
+            "cache": self.cache,
+            "function_cache": self.function_cache,
+            "capture": self.capture,
+            "screenshots": self.screenshots,
+            "rng": self.rng,
+            "browser": self.browser,
+            "browser_screenshots": self.browser_screenshots,
+            "browser_sessions": self.browser_sessions,
+            "browser_persistent": self.browser_persistent,
+            "test_monitor": self.test_monitor,
+            "impact_factor_cache": self.impact_factor_cache,
+            "openathens_cache": self.openathens_cache,
+            "scholar": self.scholar,
+            "scholar_cache": self.scholar_cache,
+            "scholar_library": self.scholar_library,
+            "writer": self.writer,
+        }
+
+    def __repr__(self) -> str:
+        return f"ScitexPaths(base='{self._base_dir}')"
+
+
+# Singleton instance for convenience (uses default SCITEX_DIR)
+_default_paths: Optional[ScitexPaths] = None
+
+
+def get_paths(base_dir: Optional[str] = None) -> ScitexPaths:
+    """Get ScitexPaths instance.
+
+    Parameters
+    ----------
+    base_dir : str, optional
+        Explicit base directory. If None, returns cached default instance.
+
+    Returns
+    -------
+    ScitexPaths
+        Path manager instance.
+    """
+    global _default_paths
+
+    if base_dir is not None:
+        return ScitexPaths(base_dir)
+
+    if _default_paths is None:
+        _default_paths = ScitexPaths()
+
+    return _default_paths
+
+
+# EOF