Utilities

chanfig.utils.Singleton

Bases: type

Metaclass for Singleton Classes.

Source code in chanfig/utils.py

class Singleton(type):
    r"""
    Metaclass for Singleton Classes.
    """

    __instances__: Mapping[type, object] = {}

    def __call__(cls, *args: Any, **kwargs: Any):
        if cls not in cls.__instances__:
            cls.__instances__[cls] = super().__call__(*args, **kwargs)  # type: ignore[index]
        return cls.__instances__[cls]

options: heading_level: 0

chanfig.utils.Null

Null is an instance of NULL.

Since the metaclass of NULL is Singleton, it is advised to use obj is Null to determine if obj is Null.

chanfig.utils.NULL

NULL class.

get method in CHANfiG may accept None or Ellipse(...) as value of default. Therefore, it is mandatory to have a different default value for default.

Null is an instance of NULL and is recommended to be used as obj is Null.

Source code in chanfig/utils.py

class NULL(metaclass=Singleton):
    r"""
    NULL class.

    `get` method in CHANfiG may accept `None` or `Ellipse`(`...`) as value of `default`.
    Therefore, it is mandatory to have a different default value for `default`.

    `Null` is an instance of `NULL` and is recommended to be used as `obj is Null`.
    """

    def __repr__(self):
        return "Null"

    def __nonzero__(self):
        return False

    def __len__(self):
        return 0

    def __call__(self, *args: Any, **kwargs: Any):
        return self

    def __contains__(self, name):
        return False

    def __iter__(self):
        return self

    def __next__(self):
        raise StopIteration

    def __getattr__(self, name):
        return self

    def __getitem__(self, index):
        return self

options: heading_level: 0

chanfig.utils.JsonEncoder

Bases: JSONEncoder

JSON encoder for Config.

Source code in chanfig/utils.py

class JsonEncoder(JSONEncoder):
    r"""
    JSON encoder for Config.
    """

    def default(self, o: Any) -> Any:
        if hasattr(o, "__json__"):
            return o.__json__()
        return super().default(o)

options: heading_level: 0

chanfig.utils.YamlDumper

Bases: SafeDumper

YAML Dumper for Config.

Source code in chanfig/utils.py

class YamlDumper(SafeDumper):  # pylint: disable=R0903
    r"""
    YAML Dumper for Config.
    """

    def increase_indent(self, flow: bool = False, indentless: bool = False):  # pylint: disable=W0235
        return super().increase_indent(flow, indentless)

options: heading_level: 0

chanfig.utils.YamlLoader

Bases: SafeLoader

YAML Loader for Config.

Source code in chanfig/utils.py

class YamlLoader(SafeLoader):
    r"""
    YAML Loader for Config.
    """

    def __init__(self, stream):
        super().__init__(stream)
        self._root = os.path.abspath(os.path.dirname(stream.name)) if hasattr(stream, "name") else os.getcwd()
        self.add_constructor("!include", self._include)
        self.add_constructor("!includes", self._includes)
        self.add_constructor("!env", self._env)

    @staticmethod
    def _include(loader: YamlLoader, node):
        relative_path = loader.construct_scalar(node)
        include_path = os.path.join(loader._root, relative_path)

        if not os.path.exists(include_path):
            raise FileNotFoundError(f"Included file not found: {include_path}")
        from .functional import load

        return load(include_path)

    @staticmethod
    def _includes(loader: YamlLoader, node):
        if not isinstance(node, SequenceNode):
            raise ConstructorError(None, None, f"!includes tag expects a sequence, got {node.id}", node.start_mark)
        files = loader.construct_sequence(node)
        return [YamlLoader._include(loader, ScalarNode("tag:yaml.org,2002:str", file)) for file in files]

    @staticmethod
    def _env(loader: YamlLoader, node):
        env_var = loader.construct_scalar(node)
        value = os.getenv(env_var)
        if value is None:
            raise ValueError(f"Environment variable '{env_var}' not set.")
        return value

options: heading_level: 0