tessl/pypi-omegaconf

A flexible configuration library that provides hierarchical configuration management with YAML support, variable interpolation, and type validation

—

Pending

Overview

Eval results

Files

Utilities & Context Managers

Name: tessl/pypi-omegaconf
Author: tessl

Helper functions, context managers for temporary configuration state changes, and utility methods for configuration inspection and conversion.

Capabilities

Context Managers

Context managers for temporarily modifying configuration behavior without permanent changes.

def open_dict(config):
    """
    Temporarily disable struct mode to allow new key additions.
    
    Parameters:
    - config: Configuration to modify
    
    Usage:
    with OmegaConf.open_dict(config):
        config.new_key = "new_value"  # Allowed even in struct mode
    # Struct mode restored after context
    """

def read_write(config):
    """
    Temporarily make configuration read-write.
    
    Parameters:
    - config: Configuration to modify
    
    Usage:
    with OmegaConf.read_write(config):
        config.key = "modified"  # Allowed even if config is readonly
    # Readonly state restored after context
    """

def flag_override(config, names, values):
    """
    Temporarily override configuration flags.
    
    Parameters:
    - config: Configuration to modify
    - names: Flag name or list of flag names
    - values: Flag value or list of flag values
    
    Usage:
    with OmegaConf.flag_override(config, "readonly", False):
        config.key = "modified"  # Readonly temporarily disabled
    """

Configuration Inspection

Methods for checking configuration types, states, and properties.

def is_config(obj):
    """
    Check if object is an OmegaConf configuration.
    
    Parameters:
    - obj: Object to check
    
    Returns:
    True if obj is DictConfig or ListConfig
    """

def is_dict(obj):
    """
    Check if object is a DictConfig.
    
    Parameters:
    - obj: Object to check
    
    Returns:
    True if obj is DictConfig
    """

def is_list(obj):
    """
    Check if object is a ListConfig.
    
    Parameters:
    - obj: Object to check
    
    Returns:
    True if obj is ListConfig
    """

def is_missing(cfg, key):
    """
    Check if key has missing mandatory value (???).
    
    Parameters:
    - cfg: Configuration to check
    - key: Key to check for missing value
    
    Returns:
    True if key exists and has missing value
    """

def is_interpolation(node, key=None):
    """
    Check if value contains interpolation.
    
    Parameters:
    - node: Configuration node to check
    - key: Optional specific key to check
    
    Returns:
    True if value contains interpolation expressions
    """

Configuration State Management

Methods for managing configuration flags and behavior modes.

def set_readonly(conf, value):
    """
    Set read-only flag on configuration.
    
    Parameters:
    - conf: Configuration to modify
    - value: True to make readonly, False to make writable
    """

def is_readonly(conf):
    """
    Check if configuration is read-only.
    
    Parameters:
    - conf: Configuration to check
    
    Returns:
    True if configuration is read-only
    """

def set_struct(conf, value):
    """
    Set struct flag on configuration.
    
    Parameters:
    - conf: Configuration to modify
    - value: True to enable struct mode, False to disable
    
    Notes:
    - Struct mode prevents addition of new keys
    - Helps prevent typos and enforces schema
    """

def is_struct(conf):
    """
    Check if configuration is in struct mode.
    
    Parameters:
    - conf: Configuration to check
    
    Returns:
    True if configuration is in struct mode
    """

Configuration Conversion

Methods for converting configurations to different formats and representations.

def to_container(cfg, resolve=False, throw_on_missing=True, enum_to_str=False, structured_config_mode=SCMode.DICT):
    """
    Convert configuration to primitive Python containers.
    
    Parameters:
    - cfg: Configuration to convert
    - resolve: Whether to resolve interpolations
    - throw_on_missing: Whether to raise on missing values
    - enum_to_str: Whether to convert enums to strings
    - structured_config_mode: How to handle structured configs
    
    Returns:
    Plain Python dict/list with primitive values
    """

def to_yaml(cfg, resolve=False, sort_keys=False):
    """
    Convert configuration to YAML string.
    
    Parameters:
    - cfg: Configuration to convert
    - resolve: Whether to resolve interpolations before conversion
    - sort_keys: Whether to sort dictionary keys in output
    
    Returns:
    YAML string representation of configuration
    """

Cache Management

Methods for managing resolver result caching.

def get_cache(conf):
    """
    Get resolver cache for configuration.
    
    Parameters:
    - conf: Configuration to get cache from
    
    Returns:
    Cache dict containing resolver results
    """

def set_cache(conf, cache):
    """
    Set resolver cache for configuration.
    
    Parameters:
    - conf: Configuration to set cache on
    - cache: Cache dict to set
    """

def clear_cache(conf):
    """
    Clear resolver cache for configuration.
    
    Parameters:
    - conf: Configuration to clear cache from
    """

def copy_cache(from_config, to_config):
    """
    Copy resolver cache between configurations.
    
    Parameters:
    - from_config: Source configuration
    - to_config: Destination configuration
    """

def masked_copy(conf, keys):
    """
    Create copy with only specified keys included.
    
    Parameters:
    - conf: Configuration to copy
    - keys: List of keys to include in copy
    
    Returns:
    New configuration with only specified keys
    """

Package Information

__version__: str = "2.3.0"  # Package version number

Usage Examples

Context Manager Usage

from omegaconf import OmegaConf

# Create a struct config (no new keys allowed)
config = OmegaConf.create({"existing_key": "value"}, flags={"struct": True})

try:
    config.new_key = "fails"  # Raises exception
except Exception:
    print("Cannot add new key in struct mode")

# Temporarily allow new keys
with OmegaConf.open_dict(config):
    config.new_key = "allowed"  # Works inside context
    config.another_key = {"nested": "value"}

print(config.new_key)  # "allowed" - key persists
# But struct mode is restored, so new additions will fail again

# Read-only example
OmegaConf.set_readonly(config, True)

try:
    config.existing_key = "fails"  # Raises exception
except Exception:
    print("Cannot modify readonly config")

# Temporarily allow modifications
with OmegaConf.read_write(config):
    config.existing_key = "modified"  # Works inside context

print(config.existing_key)  # "modified" - change persists
# But readonly mode is restored

# Flag override for multiple flags
with OmegaConf.flag_override(config, ["readonly", "struct"], [False, False]):
    config.existing_key = "changed"
    config.brand_new_key = "added"

Configuration Inspection

from omegaconf import OmegaConf

dict_config = OmegaConf.create({"a": 1, "b": "???"})
list_config = OmegaConf.create([1, 2, 3])
regular_dict = {"x": "y"}

# Type checking
print(OmegaConf.is_config(dict_config))   # True
print(OmegaConf.is_config(regular_dict))  # False

print(OmegaConf.is_dict(dict_config))     # True
print(OmegaConf.is_dict(list_config))     # False

print(OmegaConf.is_list(list_config))     # True
print(OmegaConf.is_list(dict_config))     # False

# Missing value detection
print(OmegaConf.is_missing(dict_config, "a"))  # False
print(OmegaConf.is_missing(dict_config, "b"))  # True

# Interpolation detection
interp_config = OmegaConf.create({"ref": "${other.key}", "plain": "value"})
print(OmegaConf.is_interpolation(interp_config, "ref"))    # True
print(OmegaConf.is_interpolation(interp_config, "plain"))  # False

State Management

from omegaconf import OmegaConf

config = OmegaConf.create({"key": "value"})

# Check initial state
print(OmegaConf.is_readonly(config))  # False
print(OmegaConf.is_struct(config))    # False

# Set readonly mode
OmegaConf.set_readonly(config, True)
print(OmegaConf.is_readonly(config))  # True

try:
    config.key = "modified"  # Fails
except Exception:
    print("Cannot modify readonly config")

# Set struct mode
OmegaConf.set_readonly(config, False)  # Allow modifications
OmegaConf.set_struct(config, True)

try:
    config.new_key = "fails"  # Fails in struct mode
except Exception:
    print("Cannot add new keys in struct mode")

config.key = "allowed"  # Modifying existing keys works

Configuration Conversion

from omegaconf import OmegaConf
from enum import Enum

class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

config = OmegaConf.create({
    "name": "MyApp",
    "color": Color.RED,
    "server": {
        "host": "localhost",
        "port": 8080,
        "url": "http://${server.host}:${server.port}"
    },
    "features": ["auth", "logging"]
})

# Convert to plain Python containers
plain_dict = OmegaConf.to_container(config)
print(type(plain_dict))  # <class 'dict'>
print(plain_dict["color"])  # <Color.RED: 'red'>

# Convert with enum-to-string conversion
plain_dict_str = OmegaConf.to_container(config, enum_to_str=True)
print(plain_dict_str["color"])  # "red"

# Convert with interpolation resolution
resolved_dict = OmegaConf.to_container(config, resolve=True)
print(resolved_dict["server"]["url"])  # "http://localhost:8080"

# Convert to YAML
yaml_str = OmegaConf.to_yaml(config)
print(yaml_str)
# Output:
# name: MyApp
# color: !Color 'red'
# server:
#   host: localhost
#   port: 8080
#   url: http://${server.host}:${server.port}
# features:
# - auth
# - logging

# Convert to YAML with resolution and sorting
yaml_resolved = OmegaConf.to_yaml(config, resolve=True, sort_keys=True)

Cache Management

from omegaconf import OmegaConf

# Register cached resolver
OmegaConf.register_new_resolver("expensive", lambda: "computed_value", use_cache=True)

config = OmegaConf.create({
    "value1": "${expensive:}",
    "value2": "${expensive:}"
})

# Access values to populate cache
print(config.value1)  # Computes and caches result
print(config.value2)  # Uses cached result

# Inspect cache
cache = OmegaConf.get_cache(config)
print(cache)  # Contains cached resolver results

# Clear cache
OmegaConf.clear_cache(config)
print(OmegaConf.get_cache(config))  # Empty cache

# Copy cache between configs
config2 = OmegaConf.create({"other": "${expensive:}"})
print(config2.other)  # Computes value
OmegaConf.copy_cache(config2, config)  # Copy cache to first config

Install with Tessl CLI