#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Timestamp: "2026-05-26 (ywatanabe)"
# File: src/scitex_session/_decorator/_decorator.py
"""@stx.session decorator factory.
Public entry point that wraps a script's ``main``-style function with
CLI parsing + session lifecycle management. Execution itself lives in
:mod:`scitex_session._decorator._run`.
"""
from __future__ import annotations
import functools
from typing import Callable
from ._run import _run_with_session
[docs]
def session(
func: Callable = None,
*,
verbose: bool = False,
agg: bool = True,
notify: bool = False,
sdir_suffix: str = None,
archive_format: str = None,
**session_kwargs,
) -> Callable:
"""Decorator to wrap a function in a scitex session.
Automatically handles:
- CLI argument parsing from the function signature
- Session initialization (logging, output directories)
- Execution
- Cleanup
- Error handling
This decorator is designed for script entry points. The decorated
function should be called without arguments from
``if __name__ == '__main__':`` to trigger CLI parsing and session
management.
Parameters
----------
func : callable, optional
Function to wrap (set automatically by the decorator).
verbose : bool, default False
Enable verbose logging.
agg : bool, default True
Use matplotlib's Agg backend (non-interactive).
notify : bool, default False
Send notification on completion.
sdir_suffix : str, optional
Suffix for the output directory name (defaults to function name).
archive_format : str, optional
If set (e.g. ``"tar.gz"``), replace FINISHED_SUCCESS/<session>/
with a single archive file (1 inode vs 7).
**session_kwargs
Additional session configuration parameters forwarded to
``scitex_session.start`` / ``scitex_session.close``.
Returns
-------
callable
The wrapped function; calling it with no arguments triggers
CLI parsing + session management. Calling it with arguments
bypasses session management entirely and invokes the function
directly (useful for in-process tests).
Examples
--------
Bare decorator (auto CLI from signature):
.. code-block:: python
@stx.session
def analyze(data_path: str, threshold: float = 0.5):
'''Analyze data file.'''
data = stx.io.load(data_path)
result = process(data, threshold)
stx.io.save(result, "output.csv")
return 0
if __name__ == '__main__':
analyze() # CLI mode with session management
# CLI: python script.py --data-path data.csv --threshold 0.7
Decorator with options:
.. code-block:: python
@stx.session(verbose=True, notify=True)
def train_model(model_name: str, epochs: int = 10):
'''Train ML model.'''
# Available as globals: CONFIG, plt, COLORS, rngg, logger.
logger.info(f"Session ID: {CONFIG['ID']}")
logger.info(f"Output directory: {CONFIG['SDIR_RUN']}")
# ... training code ...
return 0
if __name__ == '__main__':
train_model()
Notes
-----
- Function name can be anything (not just ``main``).
- Calling with arguments bypasses session management:
``analyze('/path', 0.5)``.
- Only one session-managed function per script.
- Do NOT call multiple ``@session`` decorated functions from one
script.
- Do NOT nest session-decorated function calls without arguments.
**Injected global variables**
When called without arguments (CLI mode), the decorator injects
these into the wrapped function's module globals:
- ``CONFIG`` (dict): Session configuration with ID, SDIR, paths, etc.
- ``plt`` (module): ``matplotlib.pyplot`` configured for the session.
- ``COLORS`` (CustomColors): Color palette for consistent plotting.
- ``rngg`` (RandomStateManager): Reproducibility manager; creates
named generators via ``rngg("name")``.
"""
def decorator(func: Callable) -> Callable:
@functools.wraps(func)
def wrapper(*args, **kwargs):
# If called with arguments (not CLI), run directly.
if args or kwargs:
return func(*args, **kwargs)
# Otherwise, parse CLI and run with session management.
return _run_with_session(
func,
verbose=verbose,
agg=agg,
notify=notify,
sdir_suffix=sdir_suffix,
archive_format=archive_format,
**session_kwargs,
)
wrapper._func = func
wrapper._is_session_wrapped = True
return wrapper
# Handle @stx.session vs @stx.session()
if func is None:
# Called with arguments: @stx.session(verbose=True)
return decorator
# Called without arguments: @stx.session
return decorator(func)
# EOF