scitex 2.14.0__py3-none-any.whl → 2.15.3__py3-none-any.whl

scitex/scholar/storage/_mixins/_symlink_handlers.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/scholar/storage/_mixins/_symlink_handlers.py
+
+"""
+Symlink handling mixin for LibraryManager.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SymlinkHandlersMixin:
+    """Mixin providing symlink handling methods."""
+
+    def _generate_readable_name(
+        self,
+        comprehensive_metadata: Dict,
+        master_storage_path: Path,
+        authors: Optional[List[str]] = None,
+        year: Optional[int] = None,
+        journal: Optional[str] = None,
+    ) -> str:
+        """Generate readable symlink name from metadata."""
+        from scitex.dict import DotDict
+
+        # Extract author
+        first_author = "Unknown"
+        if authors and len(authors) > 0:
+            author_parts = authors[0].split()
+            first_author = (
+                author_parts[-1] if len(author_parts) > 1 else author_parts[0]
+            )
+            first_author = "".join(c for c in first_author if c.isalnum() or c == "-")[
+                :20
+            ]
+
+        # Format year
+        if isinstance(year, DotDict):
+            year = None
+
+        if isinstance(year, str) and year.isdigit():
+            year = int(year)
+
+        year_str = f"{year:04d}" if isinstance(year, int) else "0000"
+
+        # Clean journal name
+        journal_clean = "Unknown"
+        if journal:
+            journal_clean = self.config.path_manager._sanitize_filename(journal)[:30]
+            if not journal_clean:
+                journal_clean = "Unknown"
+
+        # Get citation count and impact factor
+        cc, if_val = self._extract_cc_and_if(comprehensive_metadata)
+
+        # Count PDFs
+        pdf_files = list(master_storage_path.glob("*.pdf"))
+        n_pdfs = len(pdf_files)
+
+        readable_name = f"PDF-{n_pdfs:02d}_CC-{cc:06d}_IF-{int(if_val):03d}_{year_str}_{first_author}_{journal_clean}"
+        return readable_name
+
+    def _extract_cc_and_if(self, comprehensive_metadata: Dict) -> tuple:
+        """Extract citation count and impact factor from metadata."""
+        if "metadata" in comprehensive_metadata:
+            metadata_section = comprehensive_metadata.get("metadata", {})
+            cc_val = metadata_section.get("citation_count", {})
+            if isinstance(cc_val, dict):
+                cc = cc_val.get("total", 0) or 0
+            else:
+                cc = cc_val or 0
+
+            publication_section = metadata_section.get("publication", {})
+            if_val = publication_section.get("impact_factor", 0.0) or 0.0
+        else:
+            cc_val = comprehensive_metadata.get("citation_count", 0)
+            if isinstance(cc_val, dict):
+                cc = cc_val.get("total", 0) or 0
+            else:
+                cc = cc_val or 0
+
+            if_val = (
+                comprehensive_metadata.get("journal_impact_factor")
+                or comprehensive_metadata.get("impact_factor")
+                or comprehensive_metadata.get("publication", {}).get("impact_factor")
+            )
+            if isinstance(if_val, dict):
+                if_val = if_val.get("value", 0.0) or 0.0
+            else:
+                if_val = if_val or 0.0
+
+        return cc, if_val
+
+    def update_symlink(
+        self,
+        master_storage_path: Path,
+        project: str,
+        metadata: Optional[Dict] = None,
+    ) -> Optional[Path]:
+        """Update project symlink to reflect current paper status."""
+        try:
+            if metadata is None:
+                metadata_file = master_storage_path / "metadata.json"
+                if metadata_file.exists():
+                    with open(metadata_file) as f:
+                        metadata = json.load(f)
+                else:
+                    logger.warning(f"No metadata found for {master_storage_path.name}")
+                    return None
+
+            # Extract metadata from nested structure if needed
+            if "metadata" in metadata:
+                meta_section = metadata.get("metadata", {})
+                basic_section = meta_section.get("basic", {})
+                pub_section = meta_section.get("publication", {})
+                authors = basic_section.get("authors")
+                year = basic_section.get("year")
+                journal = pub_section.get("journal")
+            else:
+                authors = metadata.get("authors")
+                year = metadata.get("year")
+                journal = metadata.get("journal")
+
+            readable_name = self._generate_readable_name(
+                comprehensive_metadata=metadata,
+                master_storage_path=master_storage_path,
+                authors=authors,
+                year=year,
+                journal=journal,
+            )
+
+            return self._create_project_symlink(
+                master_storage_path=master_storage_path,
+                project=project,
+                readable_name=readable_name,
+            )
+        except Exception as exc_:
+            logger.error(
+                f"Failed to update symlink for {master_storage_path.name}: {exc_}"
+            )
+            return None
+
+    def _create_project_symlink(
+        self, master_storage_path: Path, project: str, readable_name: str
+    ) -> Optional[Path]:
+        """Create symlink in project directory pointing to master storage."""
+        try:
+            project_dir = self.config.path_manager.get_library_project_dir(project)
+            symlink_path = project_dir / readable_name
+            master_id = master_storage_path.name
+
+            # Remove old symlinks pointing to the same master entry
+            for existing_link in project_dir.iterdir():
+                if not existing_link.is_symlink():
+                    continue
+
+                try:
+                    target = existing_link.resolve()
+                    if target.name == master_id and existing_link.name != readable_name:
+                        logger.debug(f"Removing old symlink: {existing_link.name}")
+                        existing_link.unlink()
+                except Exception as e:
+                    logger.debug(f"Skipping broken symlink {existing_link.name}: {e}")
+                    continue
+
+            # Create new symlink
+            if not symlink_path.exists():
+                relative_path = os.path.relpath(master_storage_path, project_dir)
+                symlink_path.symlink_to(relative_path)
+                logger.success(
+                    f"Created project symlink: {symlink_path} -> {relative_path}"
+                )
+            else:
+                logger.debug(f"Project symlink already exists: {symlink_path}")
+
+            return symlink_path
+
+        except Exception as exc_:
+            logger.warning(f"Failed to create project symlink: {exc_}")
+            return None
+
+    def _ensure_project_symlink(
+        self,
+        title: str,
+        year: Optional[int] = None,
+        authors: Optional[List[str]] = None,
+        paper_id: str = None,
+        master_storage_path: Path = None,
+    ) -> None:
+        """Ensure project symlink exists for paper in master library."""
+        try:
+            if not paper_id or not master_storage_path:
+                return
+
+            project_lib_path = (
+                self.config.path_manager.get_scholar_library_path() / self.project
+            )
+            project_lib_path.mkdir(parents=True, exist_ok=True)
+
+            paper_info = {"title": title, "year": year, "authors": authors or []}
+            readable_paths = self._call_path_manager_get_storage_paths(
+                paper_info=paper_info, collection_name=self.project
+            )
+            readable_name = readable_paths["readable_name"]
+            symlink_path = project_lib_path / readable_name
+            relative_path = f"../MASTER/{paper_id}"
+
+            if not symlink_path.exists():
+                symlink_path.symlink_to(relative_path)
+                logger.info(
+                    f"Created project symlink: {readable_name} -> {relative_path}"
+                )
+        except Exception as exc_:
+            logger.debug(f"Error creating project symlink: {exc_}")
+
+
+# EOF

scitex/security/README.md

@@ -14,7 +14,7 @@ Reusable security utilities for the SciTeX ecosystem. Works everywhere: local, c
 The module is part of the `scitex` package (editable install):
 
 ```bash
-cd ~/proj/scitex-code
+cd ~/proj/scitex-python
 pip install -e .
 ```
 
@@ -162,7 +162,7 @@ Total open alerts: 2
 ```yaml
 - name: Check Security
   run: |
-    pip install -e ~/proj/scitex-code
+    pip install -e ~/proj/scitex-python
     python -m scitex.security.cli check --save
 ```
 
@@ -245,7 +245,7 @@ Get path to latest alerts file.
 ## Testing
 
 ```bash
-cd ~/proj/scitex-code
+cd ~/proj/scitex-python
 pytest tests/test_security.py
 ```
 

scitex/session/README.md

@@ -1,7 +1,7 @@
 <!-- ---
 !-- Timestamp: 2025-11-18 10:14:48
 !-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/session/README.md
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/session/README.md
 !-- --- -->
 
 # scitex.session

scitex/session/__init__.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 # Timestamp: "2025-08-21 20:36:45 (ywatanabe)"
 # File: /home/ywatanabe/proj/SciTeX-Code/src/scitex/session/__init__.py
 # ----------------------------------------
 from __future__ import annotations
+
 import os
 
 __FILE__ = __file__
@@ -20,27 +20,46 @@ Usage:
     import sys
     import matplotlib.pyplot as plt
     from scitex import session
-    
+
     # Start a session
     CONFIG, sys.stdout, sys.stderr, plt, COLORS, rng = session.start(sys, plt)
-    
+
     # Your experiment code here
-    
-    # Close the session  
+
+    # Close the session
     session.close(CONFIG)
 
     # Session manager for advanced use cases
     manager = session.SessionManager()
     active_sessions = manager.get_active_sessions()
+
+    # Using INJECTED sentinel for decorator parameters
+    @stx.session
+    def main(CONFIG=stx.session.INJECTED, plt=stx.session.INJECTED):
+        ...
 """
 
+
+# Sentinel object for decorator-injected parameters
+class _InjectedSentinel:
+    """Sentinel value indicating a parameter will be injected by a decorator."""
+
+    def __repr__(self):
+        return "<INJECTED>"
+
+
+INJECTED = _InjectedSentinel()
+
+
 # Import session management functionality
+from ._decorator import run, session
+from ._lifecycle import close, running2finished, start
 from ._manager import SessionManager
-from ._lifecycle import start, close, running2finished
-from ._decorator import session, run
 
 # Export public API
 __all__ = [
+    # Sentinel for injected parameters
+    "INJECTED",
     # Session lifecycle (main functions)
     "start",
     "close",

scitex/session/_decorator.py

@@ -21,7 +21,7 @@ import sys as sys_module
 
 from ._lifecycle import start, close
 from scitex.logging import getLogger
-from scitex import INJECTED
+from . import INJECTED  # Use local INJECTED from session module
 
 # Internal logger for the decorator itself
 _decorator_logger = getLogger(__name__)

scitex/sh/README.md

@@ -1,7 +1,7 @@
 <!-- ---
 !-- Timestamp: 2025-10-29 07:23:56
 !-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/sh/README.md
+!-- File: /home/ywatanabe/proj/scitex-python/src/scitex/sh/README.md
 !-- --- -->
 
 # scitex.sh - Shell Command Execution Module

scitex/sh/__init__.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 from __future__ import annotations
+
 import os
 
 __FILE__ = __file__
@@ -8,9 +8,9 @@ __DIR__ = os.path.dirname(__FILE__)
 
 from typing import Union
 
-from ._types import CommandInput, ReturnFormat, ShellResult
-from ._security import quote, validate_command
 from ._execute import execute
+from ._security import quote, validate_command
+from ._types import CommandInput, ReturnFormat, ShellResult
 
 
 def sh(
@@ -88,6 +88,9 @@ def sh_run(command: CommandInput, verbose: bool = True) -> ShellResult:
     return execute(command, verbose=verbose)
 
 
-__all__ = ["sh", "sh_run", "quote"]
+# Legacy functions moved from gen module
+from ._shell_legacy import run_shellcommand, run_shellscript
+
+__all__ = ["sh", "sh_run", "quote", "run_shellcommand", "run_shellscript"]
 
 # EOF

scitex/social/__init__.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-22
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/social/__init__.py
+
+"""SciTeX Social - Unified social media management.
+
+This module provides a thin wrapper around socialia, the core social media
+integration package. It uses scitex branding and environment variable prefixes.
+
+Features
+--------
+- Twitter/X posting and analytics
+- LinkedIn posting
+- Reddit posting
+- YouTube analytics
+- Google Analytics integration
+
+Environment Variables
+---------------------
+Credentials use SCITEX_SOCIAL_ prefix (falls back to SOCIALIA_):
+- SCITEX_SOCIAL_X_CONSUMER_KEY, SCITEX_SOCIAL_X_CONSUMER_KEY_SECRET
+- SCITEX_SOCIAL_X_ACCESS_TOKEN, SCITEX_SOCIAL_X_ACCESS_TOKEN_SECRET
+- SCITEX_SOCIAL_X_BEARER_TOKEN
+- SCITEX_SOCIAL_LINKEDIN_CLIENT_ID, SCITEX_SOCIAL_LINKEDIN_CLIENT_SECRET
+- SCITEX_SOCIAL_LINKEDIN_ACCESS_TOKEN
+- SCITEX_SOCIAL_REDDIT_CLIENT_ID, SCITEX_SOCIAL_REDDIT_CLIENT_SECRET
+- SCITEX_SOCIAL_YOUTUBE_API_KEY
+- SCITEX_SOCIAL_GOOGLE_ANALYTICS_PROPERTY_ID
+
+Usage
+-----
+    import scitex as stx
+
+    # Twitter/X
+    x = stx.social.Twitter()
+    x.post("Hello from SciTeX!")
+
+    # LinkedIn
+    linkedin = stx.social.LinkedIn()
+    linkedin.post("Research update", visibility="public")
+
+    # YouTube analytics
+    yt = stx.social.YouTube()
+    stats = yt.get_channel_stats()
+
+    # Google Analytics
+    ga = stx.social.GoogleAnalytics()
+    report = ga.get_report(start_date="7daysAgo")
+
+See Also
+--------
+- socialia: https://github.com/ywatanabe1989/socialia
+- scitex: https://scitex.ai
+"""
+
+import os as _os
+
+# Set branding BEFORE importing socialia
+_os.environ.setdefault("SOCIALIA_BRAND", "scitex.social")
+_os.environ.setdefault("SOCIALIA_ENV_PREFIX", "SCITEX_SOCIAL")
+
+# Check socialia availability
+try:
+    import socialia as _socialia
+
+    # Re-export platform clients
+    from socialia import (
+        # Content strategies for MCP
+        PLATFORM_STRATEGIES,
+        # Base class
+        BasePoster,
+        GoogleAnalytics,
+        LinkedIn,
+        LinkedInPoster,
+        Reddit,
+        RedditPoster,
+        # Platform clients (preferred names)
+        Twitter,
+        # Backward compatibility aliases
+        TwitterPoster,
+        YouTube,
+        YouTubePoster,
+    )
+    from socialia import __version__ as _socialia_version
+
+    SOCIALIA_AVAILABLE = True
+    __socialia_version__ = _socialia_version
+
+except ImportError:
+    SOCIALIA_AVAILABLE = False
+    __socialia_version__ = None
+
+    # Provide helpful error on access
+    class _SocialiaNotAvailable:
+        """Placeholder when socialia is not installed."""
+
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "socialia is required for scitex.social. "
+                "Install with: pip install socialia"
+            )
+
+        def __getattr__(self, name):
+            raise ImportError(
+                "socialia is required for scitex.social. "
+                "Install with: pip install socialia"
+            )
+
+    BasePoster = _SocialiaNotAvailable
+    Twitter = _SocialiaNotAvailable
+    LinkedIn = _SocialiaNotAvailable
+    Reddit = _SocialiaNotAvailable
+    YouTube = _SocialiaNotAvailable
+    GoogleAnalytics = _SocialiaNotAvailable
+    TwitterPoster = _SocialiaNotAvailable
+    LinkedInPoster = _SocialiaNotAvailable
+    RedditPoster = _SocialiaNotAvailable
+    YouTubePoster = _SocialiaNotAvailable
+    PLATFORM_STRATEGIES = ""
+
+
+def has_socialia() -> bool:
+    """Check if socialia is available.
+
+    Returns
+    -------
+    bool
+        True if socialia is installed and importable.
+    """
+    return SOCIALIA_AVAILABLE
+
+
+__all__ = [
+    # Availability check
+    "SOCIALIA_AVAILABLE",
+    "has_socialia",
+    "__socialia_version__",
+    # Base class
+    "BasePoster",
+    # Platform clients (preferred names)
+    "Twitter",
+    "LinkedIn",
+    "Reddit",
+    "YouTube",
+    "GoogleAnalytics",
+    # Backward compatibility aliases
+    "TwitterPoster",
+    "LinkedInPoster",
+    "RedditPoster",
+    "YouTubePoster",
+    # Content strategies
+    "PLATFORM_STRATEGIES",
+]
+
+# EOF

scitex/social/docs/EXTERNAL_PACKAGE_BRANDING.md

@@ -0,0 +1,149 @@
+# External Package Branding Guide
+
+When scitex wraps external packages (like `figrecipe` for `scitex.plt` or `crossref-local` for `scitex.scholar`), those packages should support configurable branding so documentation and error messages show the scitex namespace.
+
+## When to Use Branding
+
+- **Use branding**: External packages that scitex wraps (figrecipe, crossref-local, etc.)
+- **Don't use branding**: Internal scitex modules (scitex.audio, scitex.stats, etc.) - just hardcode `SCITEX_*` prefix
+
+## Pattern Overview
+
+The external package provides a `_branding.py` module that:
+1. Reads brand name from environment variable
+2. Derives environment variable prefix from brand name
+3. Provides helper functions for rebranding text/docstrings
+
+## Implementation Template
+
+```python
+# external_package/_branding.py
+
+import os
+import re
+from typing import Optional
+
+# Environment variables for branding
+# Parent package sets these before importing
+BRAND_NAME = os.environ.get("{PACKAGE}_BRAND", "{package}")
+BRAND_ALIAS = os.environ.get("{PACKAGE}_ALIAS", "{alias}")
+
+# Original values for replacement
+_ORIGINAL_NAME = "{package}"
+_ORIGINAL_ALIAS = "{alias}"
+
+
+def _brand_to_env_prefix(brand: str) -> str:
+    """Convert brand name to environment variable prefix.
+
+    Examples:
+        "figrecipe" -> "FIGRECIPE"
+        "scitex.plt" -> "SCITEX_PLT"
+        "crossref-local" -> "CROSSREF_LOCAL"
+    """
+    return brand.upper().replace(".", "_").replace("-", "_")
+
+
+# Environment variable prefix based on brand
+ENV_PREFIX = _brand_to_env_prefix(BRAND_NAME)
+
+
+def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get environment variable with brand-aware prefix.
+
+    Checks {ENV_PREFIX}_{key} first, then falls back to original prefix.
+    """
+    value = os.environ.get(f"{ENV_PREFIX}_{key}")
+    if value is not None:
+        return value
+
+    # Fall back to original prefix if different
+    original_prefix = _brand_to_env_prefix(_ORIGINAL_NAME)
+    if ENV_PREFIX != original_prefix:
+        value = os.environ.get(f"{original_prefix}_{key}")
+        if value is not None:
+            return value
+
+    return default
+
+
+def rebrand_text(text: Optional[str]) -> Optional[str]:
+    """Apply branding to a text string (docstrings, error messages)."""
+    if text is None:
+        return None
+
+    if BRAND_NAME == _ORIGINAL_NAME and BRAND_ALIAS == _ORIGINAL_ALIAS:
+        return text
+
+    result = text
+
+    # Replace import statements
+    result = re.sub(
+        rf"import\s+{_ORIGINAL_NAME}\s+as\s+{_ORIGINAL_ALIAS}",
+        f"import {BRAND_NAME} as {BRAND_ALIAS}",
+        result,
+    )
+
+    # Replace "from package" statements
+    result = re.sub(
+        rf"from\s+{_ORIGINAL_NAME}(\s+import|\s*\.)",
+        lambda m: f"from {BRAND_NAME}{m.group(1)}",
+        result,
+    )
+
+    return result
+
+
+def get_mcp_server_name() -> str:
+    """Get the MCP server name based on branding."""
+    return BRAND_NAME.replace(".", "-")
+```
+
+## Usage in Parent Package (scitex)
+
+```python
+# scitex/plt/__init__.py
+import os
+
+# Set branding BEFORE importing the external package
+os.environ["FIGRECIPE_BRAND"] = "scitex.plt"
+os.environ["FIGRECIPE_ALIAS"] = "plt"
+
+# Now import - docstrings will show scitex.plt instead of figrecipe
+from figrecipe import *
+```
+
+## Port Scheme
+
+SciTeX uses port scheme 3129X (TEX → te-ku-su → 2-9-3 in Japanese):
+
+| Port  | Service          |
+|-------|------------------|
+| 31290 | scitex-cloud     |
+| 31291 | crossref-local   |
+| 31292 | openalex         |
+| 31293 | scitex-audio     |
+
+## Environment Variable Pattern
+
+External packages should use `{ENV_PREFIX}_{SETTING}`:
+
+```
+SCITEX_PLT_MODE=local
+CROSSREF_LOCAL_API_URL=http://localhost:8333
+SCITEX_AUDIO_RELAY_URL=http://localhost:31293
+```
+
+## Example: crossref-local
+
+See GitHub Issue: https://github.com/ywatanabe1989/crossref-local/issues/11
+
+The crossref-local package should implement:
+- `CROSSREF_LOCAL_BRAND` / `CROSSREF_LOCAL_ALIAS` env vars
+- Dynamic `ENV_PREFIX` derived from brand name
+- When used via scitex.scholar, shows `scitex.scholar` in docs
+
+## References
+
+- figrecipe/_branding.py - Reference implementation
+- scitex/audio/_branding.py - Simple internal module (no rebranding needed)