qcload 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+qcload/__init__.py,sha256=2F_LqRmYYg_KaQBrmvUdtro3rJbUNp3kpUvzb5RGiII,4242
+qcload/config.py,sha256=ltG-X_kQKELTfwNH9dhBI8NGeBC0PVchAFcpmpOKeC8,4408
+qcload/exceptions.py,sha256=NAK431ieCLyUKKdLFVPjnv46m_wnhnpNoHOU20yR8Y4,1248
+qcload/hunter.py,sha256=Iqjm7Arf2MaxmU4R2SNLkcP1WsQimPW-TkVtTZU9Ps8,4388
+qcload/parsers.py,sha256=5lgxnmNeMFzzyh8WFun0KcEo7MALWUUtWQNfJh1oAIw,2720
+qcload-0.1.0.dist-info/METADATA,sha256=S3B_iH_G8dGLcvYVSpoWqKsWUF0w9nl5eiDUvE2NVJU,2179
+qcload-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+qcload-0.1.0.dist-info/RECORD,,

qcload-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any