scitex.config API Reference

scitex-config — configuration helpers (YAML + dotenv) — standalone.

Two distinct API surfaces:

Public (top-level scitex_config.*) — convention-free generic primitives usable by any Python project:

PriorityConfig — direct → config_dict → env → default cascade
ScitexConfig, get_config, load_yaml — YAML-based config
ScitexPaths, get_paths — centralized path manager
load_dotenv, get_scitex_dir — utilities
parse_src_file, load_env_from_path, load_scitex_env — bash-style .src/.env parsing (canonical line/value parser; load_dotenv delegates)

SciTeX-ecosystem internals (scitex_config._ecosystem.*) — helpers that embed SciTeX conventions (pkg-short naming, project-scope walk to .git/, _skills/<pkg>/ layout, SCITEX_<MODULE>_* env prefix). For scitex-* package authors only; not a stable public API:

from scitex_config._ecosystem import local_state, env_registry

Priority Order (same for PriorityConfig and ScitexConfig):

direct → config (YAML/dict) → env → default

Usage:

from scitex_config import ScitexConfig, ScitexPaths, get_config, get_paths

# 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

# Use resolve() pattern in modules cache_dir = paths.resolve(“cache”, user_provided_path)

class scitex.config.ScitexConfig(config_path=None, env_prefix='SCITEX_')[source]

Bases: object

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

__init__(config_path=None, env_prefix='SCITEX_')[source]

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_”)

get(key, default=None)[source]

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:

Configuration value

Return type:

Any

resolve(key, direct_val=None, default=None, type=<class 'str'>)[source]

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:

Resolved value

Return type:

Any

get_nested(*keys, default=None)[source]

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:

Nested value

Return type:

Any

property config_path: Path: Get the path to the loaded config file.

property raw: dict: Get raw configuration data (original nested structure).

property flat: dict: Get flattened configuration data.

print()[source]

Print configuration resolution log.

Return type:: None

scitex.config.get_config(config_path=None)[source]

Get ScitexConfig instance.

Parameters:: config_path (str or Path, optional) – Path to custom config. If None, returns cached default instance.
Returns:: Configuration instance
Return type:: ScitexConfig

scitex.config.load_yaml(path)[source]

Load YAML file with environment variable substitution.

Supports ${VAR:-default} syntax for environment variable expansion.

Parameters:: path (Path) – Path to YAML file
Returns:: Parsed YAML with environment variables substituted
Return type:: dict

class scitex.config.ScitexPaths(base_dir=None)[source]

Bases: object

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

__init__(base_dir=None)[source]

Initialize ScitexPaths.

Parameters:: base_dir (str, optional) – Explicit base directory. If None, uses SCITEX_DIR env var or falls back to ~/.scitex.

property base: Path: Base SciTeX directory ($SCITEX_DIR or ~/.scitex).

property logs: Path: Log files directory.

property cache: Path: General cache directory.

property capture: Path: Screen capture directory.

property screenshots: Path: General screenshots directory.

property rng: Path: Random number generator state directory.

property browser: Path: Browser module base directory.

property browser_screenshots: Path: Browser debugging screenshots.

property browser_sessions: Path: Shared browser sessions.

property browser_persistent: Path: Persistent browser profiles.

property test_monitor: Path: Test monitoring screenshots directory.

property function_cache: Path: Function cache (joblib memory).

property impact_factor_cache: Path: Impact factor data cache.

property openathens_cache: Path: OpenAthens authentication cache.

property scholar: Path: Scholar module base directory.

property scholar_cache: Path: Scholar-specific cache directory.

property scholar_library: Path: Scholar PDF library directory.

property writer: Path: Writer module directory.

resolve(path_name, direct_val=None)[source]

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:

Resolved path

Return type:

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)

ensure_dir(path)[source]

Ensure directory exists, creating if necessary.

Parameters:: path (Path) – Directory path to ensure exists.
Returns:: The same path, guaranteed to exist.
Return type:: Path

ensure_all()[source]

Create all standard directories.

Return type:: None

list_all()[source]

List all configured paths.

Returns:: Dictionary of path names to Path objects.
Return type:: dict

scitex.config.get_paths(base_dir=None)[source]

Get ScitexPaths instance.

Parameters:: base_dir (str, optional) – Explicit base directory. If None, returns cached default instance.
Returns:: Path manager instance.
Return type:: ScitexPaths

class scitex.config.PriorityConfig(config_dict=None, env_prefix='', auto_uppercase=True)[source]

Bases: object

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 (highest after direct)
>>> # With env: SCITEX_PORT=5000 python script.py
>>> port = config.resolve("port", None, default=8000, type=int)
3000  # config_dict takes precedence over env
>>> port = config.resolve("port", 9000, default=8000, type=int)
9000  # direct value takes highest precedence

SENSITIVE_EXPRESSIONS = ['API', 'PASSWORD', 'SECRET', 'TOKEN', 'KEY', 'PASS', 'AUTH', 'CREDENTIAL', 'PRIVATE', 'CERT']

__init__(config_dict=None, env_prefix='', auto_uppercase=True)[source]

Initialize PriorityConfig.

Parameters:

config_dict (dict, optional) – Dictionary with configuration values
env_prefix (str) – Prefix for environment variables (e.g., “SCITEX_”)
auto_uppercase (bool) – Whether to uppercase keys for env lookup

get(key)[source]

Get value from config dict only.

Return type:: Any

resolve(key, direct_val=None, default=None, type=<class 'str'>, mask=None)[source]

Get value with precedence hierarchy.

Precedence: direct → config_dict → env → default

This follows the Scholar module’s CascadeConfig pattern where config dict takes higher priority than environment variables.

Parameters:

key (str) – Configuration key to resolve
direct_val (Any, optional) – Direct value (highest precedence)
default (Any, optional) – Default value if not found elsewhere
type (Type) – Type conversion (str, int, float, bool, list)
mask (bool, optional) – Override automatic masking of sensitive values

Returns:

Resolved configuration value

Return type:

Any

print_resolutions()[source]

Print how each config was resolved.

Return type:: None

clear_log()[source]

Clear resolution log.

Return type:: None

scitex.config.get_scitex_dir(direct_val=None)[source]

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:: Resolved SCITEX_DIR path
Return type:: Path

scitex.config.load_dotenv(dotenv_path=None, *, walk_up=False, stop_at=None)[source]

Load environment variables from .env file(s).

Default behavior (walk_up=False, backward compatible):

Searches for .env file in the following order, loading the first match: 1. Explicit dotenv_path if provided 2. Current working directory (cwd/.env) 3. User home directory ($HOME/.env)

Parent-walking behavior (walk_up=True, opt-in):

Walks parent directories starting from cwd, looking for .env at each level. Stops when reaching stop_at (or $HOME if not given) or the filesystem root. All .env files found are loaded, with the most-distant parent loaded first so that closer-to-cwd values take precedence (closer .env wins). An existing process env var is never overridden by any .env (process env > closest .env > … > root .env).

Note: walk_up=True is ignored if dotenv_path is explicitly given.

Parameters:

dotenv_path (str, optional) – Path to .env file. If None, searches default locations.
walk_up (bool, optional) – If True (and dotenv_path not given), walk parent dirs from cwd. Default False for backward compatibility — new callers should pass True.
stop_at (str or Path, optional) – Directory at which to stop the upward walk (inclusive — its .env is considered). If None, stops at $HOME (or filesystem root if $HOME is not a parent of cwd). Only used when walk_up=True.

Returns:

True if at least one .env file was found and loaded, False otherwise.

Return type:

bool

scitex.config.parse_src_file(filepath)[source]

Parse a bash-compatible .src/.env file and extract env variables.

Parameters:: filepath (Path) – Path to the file.
Returns:: Dictionary of variable names to values.
Return type:: dict

scitex.config.load_env_from_path(path)[source]

Load environment variables from a file or directory.

Parameters:: path (str) – Path to a .src file or directory containing *.src files.
Returns:: All loaded environment variables.
Return type:: dict

scitex.config.load_scitex_env()[source]

Load environment variables from $SCITEX_ENV_SRC if set.

This function should be called early in the MCP server startup.

Returns:: Number of environment variables loaded.
Return type:: int