qcload 0.1.0__tar.gz

qcload-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: qcload
+Version: 0.1.0
+Summary: Priority-based config loader for qdata ecosystem — hunts config.yaml/.env from home dir upward through parent dirs
+Project-URL: Homepage, https://github.com/fengl/qcload
+License-Expression: MIT
+Keywords: config,configuration,dotenv,env,quantitative,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qcload
+
+Priority-based config loader for qdata ecosystem.
+
+## Quick start
+
+```python
+from qcload import config, load_config, load_from_path
+
+# Auto-search (global singleton, lazy load)
+db_url = config["DATABASE_URL"]
+
+# Functional call (new instance each time)
+cfg = load_config()
+
+# Load from specific file path
+cfg = load_from_path("/path/to/my/config.yaml")
+
+# Reload the global singleton
+config = reload_config()
+```
+
+## Search priority
+
+`qcload` searches for config files in this order (first found wins):
+
+1. `~/config.yaml` (user home)
+2. `~/.env`
+3. `./config.yaml` (current directory)
+4. `./.env`
+5. `../config.yaml` (parent)
+6. `../.env`
+7. `../../config.yaml` (grandparent)
+8. `../../.env`
+
+## Config object
+
+```python
+cfg = load_config()
+
+# Dict access
+cfg["DATABASE_URL"]
+
+# Attribute access (nested yaml)
+cfg.database.host
+
+# Type helpers
+cfg.get_int("PORT", 8080)
+cfg.get_bool("DEBUG", False)
+cfg.get_float("RATE", 0.0)
+cfg.get_list("HOSTS", [])
+
+# Metadata
+cfg.source       # Path to the loaded file
+cfg.file_type    # "yaml" or "env"
+cfg.is_empty     # True if no keys loaded
+```
+
+## License
+
+MIT

qcload-0.1.0/README.md

@@ -0,0 +1,61 @@
+# qcload
+
+Priority-based config loader for qdata ecosystem.
+
+## Quick start
+
+```python
+from qcload import config, load_config, load_from_path
+
+# Auto-search (global singleton, lazy load)
+db_url = config["DATABASE_URL"]
+
+# Functional call (new instance each time)
+cfg = load_config()
+
+# Load from specific file path
+cfg = load_from_path("/path/to/my/config.yaml")
+
+# Reload the global singleton
+config = reload_config()
+```
+
+## Search priority
+
+`qcload` searches for config files in this order (first found wins):
+
+1. `~/config.yaml` (user home)
+2. `~/.env`
+3. `./config.yaml` (current directory)
+4. `./.env`
+5. `../config.yaml` (parent)
+6. `../.env`
+7. `../../config.yaml` (grandparent)
+8. `../../.env`
+
+## Config object
+
+```python
+cfg = load_config()
+
+# Dict access
+cfg["DATABASE_URL"]
+
+# Attribute access (nested yaml)
+cfg.database.host
+
+# Type helpers
+cfg.get_int("PORT", 8080)
+cfg.get_bool("DEBUG", False)
+cfg.get_float("RATE", 0.0)
+cfg.get_list("HOSTS", [])
+
+# Metadata
+cfg.source       # Path to the loaded file
+cfg.file_type    # "yaml" or "env"
+cfg.is_empty     # True if no keys loaded
+```
+
+## License
+
+MIT

qcload-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qcload"
+version = "0.1.0"
+description = "Priority-based config loader for qdata ecosystem — hunts config.yaml/.env from home dir upward through parent dirs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["config", "configuration", "yaml", "env", "dotenv", "quantitative"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/fengl/qcload"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qcload"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

qcload-0.1.0/src/qcload/__init__.py

@@ -0,0 +1,153 @@
+"""qcload — Priority-based config loader for qdata ecosystem.
+
+Quick start:
+    from qcload import config, load_config, load_from_path
+
+    # Auto-search (global singleton, lazy load)
+    db_url = config["DATABASE_URL"]
+
+    # Functional call (new instance each time)
+    cfg = load_config()
+
+    # Load from specific file path
+    cfg = load_from_path("/path/to/my/config.yaml")
+
+    # Reload the global singleton
+    config = reload_config()
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .config import Config
+from .exceptions import ConfigNotFoundError, ConfigParseError, RequiredKeyError
+from .hunter import hunt, load_from_path as _load_from_path
+
+__all__ = [
+    "config",
+    "load_config",
+    "load_from_path",
+    "reload_config",
+    "Config",
+    "ConfigNotFoundError",
+    "ConfigParseError",
+    "RequiredKeyError",
+]
+
+
+class _GlobalConfig:
+    """Lazy-loading global config singleton.
+
+    The actual hunt/search only runs on first access,
+    so importing qcload never triggers file I/O.
+    """
+
+    def __init__(self) -> None:
+        self._config: Config | None = None
+
+    def _ensure_loaded(self) -> Config:
+        if self._config is None:
+            self._config = load_config()
+        return self._config
+
+    # Delegate everything to the underlying Config object
+
+    def __getitem__(self, key: str) -> Any:
+        return self._ensure_loaded()[key]
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(self._ensure_loaded(), name)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._ensure_loaded()
+
+    def __repr__(self) -> str:
+        if self._config is None:
+            return "Config(<not yet loaded>)"
+        return repr(self._config)
+
+
+# The global singleton — lazy, import-safe
+config = _GlobalConfig()
+
+
+def load_config(
+    cwd: str | Path | None = None,
+    max_parent_depth: int = 2,
+    extra_paths: list[str | Path] | None = None,
+    required: list[str] | None = None,
+) -> Config:
+    """Search for and load the first available config file.
+
+    Priority order (first found wins):
+      1. extra_paths (if provided)
+      2. ~/config.yaml
+      3. ~/.env
+      4. ./config.yaml  (CWD)
+      5. ./.env
+      6. ../config.yaml
+      7. ../.env
+      8. ../../config.yaml
+      9. ../../.env
+
+    Args:
+        cwd: Override working directory for search.
+        max_parent_depth: Parent traversal depth (default 2).
+        extra_paths: Additional file paths with highest priority.
+        required: Keys that must exist in loaded config.
+
+    Returns:
+        Config object with dict/attribute access and type helpers.
+
+    Raises:
+        ConfigNotFoundError: No config file found anywhere.
+        ConfigParseError: Found file but failed to parse.
+        RequiredKeyError: Required keys missing.
+    """
+    data, source, file_type = hunt(cwd, max_parent_depth, extra_paths, required)
+    return Config(data, source=source, file_type=file_type)
+
+
+def load_from_path(
+    file_path: str | Path,
+    required: list[str] | None = None,
+) -> Config:
+    """Load config from a specific file path directly (no search).
+
+    Args:
+        file_path: Path to the config file (.yaml, .yml, or .env).
+        required: Keys that must exist in loaded config.
+
+    Returns:
+        Config object.
+
+    Raises:
+        FileNotFoundError: File does not exist.
+        ConfigParseError: Failed to parse.
+        RequiredKeyError: Required keys missing.
+    """
+    data, source, file_type = _load_from_path(file_path, required)
+    return Config(data, source=source, file_type=file_type)
+
+
+def reload_config(
+    cwd: str | Path | None = None,
+    max_parent_depth: int = 2,
+    extra_paths: list[str | Path] | None = None,
+    required: list[str] | None = None,
+) -> Config:
+    """Force re-search and reload the global config singleton.
+
+    Same arguments as load_config(). Useful after config files
+    are modified on disk.
+
+    Returns:
+        Freshly loaded Config object (also updates the global singleton).
+    """
+    new_cfg = load_config(cwd, max_parent_depth, extra_paths, required)
+    config._config = new_cfg
+    return new_cfg

qcload-0.1.0/src/qcload/config.py

@@ -0,0 +1,135 @@
+"""Config object — dict-like access with attribute access and type helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+class Config:
+    """Rich config wrapper around a plain dict.
+
+    Supports:
+      - Dict access:    config["DATABASE_URL"]
+      - Attribute access: config.database.host  (for nested yaml)
+      - .get() with default:  config.get("KEY", "fallback")
+      - Type helpers:   config.get_int("PORT", 8080)
+                        config.get_bool("DEBUG", False)
+                        config.get_list("HOSTS", [])
+      - Metadata:       config.source, config.file_type, config.is_empty
+    """
+
+    def __init__(
+        self,
+        data: dict[str, Any],
+        source: Path | str | None = None,
+        file_type: str = "unknown",
+    ) -> None:
+        self._data = data
+        self.source = Path(source) if source else None
+        self.file_type = file_type
+
+    # --- dict-style access --------------------------------------------------
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __iter__(self) -> Any:
+        return iter(self._data)
+
+    def __repr__(self) -> str:
+        src = str(self.source) if self.source else "none"
+        return f"Config(source={src}, type={self.file_type}, keys={list(self._data.keys())})"
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value with a fallback default."""
+        return self._data.get(key, default)
+
+    # --- attribute-style access (for nested dicts) -------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            val = self._data[name]
+        except KeyError:
+            raise AttributeError(f"No config key: '{name}'")
+        # Wrap nested dicts so attribute access chains work
+        if isinstance(val, dict):
+            return Config(val, source=self.source, file_type=self.file_type)
+        return val
+
+    # --- type helpers -------------------------------------------------------
+
+    def get_int(self, key: str, default: int = 0) -> int:
+        """Get a value as int. Falls back to default if key missing or conversion fails."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            return default
+
+    def get_bool(self, key: str, default: bool = False) -> bool:
+        """Get a value as bool. Recognizes common truthy/falsy string values."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        if isinstance(val, bool):
+            return val
+        if isinstance(val, str):
+            return val.lower() in ("true", "yes", "1", "on")
+        return bool(val)
+
+    def get_float(self, key: str, default: float = 0.0) -> float:
+        """Get a value as float."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        try:
+            return float(val)
+        except (ValueError, TypeError):
+            return default
+
+    def get_list(self, key: str, default: list[Any] | None = None) -> list[Any]:
+        """Get a value as list. If the value is a string, split by comma."""
+        if default is None:
+            default = []
+        val = self._data.get(key)
+        if val is None:
+            return default
+        if isinstance(val, list):
+            return val
+        if isinstance(val, str):
+            return [item.strip() for item in val.split(",") if item.strip()]
+        return default
+
+    # --- metadata -----------------------------------------------------------
+
+    @property
+    def is_empty(self) -> bool:
+        """True if no config keys were loaded."""
+        return len(self._data) == 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the raw config data as a plain dict."""
+        return dict(self._data)
+
+    def keys(self) -> Any:
+        """Return config keys."""
+        return self._data.keys()
+
+    def values(self) -> Any:
+        """Return config values."""
+        return self._data.values()
+
+    def items(self) -> Any:
+        """Return config items."""
+        return self._data.items()

qcload-0.1.0/src/qcload/exceptions.py

@@ -0,0 +1,35 @@
+"""Custom exceptions for qcload."""
+
+
+class ConfigNotFoundError(Exception):
+    """Raised when no config file is found in any search path."""
+
+    def __init__(self, search_paths: list[str] | None = None) -> None:
+        self.search_paths = search_paths or []
+        paths_str = "\n  - ".join(self.search_paths) if self.search_paths else "(none)"
+        super().__init__(f"No config file found in search paths:\n  - {paths_str}")
+
+
+class ConfigParseError(Exception):
+    """Raised when a config file exists but cannot be parsed."""
+
+    def __init__(self, file_path: str, reason: str = "") -> None:
+        self.file_path = file_path
+        self.reason = reason
+        msg = f"Failed to parse config file: {file_path}"
+        if reason:
+            msg += f" — {reason}"
+        super().__init__(msg)
+
+
+class RequiredKeyError(Exception):
+    """Raised when a required key is missing from the loaded config."""
+
+    def __init__(self, missing_keys: list[str], source: str = "") -> None:
+        self.missing_keys = missing_keys
+        self.source = source
+        keys_str = ", ".join(missing_keys)
+        msg = f"Required keys missing: {keys_str}"
+        if source:
+            msg += f" (source: {source})"
+        super().__init__(msg)

qcload-0.1.0/src/qcload/hunter.py

@@ -0,0 +1,140 @@
+"""Core config hunting logic — searches directories in priority order."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .exceptions import ConfigNotFoundError, RequiredKeyError
+from .parsers import detect_file_type, parse_file
+
+
+# Default config file names to look for at each directory level
+_DEFAULT_NAMES = ["config.yaml", ".env"]
+
+# Maximum number of parent directories to traverse upward from cwd
+_MAX_PARENT_DEPTH = 2
+
+
+def build_search_paths(
+    cwd: str | Path | None = None,
+    max_parent_depth: int = _MAX_PARENT_DEPTH,
+    extra_paths: list[str | Path] | None = None,
+) -> list[Path]:
+    """Build the ordered list of config file paths to search.
+
+    Priority order (first match wins):
+      1. User home dir: config.yaml, .env
+      2. CWD:           config.yaml, .env
+      3. CWD/../:       config.yaml, .env
+      4. CWD/../../:    config.yaml, .env
+      5. User-specified extra_paths (if provided)
+
+    Args:
+        cwd: Current working directory. Defaults to os.getcwd().
+        max_parent_depth: How many parent dirs to traverse upward (default 2).
+        extra_paths: Additional file paths prepended with highest priority.
+
+    Returns:
+        Ordered list of absolute Path objects to check.
+    """
+    if cwd is None:
+        cwd = Path.cwd()
+    else:
+        cwd = Path(cwd).resolve()
+
+    paths: list[Path] = []
+
+    # User-specified paths have highest priority
+    if extra_paths:
+        for p in extra_paths:
+            paths.append(Path(p).resolve())
+
+    # Home directory
+    home = Path.home()
+    for name in _DEFAULT_NAMES:
+        paths.append(home / name)
+
+    # CWD and parent dirs upward
+    current = cwd
+    for _ in range(max_parent_depth + 1):
+        for name in _DEFAULT_NAMES:
+            paths.append(current / name)
+        parent = current.parent
+        if parent == current:
+            # Reached filesystem root, stop
+            break
+        current = parent
+
+    return paths
+
+
+def hunt(
+    cwd: str | Path | None = None,
+    max_parent_depth: int = _MAX_PARENT_DEPTH,
+    extra_paths: list[str | Path] | None = None,
+    required: list[str] | None = None,
+) -> tuple[dict[str, Any], Path, str]:
+    """Search for and load the first available config file.
+
+    Args:
+        cwd: Working directory for search. Defaults to os.getcwd().
+        max_parent_depth: Parent traversal depth (default 2).
+        extra_paths: Additional config file paths (highest priority).
+        required: Keys that must exist in the loaded config.
+                   Raises RequiredKeyError if any are missing.
+
+    Returns:
+        Tuple of (config_dict, source_path, file_type).
+
+    Raises:
+        ConfigNotFoundError: No config file found in any search path.
+        ConfigParseError: Found file but failed to parse it.
+        RequiredKeyError: Required keys missing from loaded config.
+    """
+    search_paths = build_search_paths(cwd, max_parent_depth, extra_paths)
+
+    for path in search_paths:
+        if path.is_file():
+            config = parse_file(path)
+            file_type = detect_file_type(path)
+
+            if required:
+                missing = [k for k in required if k not in config]
+                if missing:
+                    raise RequiredKeyError(missing, str(path))
+
+            return config, path, file_type
+
+    raise ConfigNotFoundError([str(p) for p in search_paths])
+
+
+def load_from_path(file_path: str | Path, required: list[str] | None = None) -> tuple[dict[str, Any], Path, str]:
+    """Load config from a specific file path directly (no search).
+
+    Args:
+        file_path: Absolute or relative path to the config file.
+        required: Keys that must exist in the loaded config.
+
+    Returns:
+        Tuple of (config_dict, source_path, file_type).
+
+    Raises:
+        FileNotFoundError: The specified file does not exist.
+        ConfigParseError: Found file but failed to parse it.
+        RequiredKeyError: Required keys missing from loaded config.
+    """
+    path = Path(file_path).resolve()
+
+    if not path.is_file():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    config = parse_file(path)
+    file_type = detect_file_type(path)
+
+    if required:
+        missing = [k for k in required if k not in config]
+        if missing:
+            raise RequiredKeyError(missing, str(path))
+
+    return config, path, file_type

qcload-0.1.0/src/qcload/parsers.py

@@ -0,0 +1,95 @@
+"""File parsers for yaml and .env config formats."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import dotenv_values
+
+from .exceptions import ConfigParseError
+
+
+def parse_yaml(file_path: str | Path) -> dict[str, Any]:
+    """Parse a YAML config file and return a dict.
+
+    Raises ConfigParseError if the file cannot be read or parsed.
+    """
+    path = Path(file_path)
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigParseError(str(path), f"YAML syntax error: {e}") from e
+    except OSError as e:
+        raise ConfigParseError(str(path), f"IO error: {e}") from e
+
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigParseError(str(path), f"Expected dict, got {type(data).__name__}")
+    return data
+
+
+def parse_env(file_path: str | Path) -> dict[str, str]:
+    """Parse a .env file and return a flat dict of key-value strings.
+
+    Uses python-dotenv's dotenv_values which handles comments,
+    quotes, and multiline values.
+
+    Raises ConfigParseError if the file cannot be read.
+    """
+    path = Path(file_path)
+    try:
+        values = dotenv_values(path)
+    except Exception as e:
+        raise ConfigParseError(str(path), f"Failed to read .env: {e}") from e
+
+    # dotenv_values returns None for empty/unset values
+    result: dict[str, str] = {}
+    for key, val in values.items():
+        if val is not None:
+            result[key] = val
+
+    return result
+
+
+def _is_env_file(path: Path) -> bool:
+    """Check if a path is a .env file.
+
+    Handles both '.env' (dotfile, suffix may be empty on Windows)
+    and 'custom.env' (regular file with .env extension).
+    """
+    name = path.name.lower()
+    return name == ".env" or name.endswith(".env")
+
+
+def parse_file(file_path: str | Path) -> dict[str, Any]:
+    """Auto-detect file format and parse accordingly.
+
+    Dispatches to parse_yaml for .yaml/.yml extensions,
+    parse_env for .env files, and raises ConfigParseError
+    for unsupported formats.
+    """
+    path = Path(file_path)
+    ext = path.suffix.lower()
+
+    if ext in (".yaml", ".yml"):
+        return parse_yaml(path)
+    elif _is_env_file(path):
+        return parse_env(path)
+    else:
+        raise ConfigParseError(str(path), f"Unsupported config format: '{ext}'")
+
+
+def detect_file_type(file_path: str | Path) -> str:
+    """Return 'yaml' or 'env' based on file name/extension."""
+    path = Path(file_path)
+    ext = path.suffix.lower()
+    if ext in (".yaml", ".yml"):
+        return "yaml"
+    elif _is_env_file(path):
+        return "env"
+    return "unknown"

qcload-0.1.0/tests/test_config.py

@@ -0,0 +1,152 @@
+"""Tests for qcload Config object."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from qcload.config import Config
+
+
+class TestConfigDictAccess:
+    """Tests for dict-style access."""
+
+    def test_getitem(self) -> None:
+        cfg = Config({"KEY": "value"}, source="/test/config.yaml", file_type="yaml")
+        assert cfg["KEY"] == "value"
+
+    def test_getitem_missing_raises_keyerror(self) -> None:
+        cfg = Config({"KEY": "value"}, source="/test/config.yaml")
+        with pytest.raises(KeyError):
+            cfg["MISSING"]
+
+    def test_contains(self) -> None:
+        cfg = Config({"KEY": "value"})
+        assert "KEY" in cfg
+        assert "MISSING" not in cfg
+
+    def test_len(self) -> None:
+        cfg = Config({"A": 1, "B": 2, "C": 3})
+        assert len(cfg) == 3
+
+    def test_iter(self) -> None:
+        cfg = Config({"A": 1, "B": 2})
+        assert set(cfg) == {"A", "B"}
+
+    def test_get_with_default(self) -> None:
+        cfg = Config({"KEY": "value"})
+        assert cfg.get("KEY") == "value"
+        assert cfg.get("MISSING", "fallback") == "fallback"
+        assert cfg.get("MISSING") is None
+
+
+class TestConfigAttributeAccess:
+    """Tests for attribute-style access (nested yaml dicts)."""
+
+    def test_simple_attribute(self) -> None:
+        cfg = Config({"database": {"host": "localhost", "port": 5432}})
+        assert cfg.database.host == "localhost"
+        assert cfg.database.port == 5432
+
+    def test_attribute_returns_config_for_nested_dict(self) -> None:
+        cfg = Config({"database": {"host": "localhost"}})
+        nested = cfg.database
+        assert isinstance(nested, Config)
+        assert nested.host == "localhost"
+
+    def test_attribute_missing_raises_attributeerror(self) -> None:
+        cfg = Config({"KEY": "value"})
+        with pytest.raises(AttributeError, match="No config key"):
+            cfg.nonexistent
+
+    def test_private_attr_raises_attributeerror(self) -> None:
+        cfg = Config({})
+        with pytest.raises(AttributeError):
+            cfg._nonexistent
+
+
+class TestConfigTypeHelpers:
+    """Tests for type conversion helpers."""
+
+    def test_get_int(self) -> None:
+        cfg = Config({"PORT": "8080", "ZERO": 0})
+        assert cfg.get_int("PORT") == 8080
+        assert cfg.get_int("ZERO") == 0
+        assert cfg.get_int("MISSING", 3000) == 3000
+
+    def test_get_int_invalid_returns_default(self) -> None:
+        cfg = Config({"PORT": "not_a_number"})
+        assert cfg.get_int("PORT", 8080) == 8080
+
+    def test_get_bool(self) -> None:
+        cfg = Config({
+            "DEBUG_TRUE": "true",
+            "DEBUG_YES": "yes",
+            "DEBUG_ON": "on",
+            "DEBUG_1": "1",
+            "DEBUG_FALSE": "false",
+            "BOOL_TYPE": True,
+        })
+        assert cfg.get_bool("DEBUG_TRUE") is True
+        assert cfg.get_bool("DEBUG_YES") is True
+        assert cfg.get_bool("DEBUG_ON") is True
+        assert cfg.get_bool("DEBUG_1") is True
+        assert cfg.get_bool("DEBUG_FALSE") is False
+        assert cfg.get_bool("BOOL_TYPE") is True
+        assert cfg.get_bool("MISSING", False) is False
+
+    def test_get_float(self) -> None:
+        cfg = Config({"RATE": "3.14"})
+        assert cfg.get_float("RATE") == 3.14
+        assert cfg.get_float("MISSING", 0.0) == 0.0
+
+    def test_get_list_from_yaml_list(self) -> None:
+        cfg = Config({"HOSTS": ["a", "b", "c"]})
+        assert cfg.get_list("HOSTS") == ["a", "b", "c"]
+
+    def test_get_list_from_comma_string(self) -> None:
+        cfg = Config({"HOSTS": "a, b, c"})
+        assert cfg.get_list("HOSTS") == ["a", "b", "c"]
+
+    def test_get_list_missing_returns_default(self) -> None:
+        cfg = Config({})
+        assert cfg.get_list("MISSING") == []
+        assert cfg.get_list("MISSING", ["default"]) == ["default"]
+
+
+class TestConfigMetadata:
+    """Tests for metadata properties."""
+
+    def test_source(self) -> None:
+        cfg = Config({}, source="/test/config.yaml", file_type="yaml")
+        assert cfg.source == Path("/test/config.yaml")
+
+    def test_file_type(self) -> None:
+        cfg = Config({}, file_type="env")
+        assert cfg.file_type == "env"
+
+    def test_is_empty(self) -> None:
+        assert Config({}).is_empty is True
+        assert Config({"KEY": "val"}).is_empty is False
+
+    def test_repr(self) -> None:
+        cfg = Config({"A": 1}, source="/test/config.yaml", file_type="yaml")
+        assert "yaml" in repr(cfg)
+        assert "A" in repr(cfg)
+
+    def test_repr_not_loaded(self) -> None:
+        cfg = Config({})
+        # Just check repr doesn't crash
+        assert isinstance(repr(cfg), str)
+
+    def test_to_dict(self) -> None:
+        data = {"KEY": "value", "PORT": 8080}
+        cfg = Config(data)
+        assert cfg.to_dict() == data
+
+    def test_keys_values_items(self) -> None:
+        cfg = Config({"A": 1, "B": 2})
+        assert set(cfg.keys()) == {"A", "B"}
+        assert set(cfg.values()) == {1, 2}
+        assert set(cfg.items()) == {("A", 1), ("B", 2)}

qcload-0.1.0/tests/test_hunter.py

@@ -0,0 +1,208 @@
+"""Tests for qcload hunter module — config search and loading logic."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from qcload.exceptions import ConfigNotFoundError, RequiredKeyError
+from qcload.hunter import build_search_paths, hunt, load_from_path
+
+
+class TestBuildSearchPaths:
+    """Tests for the search path builder."""
+
+    def test_default_search_order(self) -> None:
+        paths = build_search_paths(cwd="/project/qdata")
+        home = Path.home()
+
+        # Should start with home dir files
+        assert paths[0] == home / "config.yaml"
+        assert paths[1] == home / ".env"
+
+        # Then cwd files
+        cwd = Path("/project/qdata").resolve()
+        assert paths[2] == cwd / "config.yaml"
+        assert paths[3] == cwd / ".env"
+
+        # Then parent files
+        parent = cwd.parent
+        assert paths[4] == parent / "config.yaml"
+        assert paths[5] == parent / ".env"
+
+        # Then grandparent files
+        grandparent = parent.parent
+        assert paths[6] == grandparent / "config.yaml"
+        assert paths[7] == grandparent / ".env"
+
+    def test_extra_paths_have_highest_priority(self) -> None:
+        paths = build_search_paths(
+            cwd="/project",
+            extra_paths=["/custom/config.yaml"],
+        )
+        assert paths[0] == Path("/custom/config.yaml").resolve()
+
+    def test_max_parent_depth_zero(self) -> None:
+        paths = build_search_paths(cwd="/deep/project", max_parent_depth=0)
+        # Home + cwd only, no parent traversal
+        home = Path.home()
+        cwd = Path("/deep/project").resolve()
+
+        home_paths = [p for p in paths if p.parent == home]
+        cwd_paths = [p for p in paths if p.parent == cwd]
+        parent_paths = [p for p in paths if p.parent == cwd.parent]
+
+        assert len(home_paths) == 2
+        assert len(cwd_paths) == 2
+        assert len(parent_paths) == 0
+
+
+class TestHunt:
+    """Tests for the hunt (search & load) function."""
+
+    def test_find_config_in_cwd(self, tmp_path: Path) -> None:
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text("DB_HOST: localhost\nPORT: 5432\n", encoding="utf-8")
+
+        data, source, file_type = hunt(cwd=tmp_path)
+        assert data["DB_HOST"] == "localhost"
+        assert source == config_file
+        assert file_type == "yaml"
+
+    def test_find_env_in_cwd(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("API_KEY=abc123\nDEBUG=true\n", encoding="utf-8")
+
+        data, source, file_type = hunt(cwd=tmp_path)
+        assert data["API_KEY"] == "abc123"
+        assert source == env_file
+        assert file_type == "env"
+
+    def test_yaml_priority_over_env_in_same_dir(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text("KEY: from_yaml\n", encoding="utf-8")
+
+        env_file = tmp_path / ".env"
+        env_file.write_text("KEY=from_env\n", encoding="utf-8")
+
+        data, source, file_type = hunt(cwd=tmp_path)
+        assert data["KEY"] == "from_yaml"
+        assert file_type == "yaml"
+
+    def test_home_priority_over_cwd(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        # Create config in mock home
+        fake_home = tmp_path / "home"
+        fake_home.mkdir()
+        home_config = fake_home / "config.yaml"
+        home_config.write_text("KEY: from_home\n", encoding="utf-8")
+
+        # Create config in cwd (should NOT be loaded)
+        work_dir = tmp_path / "workspace"
+        work_dir.mkdir()
+        cwd_config = work_dir / "config.yaml"
+        cwd_config.write_text("KEY: from_cwd\n", encoding="utf-8")
+
+        monkeypatch.setattr(Path, "home", lambda: fake_home)
+        data, source, file_type = hunt(cwd=work_dir)
+        assert data["KEY"] == "from_home"
+
+    def test_cwd_priority_over_parent(self, tmp_path: Path) -> None:
+        # Parent has config
+        parent_config = tmp_path / "config.yaml"
+        parent_config.write_text("KEY: from_parent\n", encoding="utf-8")
+
+        # Child dir has config (higher priority)
+        child_dir = tmp_path / "child"
+        child_dir.mkdir()
+        child_config = child_dir / "config.yaml"
+        child_config.write_text("KEY: from_child\n", encoding="utf-8")
+
+        data, source, file_type = hunt(cwd=child_dir)
+        assert data["KEY"] == "from_child"
+
+    def test_no_config_found(self, tmp_path: Path) -> None:
+        empty_dir = tmp_path / "empty"
+        empty_dir.mkdir()
+
+        with pytest.raises(ConfigNotFoundError):
+            hunt(cwd=empty_dir)
+
+    def test_required_keys_present(self, tmp_path: Path) -> None:
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text("API_KEY: abc\nDB_URL: postgresql://localhost\n", encoding="utf-8")
+
+        data, source, file_type = hunt(
+            cwd=tmp_path,
+            required=["API_KEY", "DB_URL"],
+        )
+        assert data["API_KEY"] == "abc"
+
+    def test_required_keys_missing(self, tmp_path: Path) -> None:
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text("API_KEY: abc\n", encoding="utf-8")
+
+        with pytest.raises(RequiredKeyError, match="DB_URL"):
+            hunt(cwd=tmp_path, required=["API_KEY", "DB_URL"])
+
+    def test_extra_paths_highest_priority(self, tmp_path: Path) -> None:
+        # Cwd has a config
+        cwd_config = tmp_path / "config.yaml"
+        cwd_config.write_text("KEY: from_cwd\n", encoding="utf-8")
+
+        # Extra path has another config (should win)
+        extra_dir = tmp_path / "extra"
+        extra_dir.mkdir()
+        extra_config = extra_dir / "config.yaml"
+        extra_config.write_text("KEY: from_extra\n", encoding="utf-8")
+
+        data, source, file_type = hunt(
+            cwd=tmp_path,
+            extra_paths=[str(extra_config)],
+        )
+        assert data["KEY"] == "from_extra"
+
+    def test_fallback_to_parent(self, tmp_path: Path) -> None:
+        # Only parent has config
+        parent_config = tmp_path / "config.yaml"
+        parent_config.write_text("KEY: from_parent\n", encoding="utf-8")
+
+        # Child has no config
+        child_dir = tmp_path / "child"
+        child_dir.mkdir()
+
+        data, source, file_type = hunt(cwd=child_dir)
+        assert data["KEY"] == "from_parent"
+
+
+class TestLoadFromPath:
+    """Tests for direct path loading."""
+
+    def test_load_yaml_directly(self, tmp_path: Path) -> None:
+        config_file = tmp_path / "my_config.yaml"
+        config_file.write_text("KEY: value\n", encoding="utf-8")
+
+        data, source, file_type = load_from_path(config_file)
+        assert data["KEY"] == "value"
+        assert file_type == "yaml"
+
+    def test_load_env_directly(self, tmp_path: Path) -> None:
+        env_file = tmp_path / "custom.env"
+        env_file.write_text("KEY=value\n", encoding="utf-8")
+
+        data, source, file_type = load_from_path(env_file)
+        assert data["KEY"] == "value"
+        assert file_type == "env"
+
+    def test_file_not_found(self) -> None:
+        with pytest.raises(FileNotFoundError):
+            load_from_path("/nonexistent/config.yaml")
+
+    def test_required_keys_direct_load(self, tmp_path: Path) -> None:
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text("KEY: value\n", encoding="utf-8")
+
+        with pytest.raises(RequiredKeyError, match="MISSING_KEY"):
+            load_from_path(config_file, required=["KEY", "MISSING_KEY"])

qcload-0.1.0/tests/test_parsers.py

@@ -0,0 +1,143 @@
+"""Tests for qcload parsers module."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from qcload.exceptions import ConfigParseError
+from qcload.parsers import detect_file_type, parse_env, parse_file, parse_yaml
+
+
+class TestParseYaml:
+    """Tests for YAML config parsing."""
+
+    def test_parse_simple_yaml(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text(
+            "database:\n  host: localhost\n  port: 5432\nAPI_KEY: secret123\n",
+            encoding="utf-8",
+        )
+        result = parse_yaml(yaml_file)
+        assert result["database"]["host"] == "localhost"
+        assert result["database"]["port"] == 5432
+        assert result["API_KEY"] == "secret123"
+
+    def test_parse_empty_yaml(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text("", encoding="utf-8")
+        result = parse_yaml(yaml_file)
+        assert result == {}
+
+    def test_parse_yaml_with_lists(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text(
+            "allowed_hosts:\n  - localhost\n  - 127.0.0.1\n  - example.com\n",
+            encoding="utf-8",
+        )
+        result = parse_yaml(yaml_file)
+        assert result["allowed_hosts"] == ["localhost", "127.0.0.1", "example.com"]
+
+    def test_parse_yaml_syntax_error(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text("key: [broken: yaml: here\n", encoding="utf-8")
+        with pytest.raises(ConfigParseError):
+            parse_yaml(yaml_file)
+
+    def test_parse_yaml_non_dict_top_level(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text("just_a_string\n", encoding="utf-8")
+        with pytest.raises(ConfigParseError, match="Expected dict"):
+            parse_yaml(yaml_file)
+
+
+class TestParseEnv:
+    """Tests for .env config parsing."""
+
+    def test_parse_simple_env(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text(
+            "DATABASE_URL=postgresql://localhost/mydb\nAPI_KEY=abc123\nDEBUG=true\n",
+            encoding="utf-8",
+        )
+        result = parse_env(env_file)
+        assert result["DATABASE_URL"] == "postgresql://localhost/mydb"
+        assert result["API_KEY"] == "abc123"
+        assert result["DEBUG"] == "true"
+
+    def test_parse_env_with_comments(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text(
+            "# This is a comment\nKEY=value\n# Another comment\n",
+            encoding="utf-8",
+        )
+        result = parse_env(env_file)
+        assert "KEY" in result
+        assert result["KEY"] == "value"
+
+    def test_parse_env_with_quotes(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text(
+            'QUOTED_KEY="hello world"\n', encoding="utf-8",
+        )
+        result = parse_env(env_file)
+        assert result["QUOTED_KEY"] == "hello world"
+
+    def test_parse_empty_env(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("", encoding="utf-8")
+        result = parse_env(env_file)
+        assert result == {}
+
+    def test_parse_env_skips_none_values(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("KEY=value\nEMPTY=\n", encoding="utf-8")
+        result = parse_env(env_file)
+        assert "KEY" in result
+
+
+class TestParseFile:
+    """Tests for the auto-detect dispatcher."""
+
+    def test_parse_yaml_by_extension(self, tmp_path: Path) -> None:
+        yaml_file = tmp_path / "config.yaml"
+        yaml_file.write_text("key: value\n", encoding="utf-8")
+        result = parse_file(yaml_file)
+        assert result["key"] == "value"
+
+    def test_parse_yml_extension(self, tmp_path: Path) -> None:
+        yml_file = tmp_path / "config.yml"
+        yml_file.write_text("key: value\n", encoding="utf-8")
+        result = parse_file(yml_file)
+        assert result["key"] == "value"
+
+    def test_parse_env_by_extension(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("KEY=value\n", encoding="utf-8")
+        result = parse_file(env_file)
+        assert result["KEY"] == "value"
+
+    def test_parse_unsupported_extension(self, tmp_path: Path) -> None:
+        json_file = tmp_path / "config.json"
+        json_file.write_text("{}\n", encoding="utf-8")
+        with pytest.raises(ConfigParseError, match="Unsupported"):
+            parse_file(json_file)
+
+
+class TestDetectFileType:
+    """Tests for file type detection."""
+
+    def test_yaml(self) -> None:
+        assert detect_file_type("config.yaml") == "yaml"
+
+    def test_yml(self) -> None:
+        assert detect_file_type("config.yml") == "yaml"
+
+    def test_env(self) -> None:
+        assert detect_file_type(".env") == "env"
+
+    def test_unknown(self) -> None:
+        assert detect_file_type("config.json") == "unknown"