Skip to content

Config

Configuration management for slurmkit projects.

Overview

The Config class manages configuration from multiple sources with the following priority (highest to lowest):

  1. CLI arguments
  2. Environment variables (SLURMKIT_*)
  3. Config file (.slurmkit/config.yaml)
  4. Default values

Classes

Config

Config(config_path: Optional[Union[str, Path]] = None, project_root: Optional[Union[str, Path]] = None)

Configuration manager for slurmkit.

Loads configuration from multiple sources and provides access to settings. Configuration precedence (highest to lowest): 1. Explicit overrides (passed to methods) 2. Environment variables 3. Project config file 4. Built-in defaults

Attributes:

Name Type Description
config_path

Path to the loaded config file (if any)

project_root

Root directory of the project (where .slurmkit/ lives)

hostname

Current machine's hostname (for cluster identification)

Example

config = Config() config.get("jobs_dir") '.jobs/' config.get("slurm_defaults.partition") 'compute'

Initialize configuration.

Parameters:

Name Type Description Default
config_path Optional[Union[str, Path]]

Explicit path to config file. If None, searches for .slurmkit/config.yaml in project_root or current directory.

None
project_root Optional[Union[str, Path]]

Project root directory. If None, uses current directory.

None
Source code in src/slurmkit/config.py
def __init__(
    self,
    config_path: Optional[Union[str, Path]] = None,
    project_root: Optional[Union[str, Path]] = None,
):
    """
    Initialize configuration.

    Args:
        config_path: Explicit path to config file. If None, searches for
            .slurmkit/config.yaml in project_root or current directory.
        project_root: Project root directory. If None, uses current directory.
    """
    self.hostname = socket.gethostname()
    self.project_root = Path(project_root) if project_root else Path.cwd()

    # Determine config file path
    if config_path:
        self.config_path = Path(config_path)
    else:
        # Check environment variable first
        env_config = os.environ.get("SLURMKIT_CONFIG")
        if env_config:
            self.config_path = Path(env_config)
        else:
            self.config_path = self.project_root / METADATA_DIRNAME / CONFIG_FILENAME

    # Load configuration
    self._config = self._load_config()

get

get(key: str, default: Any = None) -> Any

Get a configuration value by dot-separated key path.

Parameters:

Name Type Description Default
key str

Dot-separated key path (e.g., "slurm_defaults.partition")

required
default Any

Default value if key not found.

None

Returns:

Type Description
Any

Configuration value or default.

Example

config.get("jobs_dir") '.jobs/' config.get("slurm_defaults.partition") 'compute' config.get("nonexistent", "fallback") 'fallback'

Source code in src/slurmkit/config.py
def get(self, key: str, default: Any = None) -> Any:
    """
    Get a configuration value by dot-separated key path.

    Args:
        key: Dot-separated key path (e.g., "slurm_defaults.partition")
        default: Default value if key not found.

    Returns:
        Configuration value or default.

    Example:
        >>> config.get("jobs_dir")
        '.jobs/'
        >>> config.get("slurm_defaults.partition")
        'compute'
        >>> config.get("nonexistent", "fallback")
        'fallback'
    """
    return _get_nested(self._config, key, default)

get_path

get_path(key: str, default: Any = None) -> Optional[Path]

Get a configuration value as a Path, resolved relative to project root.

Parameters:

Name Type Description Default
key str

Dot-separated key path.

required
default Any

Default value if key not found.

None

Returns:

Type Description
Optional[Path]

Resolved Path or None.

Source code in src/slurmkit/config.py
def get_path(self, key: str, default: Any = None) -> Optional[Path]:
    """
    Get a configuration value as a Path, resolved relative to project root.

    Args:
        key: Dot-separated key path.
        default: Default value if key not found.

    Returns:
        Resolved Path or None.
    """
    value = self.get(key, default)
    if value is None:
        return None
    path = Path(value)
    if not path.is_absolute():
        path = self.project_root / path
    return path

get_output_patterns

get_output_patterns() -> List[str]

Get output file patterns in priority order.

Returns:

Type Description
List[str]

List of output file pattern strings.

Source code in src/slurmkit/config.py
def get_output_patterns(self) -> List[str]:
    """
    Get output file patterns in priority order.

    Returns:
        List of output file pattern strings.
    """
    patterns = self.get("output_patterns", DEFAULT_CONFIG["output_patterns"])
    if isinstance(patterns, str):
        patterns = [patterns]
    return patterns

get_slurm_defaults

get_slurm_defaults() -> Dict[str, Any]

Get default SLURM arguments.

Returns:

Type Description
Dict[str, Any]

Dictionary of default SLURM arguments.

Source code in src/slurmkit/config.py
def get_slurm_defaults(self) -> Dict[str, Any]:
    """
    Get default SLURM arguments.

    Returns:
        Dictionary of default SLURM arguments.
    """
    return self.get("slurm_defaults", DEFAULT_CONFIG["slurm_defaults"])

as_dict

as_dict() -> Dict[str, Any]

Return the full configuration as a dictionary.

Returns:

Type Description
Dict[str, Any]

Complete configuration dictionary.

Source code in src/slurmkit/config.py
def as_dict(self) -> Dict[str, Any]:
    """
    Return the full configuration as a dictionary.

    Returns:
        Complete configuration dictionary.
    """
    return _deep_copy(self._config)

save

save(path: Optional[Union[str, Path]] = None) -> Path

Save current configuration to a YAML file.

Parameters:

Name Type Description Default
path Optional[Union[str, Path]]

Path to save to. Defaults to self.config_path.

None

Returns:

Type Description
Path

Path where config was saved.

Source code in src/slurmkit/config.py
def save(self, path: Optional[Union[str, Path]] = None) -> Path:
    """
    Save current configuration to a YAML file.

    Args:
        path: Path to save to. Defaults to self.config_path.

    Returns:
        Path where config was saved.
    """
    save_path = Path(path) if path else self.config_path
    save_path.parent.mkdir(parents=True, exist_ok=True)

    with open(save_path, "w") as f:
        yaml.dump(self._config, f, default_flow_style=False, sort_keys=False)

    return save_path

Functions

get_config

get_config(config_path: Optional[Union[str, Path]] = None, project_root: Optional[Union[str, Path]] = None, reload: bool = False) -> Config

Get the global configuration instance.

This function provides a singleton-like access to configuration. On first call (or when reload=True), it creates a new Config instance.

Parameters:

Name Type Description Default
config_path Optional[Union[str, Path]]

Explicit path to config file.

None
project_root Optional[Union[str, Path]]

Project root directory.

None
reload bool

Force reload of configuration.

False

Returns:

Type Description
Config

Global Config instance.

Example

config = get_config() config.get("jobs_dir") '.jobs/'

Source code in src/slurmkit/config.py
def get_config(
    config_path: Optional[Union[str, Path]] = None,
    project_root: Optional[Union[str, Path]] = None,
    reload: bool = False,
) -> Config:
    """
    Get the global configuration instance.

    This function provides a singleton-like access to configuration.
    On first call (or when reload=True), it creates a new Config instance.

    Args:
        config_path: Explicit path to config file.
        project_root: Project root directory.
        reload: Force reload of configuration.

    Returns:
        Global Config instance.

    Example:
        >>> config = get_config()
        >>> config.get("jobs_dir")
        '.jobs/'
    """
    global _global_config

    if _global_config is None or reload:
        _global_config = Config(config_path=config_path, project_root=project_root)

    return _global_config

init_config

init_config(project_root: Optional[Union[str, Path]] = None, overwrite: bool = False, **kwargs: Any) -> Path

Initialize a new project configuration file.

Creates .slurmkit/config.yaml with default values, optionally customized with provided kwargs.

Parameters:

Name Type Description Default
project_root Optional[Union[str, Path]]

Project root directory. Defaults to current directory.

None
overwrite bool

If True, overwrite existing config file.

False
**kwargs Any

Configuration values to set (e.g., jobs_dir="my_jobs/").

{}

Returns:

Type Description
Path

Path to created config file.

Raises:

Type Description
FileExistsError

If config file exists and overwrite=False.

Example

init_config(jobs_dir="experiments/", slurm_defaults={"partition": "gpu"}) PosixPath('.slurmkit/config.yaml')

Source code in src/slurmkit/config.py
def init_config(
    project_root: Optional[Union[str, Path]] = None,
    overwrite: bool = False,
    **kwargs: Any,
) -> Path:
    """
    Initialize a new project configuration file.

    Creates .slurmkit/config.yaml with default values, optionally
    customized with provided kwargs.

    Args:
        project_root: Project root directory. Defaults to current directory.
        overwrite: If True, overwrite existing config file.
        **kwargs: Configuration values to set (e.g., jobs_dir="my_jobs/").

    Returns:
        Path to created config file.

    Raises:
        FileExistsError: If config file exists and overwrite=False.

    Example:
        >>> init_config(jobs_dir="experiments/", slurm_defaults={"partition": "gpu"})
        PosixPath('.slurmkit/config.yaml')
    """
    root = Path(project_root) if project_root else Path.cwd()
    config_path = root / METADATA_DIRNAME / CONFIG_FILENAME

    if config_path.exists() and not overwrite:
        raise FileExistsError(
            f"Config file already exists: {config_path}. "
            "Use overwrite=True to replace."
        )

    # Start with defaults and apply any overrides
    config_data = _deep_copy(DEFAULT_CONFIG)
    for key, value in kwargs.items():
        if isinstance(value, dict) and key in config_data:
            config_data[key] = _deep_merge(config_data[key], value)
        else:
            config_data[key] = value

    # Create directory and write config
    config_path.parent.mkdir(parents=True, exist_ok=True)
    (root / METADATA_DIRNAME / COLLECTIONS_SUBDIR).mkdir(parents=True, exist_ok=True)
    (root / METADATA_DIRNAME / SYNC_SUBDIR).mkdir(parents=True, exist_ok=True)
    (root / METADATA_DIRNAME / LOCKS_SUBDIR / COLLECTION_LOCKS_SUBDIR).mkdir(parents=True, exist_ok=True)
    with open(config_path, "w", encoding="utf-8") as f:
        f.write(format_config_yaml(config_data, with_comments=True))

    return config_path

Usage Example

from slurmkit import Config, get_config

# Get the global config instance
config = get_config()

# Access configuration values
jobs_dir = config.get("jobs_dir")
partition = config.get("slurm_defaults.partition")

# Get as Path object
jobs_path = config.get_path("jobs_dir")

# Get all SLURM defaults
slurm_defaults = config.get_slurm_defaults()