scitex.session API Reference

scitex-session — the @scitex_session.session decorator (standalone).

THE one public entry point is the decorator:

import scitex_session

@scitex_session.session
def main(CONFIG=scitex_session.INJECTED, plt=scitex_session.INJECTED):
    ...

if __name__ == "__main__":
    main()

It parses CLI args from main’s signature, loads config/*.yaml, configures matplotlib + logging, seeds a reproducible RNG, runs the function, writes outputs under script_out/<status>/<session_id>/, and records clew lineage. That is the supported, recommended surface.

The low-level building blocks the decorator orchestrates — start() (start(sys, plt, ...)) and run() (the imperative, non-decorator runner) — are INTERNAL. They are easy to misuse: @scitex_session.start binds main to the sys parameter rather than decorating it, and run(name=...) forwards unknown kwargs into start(). They are therefore not part of the default public surface (absent from __all__ and dir(scitex_session)). Power users who genuinely need them should reach for the underscore aliases scitex_session._start / scitex_session._run. The bare scitex_session.start / scitex_session.run names remain importable for backward compatibility but emit a DeprecationWarning on access.

scitex.session.session(func=None, *, verbose=False, agg=True, notify=False, sdir_suffix=None, archive_format=None, **session_kwargs)[source]

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:

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).

Return type:

callable

Examples

Bare decorator (auto CLI from signature):

@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:

@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.

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").

scitex.session.close(CONFIG, message=':)', notify=False, verbose=True, exit_status=None, archive_format=None)[source]

Close experiment session and finalize logging.

Parameters:

CONFIG (DotDict) – Configuration dictionary from start()
message (str, default=':)') – Completion message
notify (bool, default=False) – Whether to send notification
verbose (bool, default=True) – Whether to print verbose output
exit_status (int, optional) – Exit status code (0=success, 1=error, None=finished)
archive_format (str, optional) – If set (e.g. “tar.gz”), replace the FINISHED dest dir with a single archive file. None (default) preserves the original copytree-only behavior bit-for-bit.

scitex.session.running2finished(CONFIG, exit_status=None, remove_src_dir=True, max_wait=60, archive_format=None)[source]

Move session from RUNNING to FINISHED directory.

Parameters:

CONFIG (dict) – Session configuration dictionary
exit_status (int, optional) – Exit status code (0=success, 1=error, None=finished)
remove_src_dir (bool, default=True) – Whether to remove source directory after copy
max_wait (int, default=60) – Maximum seconds to wait for copy operation
archive_format (str, optional) – If set (e.g. “tar.gz”), replace the FINISHED dest dir with a single archive file (1 inode instead of N). None (default) preserves the original copytree-only behavior bit-for-bit.

Returns:

Updated configuration with new SDIR

Return type:

dict

class scitex.session.SessionManager[source]

Bases: object

Manages experiment sessions with tracking and lifecycle management.

create_session(session_id, config, script_path=None)[source]

Register a new session.

Parameters:

session_id (str) – Unique identifier for the session
config (Dict[str, Any]) – Session configuration dictionary
script_path (str, optional) – Path to the script being run

Return type:

None

close_session(session_id, status='success', exit_code=0)[source]

Mark a session as closed.

Parameters:

session_id (str) – Unique identifier for the session to close
status (str, optional) – Final status (success, failed, error)
exit_code (int, optional) – Exit code of the session

Return type:

None

get_active_sessions()[source]

Get all active sessions.

Returns:: Dictionary of active session information
Return type:: Dict[str, Any]

get_session(session_id)[source]

Get specific session information.

Parameters:: session_id (str) – Session ID to retrieve
Returns:: Session information dictionary
Return type:: Dict[str, Any]

list_sessions()[source]

Get all sessions (active and closed).

Returns:: Dictionary of all session information
Return type:: Dict[str, Any]

scitex.session.archive_session_dir(src_dir, format='tar.gz', remove_src=True, compresslevel=1)[source]

Compress a single session dir into a single archive file.

Writes to a temp path adjacent to the destination, then atomically renames into place. Only after the archive exists and passes a size sanity check do we delete the source (when remove_src=True). On any error the source is left untouched.

Returns:: Absolute path to the final archive file.
Return type:: Path

scitex.session.restore_session_archive(archive_path, dest_dir=None, remove_archive=False)[source]

Extract a session archive back into a session directory.

Extraction is done into a temp dir adjacent to the final destination and atomically renamed into place. If remove_archive=True the archive file is deleted only after a successful rename.

Returns:: Absolute path to the restored directory.
Return type:: Path

scitex.session.archive_existing(root, older_than_days=None, format='tar.gz', pattern=None, dry_run=True, max_dirs=None, track_bytes=False, use_fd=True)[source]

Bulk compress every session-shaped child of root.

Parameters:

track_bytes (bool, default False) – When True, run a per-candidate dir_size() (os.walk + getsize per file) so that bytes_in / bytes_out in the returned summary are populated. Off by default because the size accounting adds a measurable per-session overhead on top of the mandatory tar IO (observed on neurovista 2026-05-25: 80,408 sessions / 47 min wall-clock — the byte stats are a meaningful contributor).
use_fd (bool, default True) – Forwarded to iter_session_candidates. When True and fd is installed, candidate enumeration uses the parallel subprocess path; otherwise the Python iterdir+stat path.

Returns:

Summary {scanned, candidates, archived, skipped, failed, bytes_in, bytes_out}. bytes_in and bytes_out stay at 0 when track_bytes is False.

Return type:

dict

scitex.session.restore_existing(root, pattern='*.tar.gz', dest_root=None, remove_archive=False, dry_run=True, max_files=None, track_bytes=False)[source]

Bulk restore every archive matching pattern directly under root.

Returns:: Summary {scanned, candidates, restored, skipped, failed}.
Return type:: dict

scitex.session.register_session_start_hook(fn)[source]

Register fn to be called at session start.

fn is invoked as fn(session_id, script_path, metadata). Registration is idempotent (registering the same callable twice is a no-op). Returns fn so it can also be used as a decorator.

Return type:: Callable[..., Any]

scitex.session.register_session_close_hook(fn)[source]

Register fn to be called at session close.

fn is invoked as fn(status, exit_code). Registration is idempotent. Returns fn so it can also be used as a decorator.

Return type:: Callable[..., Any]

scitex.session.unregister_session_start_hook(fn)[source]

Remove a previously registered start hook (no-op if absent).

Return type:: None

scitex.session.unregister_session_close_hook(fn)[source]

Remove a previously registered close hook (no-op if absent).

Return type:: None