gpconfig 0.3.2__py3-none-any.whl

gpconfig/__init__.py

@@ -0,0 +1,31 @@
+# src/gpconfig/__init__.py
+"""gpconfig - General Purpose Configuration management for Python."""
+
+from gpconfig.config import GPConfig
+from gpconfig.configurable import GPConfigurable
+from gpconfig.manager import GPConfigManager, GPConfigFolder
+from gpconfig.exceptions import (
+    GPConfigError,
+    ConfigFolderError,
+    ConfigNotFoundError,
+    ConfigReadonlyError,
+    RegistrationError,
+    ConfigValidationError,
+)
+
+__all__ = [
+    # Core classes
+    "GPConfig",
+    "GPConfigurable",
+    "GPConfigManager",
+    "GPConfigFolder",
+    # Exceptions
+    "GPConfigError",
+    "ConfigFolderError",
+    "ConfigNotFoundError",
+    "ConfigReadonlyError",
+    "RegistrationError",
+    "ConfigValidationError",
+]
+
+__version__ = "0.3.2"

gpconfig/config.py

@@ -0,0 +1,59 @@
+"""GPConfig base class for configuration management."""
+
+from pathlib import Path
+from typing import ClassVar, Optional
+
+import yaml
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from gpconfig.exceptions import ConfigReadonlyError
+
+
+class GPConfig(BaseSettings):
+    """
+    Base class for all configuration classes.
+    Each subclass is initialized from a YAML config file.
+    """
+
+    model_config = SettingsConfigDict(
+        extra="forbid",
+        env_prefix="GPCFG_",
+    )
+
+    # Class-level defaults (can be overridden in subclasses)
+    cfg_class_name: ClassVar[str] = "GPConfig"
+    default_cfg_path: ClassVar[Optional[str]] = None
+
+    # Instance fields (set during initialization, NOT from YAML)
+    name: str = ""
+    cfg_file_path: Path = Path()
+    readonly: bool = False
+    configured_class_name: Optional[str] = None
+
+    def save(self) -> None:
+        """Save current config state back to the YAML file.
+
+        Raises:
+            ConfigReadonlyError: If readonly is True
+        """
+        if self.readonly:
+            raise ConfigReadonlyError(self.name)
+
+        # Get model dump, excluding non-YAML fields
+        data = self.model_dump(
+            mode="python", exclude={"name", "cfg_file_path", "readonly"}
+        )
+
+        # Add cfg_class_name to the saved data
+        data["cfg_class_name"] = self.cfg_class_name
+
+        # Include configured_class_name if set
+        if self.configured_class_name:
+            data["configured_class_name"] = self.configured_class_name
+        else:
+            # Remove it from data if it exists (from model_dump)
+            data.pop("configured_class_name", None)
+
+        # Write to YAML file
+        with open(self.cfg_file_path, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, allow_unicode=True)

gpconfig/configurable.py

@@ -0,0 +1,31 @@
+"""GPConfigurable base class for configurable objects."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gpconfig.config import GPConfig
+
+
+class GPConfigurable:
+    """
+    Base class for objects that are configured by GPConfig subclasses.
+
+    Subclasses must accept a single config parameter in __init__:
+        def __init__(self, config: MyConfigSubclass) -> None:
+            super().__init__(config)
+            # Initialize from config values
+    """
+
+    def __init__(self, config: "GPConfig") -> None:
+        """
+        Initialize the configurable object from its config.
+
+        Args:
+            config: A GPConfig subclass instance containing this object's settings
+        """
+        self._config = config
+
+    @property
+    def config(self) -> "GPConfig":
+        """Access the configuration object."""
+        return self._config

gpconfig/exceptions.py

@@ -0,0 +1,43 @@
+"""Custom exceptions for gpconfig library."""
+
+
+class GPConfigError(Exception):
+    """Base exception for all gpconfig errors."""
+
+    pass
+
+
+class ConfigFolderError(GPConfigError):
+    """Raised when the config folder cannot be found or is invalid."""
+
+    pass
+
+
+class ConfigNotFoundError(GPConfigError):
+    """Raised when a requested config path doesn't exist."""
+
+    def __init__(self, path: str, message: str = ""):
+        self.path = path
+        super().__init__(message or f"Config not found: {path}")
+
+
+class ConfigReadonlyError(GPConfigError):
+    """Raised when trying to modify or save a readonly config."""
+
+    def __init__(self, config_name: str):
+        super().__init__(f"Config '{config_name}' is readonly and cannot be modified")
+
+
+class RegistrationError(GPConfigError):
+    """Raised when there's an issue with class registration."""
+
+    pass
+
+
+class ConfigValidationError(GPConfigError):
+    """Raised when a config file fails validation."""
+
+    def __init__(self, path: str, original_error: Exception):
+        self.path = path
+        self.original_error = original_error
+        super().__init__(f"Validation failed for '{path}': {original_error}")

gpconfig/manager.py

@@ -0,0 +1,744 @@
+"""GPConfigManager - Central configuration manager for gpconfig."""
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, List, Optional, Type, TypeVar, Union
+
+import yaml
+
+if TYPE_CHECKING:
+    from gpconfig.config import GPConfig
+
+from gpconfig.exceptions import (
+    ConfigFolderError,
+    ConfigNotFoundError,
+    ConfigValidationError,
+    RegistrationError,
+)
+
+T = TypeVar("T")
+
+
+class GPConfigFolder:
+    """Represent a subfolder in the config folder hierarchy.
+
+    This class provides convenient access to configs within a specific folder.
+
+    Attributes:
+        path: Relative path from cfg_folder (dot notation, e.g., "llm.providers").
+    """
+
+    def __init__(self, manager: "GPConfigManager", relative_path: str):
+        """Initialize GPConfigFolder.
+
+        Args:
+            manager: The GPConfigManager instance.
+            relative_path: Relative path from cfg_folder using dot notation.
+        """
+        self._manager = manager
+        self._relative_path = relative_path
+
+    @property
+    def path(self) -> str:
+        """Get the relative path of this folder."""
+        return self._relative_path
+
+    def get_config(
+        self, path: str, config_cls: Optional[Type[T]] = None
+    ) -> Union[T, Any]:
+        """Get a config object or value from this folder.
+
+        Args:
+            path: Config path relative to this folder (e.g., "api" or "nested.config").
+            config_cls: Optional GPConfig subclass to use for loading.
+
+        Returns:
+            GPConfig instance, GPConfigFolder, or config value.
+        """
+        full_path = f"{self._relative_path}.{path}" if self._relative_path else path
+        return self._manager.get_config(full_path, config_cls)
+
+    def get_object(self, path: str) -> Any:
+        """Get a configurable object instance from this folder.
+
+        Args:
+            path: Config path relative to this folder.
+
+        Returns:
+            A new instance of the configured GPConfigurable subclass.
+        """
+        full_path = f"{self._relative_path}.{path}" if self._relative_path else path
+        return self._manager.get_object(full_path)
+
+    def list_configs(self) -> List[str]:
+        """List all config objects in this folder.
+
+        Returns:
+            List of object names (config names and subfolder names).
+        """
+        return self._manager.list_configs(self._relative_path)
+
+
+class GPConfigManager:
+    """Central manager for configuration management.
+
+    This class handles initialization, config folder resolution, and provides
+    access to configuration data.
+
+    Attributes:
+        project_name: Name of the project using gpconfig.
+        cfg_folder: Path to the resolved configuration folder.
+        global_env: Dictionary containing global environment configuration.
+
+    Config Folder Search Rules:
+        1. Explicit parameter - cfg_folder argument if provided
+        2. Environment variable - {PROJECT_NAME}_CFG_PATH (uppercase)
+        3. User home subfolder - ~/.{project_name}/
+
+    A valid config folder must contain global_env.yaml.
+    """
+
+    # Class-level registry: cfg_class_name -> GPConfig subclass
+    _config_classes: dict[str, Type[Any]] = {}
+    # Class-level registry: configurable class name -> GPConfigurable subclass
+    _configurable_classes: dict[str, Type[Any]] = {}
+
+    def __init__(self, project_name: str, cfg_folder: Optional[Path | str] = None):
+        """Initialize GPConfigManager.
+
+        Args:
+            project_name: Name of the project.
+            cfg_folder: Optional explicit path to config folder.
+                       If not provided, will search using the resolution rules.
+
+        Raises:
+            ConfigFolderError: If config folder doesn't exist or lacks global_env.yaml.
+        """
+        self._project_name = project_name
+        self._cfg_folder = self._resolve_cfg_folder(project_name, cfg_folder)
+        self._global_env = self._load_global_env()
+        self._config_cache: dict[str, Any] = {}
+        self._folder_cache: dict[str, GPConfigFolder] = {}
+
+    @property
+    def project_name(self) -> str:
+        """Get the project name."""
+        return self._project_name
+
+    @property
+    def cfg_folder(self) -> Path:
+        """Get the config folder path."""
+        return self._cfg_folder
+
+    @property
+    def global_env(self) -> dict:
+        """Get the global environment configuration."""
+        return self._global_env
+
+    def _resolve_cfg_folder(
+        self, project_name: str, cfg_folder: Optional[Path | str]
+    ) -> Path:
+        """Resolve the config folder using search rules.
+
+        Args:
+            project_name: Name of the project.
+            cfg_folder: Optional explicit path to config folder.
+
+        Returns:
+            Resolved Path to config folder.
+
+        Raises:
+            ConfigFolderError: If no valid config folder can be found.
+        """
+        # Rule 1: Explicit parameter
+        if cfg_folder is not None:
+            cfg_path = Path(cfg_folder).resolve()
+            self._validate_cfg_folder(cfg_path, "explicit parameter")
+            return cfg_path
+
+        # Rule 2: Environment variable
+        env_var_name = f"{project_name.upper()}_CFG_PATH"
+        import os
+
+        env_path = os.environ.get(env_var_name)
+        if env_path:
+            cfg_path = Path(env_path).resolve()
+            self._validate_cfg_folder(cfg_path, f"environment variable {env_var_name}")
+            return cfg_path
+
+        # Rule 3: User home subfolder
+        home_path = Path.home() / f".{project_name}"
+        if home_path.exists():
+            cfg_path = home_path.resolve()
+            self._validate_cfg_folder(cfg_path, f"home folder {home_path}")
+            return cfg_path
+
+        # No valid folder found
+        raise ConfigFolderError(
+            f"Could not find valid config folder for project '{project_name}'. "
+            f"Searched: explicit parameter, environment variable {env_var_name}, "
+            f"and home folder {home_path}"
+        )
+
+    def _validate_cfg_folder(self, cfg_path: Path, source: str) -> None:
+        """Validate that the config folder is valid.
+
+        A valid config folder must:
+        - Exist as a directory
+        - Contain global_env.yaml
+
+        Args:
+            cfg_path: Path to validate.
+            source: Description of where the path came from (for error messages).
+
+        Raises:
+            ConfigFolderError: If the folder is invalid.
+        """
+        if not cfg_path.exists():
+            raise ConfigFolderError(
+                f"Config folder does not exist: {cfg_path} (from {source})"
+            )
+
+        if not cfg_path.is_dir():
+            raise ConfigFolderError(
+                f"Config folder path is not a directory: {cfg_path} (from {source})"
+            )
+
+        global_env_path = cfg_path / "global_env.yaml"
+        if not global_env_path.exists():
+            raise ConfigFolderError(
+                f"Config folder must contain global_env.yaml: {cfg_path} (from {source})"
+            )
+
+    def _load_global_env(self) -> dict:
+        """Load global_env.yaml into a dictionary.
+
+        Returns:
+            Dictionary with global environment configuration.
+            Returns empty dict if file is empty or contains only comments.
+        """
+        global_env_path = self._cfg_folder / "global_env.yaml"
+
+        with open(global_env_path, "r", encoding="utf-8") as f:
+            content = yaml.safe_load(f)
+
+        # yaml.safe_load returns None for empty files or files with only comments
+        return content if content is not None else {}
+
+    def _parse_path(self, path: str) -> tuple[Path, Optional[str]]:
+        """
+        Parse a config path into (file_path, optional_key).
+
+        Args:
+            path: Config path string
+
+        Returns:
+            Tuple of (yaml_file_path, optional_key_path)
+
+        Raises:
+            ConfigNotFoundError: If the path cannot be resolved
+        """
+        from gpconfig.exceptions import ConfigNotFoundError
+
+        parts = path.split(".")
+
+        # Strip optional project name prefix
+        if parts[0] == self._project_name:
+            parts = parts[1:]
+
+        if not parts:
+            raise ConfigNotFoundError(path, "Empty config path")
+
+        # Handle global_env specially
+        if parts[0] == "global_env":
+            if len(parts) == 1:
+                raise ConfigNotFoundError(
+                    path, "global_env requires a key path (e.g., 'global_env.debug')"
+                )
+            return (self._cfg_folder / "global_env.yaml", ".".join(parts[1:]))
+
+        # Try to find the config file by progressively treating
+        # trailing parts as keys if file not found
+        for i in range(len(parts), 0, -1):
+            folder_parts = parts[: i - 1]
+            file_part = parts[i - 1]
+            key_parts = parts[i:]
+
+            candidate_path = self._cfg_folder
+            for fp in folder_parts:
+                candidate_path = candidate_path / fp
+
+            yaml_path = candidate_path / f"{file_part}.yaml"
+            if yaml_path.exists():
+                return (yaml_path, ".".join(key_parts) if key_parts else None)
+
+        raise ConfigNotFoundError(path)
+
+    def _check_folder_exists(self, path: str) -> tuple[bool, Path]:
+        """Check if a folder exists at the given path.
+
+        Args:
+            path: Config path (dot notation).
+
+        Returns:
+            Tuple of (exists, full_path).
+        """
+        parts = path.split(".")
+
+        # Strip optional project name prefix
+        if parts[0] == self._project_name:
+            parts = parts[1:]
+
+        if not parts:
+            return (False, Path())
+
+        folder_path = self._cfg_folder
+        for part in parts:
+            folder_path = folder_path / part
+
+        return (folder_path.is_dir(), folder_path)
+
+    def _get_or_create_folder(self, path: str) -> GPConfigFolder:
+        """Get or create a cached GPConfigFolder for the given path.
+
+        Args:
+            path: Config path (dot notation), optionally prefixed with project name.
+
+        Returns:
+            A cached GPConfigFolder instance for the path.
+        """
+        # Normalize path
+        parts = path.split(".")
+        if parts[0] == self._project_name:
+            parts = parts[1:]
+        normalized_path = ".".join(parts)
+
+        if normalized_path not in self._folder_cache:
+            self._folder_cache[normalized_path] = GPConfigFolder(self, normalized_path)
+
+        return self._folder_cache[normalized_path]
+
+    def get_config(
+        self,
+        path: str,
+        config_cls: Optional[Type[T]] = None,
+        *,
+        _force_file: bool = False,
+    ) -> Union[T, Any]:
+        """
+        Get a config object, folder, or a specific config value.
+
+        Args:
+            path: Config path (e.g., "cfg_name" or "cfg_class.cfg_name" or "cfg.path.key")
+            config_cls: Optional GPConfig subclass to use for loading.
+                       If not provided, will try to auto-detect from cfg_class_name in the file.
+
+        Returns:
+            - GPConfigFolder if path points to a folder (and no config_cls, or no file exists)
+            - GPConfig instance if path points to a config file
+            - Config value if path points to a specific key
+
+        Raises:
+            ConfigNotFoundError: If the path doesn't exist
+            ConfigValidationError: If the config fails validation
+        """
+        from pydantic import ValidationError
+
+        # First check if folder exists
+        folder_exists, folder_path = self._check_folder_exists(path)
+
+        # Try to parse as file path
+        try:
+            file_path, key = self._parse_path(path)
+            file_exists = file_path.exists()
+        except ConfigNotFoundError:
+            file_path = None
+            key = None
+            file_exists = False
+
+        # Determine what to return based on existence and config_cls
+        if file_exists and folder_exists:
+            # Both exist: config_cls or _force_file determines priority
+            if config_cls is not None or _force_file:
+                # File priority
+                pass  # Continue with file loading below
+            else:
+                # Folder priority
+                return self._get_or_create_folder(path)
+        elif folder_exists and not file_exists:
+            # Only folder exists
+            return self._get_or_create_folder(path)
+        elif not file_exists and not folder_exists:
+            # Neither exists
+            raise ConfigNotFoundError(path)
+
+        # File loading logic (existing code)
+        # Generate cache key
+        cache_key = str(file_path)
+
+        # Handle global_env key access
+        if file_path.name == "global_env.yaml" and key:
+            return self._get_nested_value(self._global_env, key, path)
+
+        # Load or retrieve cached config
+        if cache_key not in self._config_cache:
+            # Load raw data first
+            with open(file_path, "r", encoding="utf-8") as f:
+                raw_data = yaml.safe_load(f) or {}
+
+            if key:
+                # Key access - just return the value
+                return self._get_nested_value(raw_data, key, path)
+
+            # Auto-detect config class from cfg_class_name if not provided
+            if config_cls is None:
+                cfg_class_name = raw_data.get("cfg_class_name")
+                if cfg_class_name and cfg_class_name in self._config_classes:
+                    config_cls = self._config_classes[cfg_class_name]
+
+            if config_cls is None:
+                # No config class found - return raw dict
+                return raw_data
+
+            try:
+                # Remove cfg_class_name from data before passing to config class
+                # since it's a ClassVar, not an instance field
+                data_for_config = {
+                    k: v for k, v in raw_data.items() if k != "cfg_class_name"
+                }
+                config = self._load_config(file_path, config_cls, data_for_config)
+            except ValidationError as e:
+                raise ConfigValidationError(path, e)
+
+            self._config_cache[cache_key] = config
+
+        config = self._config_cache[cache_key]
+
+        if key:
+            return self._get_nested_value(config.model_dump(), key, path)
+
+        return config
+
+    def _load_config(
+        self, file_path: Path, config_cls: Type[T], data: Optional[dict] = None
+    ) -> T:
+        """Load a config from a YAML file.
+
+        Args:
+            file_path: Path to the YAML file.
+            config_cls: The GPConfig subclass to instantiate.
+            data: Optional pre-loaded data dict. If None, will load from file.
+
+        Returns:
+            Configured GPConfig instance.
+        """
+        if data is None:
+            with open(file_path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+
+        config = config_cls(**data)
+        config.name = file_path.stem
+        config.cfg_file_path = file_path
+        return config
+
+    def _get_nested_value(self, data: dict, key_path: str, full_path: str) -> Any:
+        """Get a nested value from a dict using dot notation."""
+        keys = key_path.split(".")
+        current = data
+
+        for key in keys:
+            if not isinstance(current, dict) or key not in current:
+                raise ConfigNotFoundError(
+                    full_path, f"Key '{key}' not found in path '{full_path}'"
+                )
+            current = current[key]
+
+        return current
+
+    @classmethod
+    def register_config_class(cls, config_cls: Type[Any]) -> None:
+        """Register a config class by its cfg_class_name.
+
+        This method registers config classes that don't configure specific objects,
+        or can be called independently before register_configurable_class.
+
+        Args:
+            config_cls: The GPConfig subclass to register.
+
+        Raises:
+            RegistrationError: If a class with the same cfg_class_name is already registered.
+        """
+        cfg_class_name = config_cls.cfg_class_name
+        if cfg_class_name in cls._config_classes:
+            # Idempotent: allow re-registration of same class
+            if cls._config_classes[cfg_class_name] is config_cls:
+                return
+            raise RegistrationError(
+                f"Config class name '{cfg_class_name}' is already registered "
+                f"with a different class"
+            )
+        cls._config_classes[cfg_class_name] = config_cls
+
+    @classmethod
+    def register_configurable_class(cls, configurable_cls: Type[Any]) -> None:
+        """Register a GPConfigurable subclass by its class name.
+
+        This method registers configurable classes that can be instantiated
+        from config files that specify configured_class_name.
+
+        Args:
+            configurable_cls: The GPConfigurable subclass to register.
+
+        Raises:
+            RegistrationError: If a different class with the same name is already registered.
+        """
+        class_name = configurable_cls.__name__
+        if class_name in cls._configurable_classes:
+            # Idempotent: allow re-registration of same class
+            if cls._configurable_classes[class_name] is configurable_cls:
+                return
+            raise RegistrationError(
+                f"Configurable class name '{class_name}' is already registered "
+                f"with a different class"
+            )
+        cls._configurable_classes[class_name] = configurable_cls
+
+    def get_object(self, path: str) -> Any:
+        """Get a configurable object instance from a config path.
+
+        This method:
+        1. Loads the config using get_config (auto-detects class from cfg_class_name)
+        2. Reads configured_class_name from the config instance
+        3. Looks up the configurable class in _configurable_classes
+        4. Creates a new instance (no caching)
+
+        Args:
+            path: Config path (e.g., "database" or "services.api").
+
+        Returns:
+            A new instance of the configured GPConfigurable subclass.
+
+        Raises:
+            RegistrationError: If the configured_class_name is missing or not registered.
+            ConfigNotFoundError: If the config path doesn't exist.
+        """
+        # Load the config (will auto-detect class from cfg_class_name)
+        # Use _force_file=True to ensure we get file even when folder exists
+        config = self.get_config(path, _force_file=True)
+
+        # If config is a dict, we can still proceed if it has configured_class_name
+        if isinstance(config, dict):
+            class_name = config.get("configured_class_name")
+            if not class_name:
+                raise RegistrationError(
+                    f"Config at path '{path}' was loaded as dict (no registered config class). "
+                    f"Use register_config_class() first, or add 'configured_class_name' to the config."
+                )
+        else:
+            # Get the configured_class_name from the config instance
+            class_name = config.configured_class_name
+
+            if not class_name:
+                raise RegistrationError(
+                    f"Config at path '{path}' has no configured_class_name. "
+                    f"Add 'configured_class_name' to the config file."
+                )
+
+        if class_name not in self._configurable_classes:
+            raise RegistrationError(
+                f"Configured class '{class_name}' not registered for config at '{path}'. "
+                f"Use register_configurable_class() to register it."
+            )
+
+        configurable_cls = self._configurable_classes[class_name]
+        return configurable_cls(config)
+
+    def list_configs(self, path: str = "") -> list[str]:
+        """List all config objects in a folder.
+
+        This method returns names of YAML config files and subfolders,
+        excluding global_env.yaml.
+
+        Args:
+            path: Optional folder path relative to cfg_folder.
+                  Empty string means root folder.
+
+        Returns:
+            List of object names (config names without .yaml extension, and folder names).
+
+        Raises:
+            ConfigNotFoundError: If the folder doesn't exist.
+        """
+        if path:
+            # Convert dot notation to path separators
+            folder_path = self._cfg_folder / Path(
+                path.replace(".", "/") if "." in path else path
+            )
+        else:
+            folder_path = self._cfg_folder
+
+        if not folder_path.exists() or not folder_path.is_dir():
+            raise ConfigNotFoundError(path or "/", f"Folder '{path}' does not exist")
+
+        items = []
+        for item in folder_path.iterdir():
+            # Skip global_env.yaml
+            if item.name == "global_env.yaml":
+                continue
+
+            if item.is_file() and item.suffix == ".yaml":
+                # Add config name without extension
+                items.append(item.stem)
+            elif item.is_dir():
+                # Add folder name
+                items.append(item.name)
+
+        return sorted(items)
+
+    def save(self, config: "GPConfig", path: Optional[str] = None) -> None:
+        """Save a GPConfig instance to a config file.
+
+        This method determines the file path using:
+        1. If `path` is provided: use it as relative path from cfg_folder
+        2. Otherwise: use config's default_cfg_path + name
+
+        The config's cfg_file_path will be set before saving.
+
+        Args:
+            config: The GPConfig instance to save.
+            path: Optional relative path from cfg_folder (e.g., "cache/redis" or "database").
+                  If not provided, uses config.default_cfg_path + config.name.
+
+        Raises:
+            ValueError: If config.name is empty or path cannot be determined.
+            ConfigReadonlyError: If config.readonly is True.
+        """
+        from gpconfig.config import GPConfig
+        from gpconfig.exceptions import ConfigReadonlyError
+
+        if not isinstance(config, GPConfig):
+            raise TypeError(f"Expected GPConfig instance, got {type(config).__name__}")
+
+        if config.readonly:
+            raise ConfigReadonlyError(config.name or "unnamed")
+
+        if not config.name:
+            raise ValueError(
+                "Config must have a non-empty 'name' attribute to be saved"
+            )
+
+        # Determine the file path
+        if path is not None:
+            # Use provided relative path
+            # Normalize path: remove leading slashes, convert dots to slashes
+            relative_path = path.lstrip("/\\").replace(".", "/")
+            file_path = self._cfg_folder / f"{relative_path}.yaml"
+        else:
+            # Use default_cfg_path + name
+            default_path = config.default_cfg_path or ""
+            # Normalize default_path: remove leading/trailing slashes
+            default_path = default_path.strip("/\\")
+
+            if default_path:
+                file_path = self._cfg_folder / default_path / f"{config.name}.yaml"
+            else:
+                file_path = self._cfg_folder / f"{config.name}.yaml"
+
+        # Create parent directories if needed
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Set the config's file path
+        config.cfg_file_path = file_path
+
+        # Call the config's save method
+        config.save()
+
+        # Update cache with the new config
+        cache_key = str(file_path)
+        self._config_cache[cache_key] = config
+
+    @classmethod
+    def make_new_project_config_folder(
+        cls,
+        project_name: str,
+        cfgs: List["GPConfig"],
+        global_env: Optional[dict] = None,
+        cfg_folder_path: Optional[str | Path] = None,
+    ) -> Path:
+        """Create a new project configuration folder with initial configs.
+
+        Args:
+            project_name: Name of the project.
+            cfgs: List of GPConfig instances to save. Each must have a non-empty 'name'.
+            global_env: Optional dictionary for global_env.yaml content.
+            cfg_folder_path: Optional explicit path for the config folder.
+
+        Returns:
+            Path to the created configuration folder.
+
+        Raises:
+            ConfigFolderError: If the config folder already exists.
+            ValueError: If any config in cfgs has an empty 'name'.
+            ConfigReadonlyError: If any config in cfgs has readonly=True.
+        """
+        from gpconfig.config import GPConfig
+        from gpconfig.exceptions import ConfigReadonlyError
+        import os
+
+        # Resolve folder path
+        if cfg_folder_path is not None:
+            folder_path = Path(cfg_folder_path).resolve()
+        else:
+            # Try environment variable
+            env_var_name = f"{project_name.upper()}_CFG_PATH"
+            env_path = os.environ.get(env_var_name)
+            if env_path:
+                folder_path = Path(env_path).resolve()
+            else:
+                # Fallback to home directory
+                folder_path = Path.home() / f".{project_name}"
+
+        # Check if folder already exists
+        if folder_path.exists():
+            raise ConfigFolderError(f"Config folder already exists: {folder_path}")
+
+        # Create folder
+        folder_path.mkdir(parents=True, exist_ok=False)
+
+        # Create global_env.yaml
+        global_env_path = folder_path / "global_env.yaml"
+        with open(global_env_path, "w", encoding="utf-8") as f:
+            yaml.dump(global_env or {}, f, default_flow_style=False, allow_unicode=True)
+
+        # Validate and save configs
+        for config in cfgs:
+            if not isinstance(config, GPConfig):
+                raise TypeError(
+                    f"Expected GPConfig instance, got {type(config).__name__}"
+                )
+
+            if not config.name:
+                raise ValueError(
+                    f"Config of type '{type(config).__name__}' has empty 'name' attribute. "
+                    "All configs must have a non-empty 'name' to be saved."
+                )
+
+            if config.readonly:
+                raise ConfigReadonlyError(config.name)
+
+            # Determine file path from default_cfg_path + name
+            default_path = config.default_cfg_path or ""
+            default_path = default_path.strip("/\\")
+
+            if default_path:
+                file_path = folder_path / default_path / f"{config.name}.yaml"
+            else:
+                file_path = folder_path / f"{config.name}.yaml"
+
+            # Create subdirectories if needed
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Set file path and save
+            config.cfg_file_path = file_path
+            config.save()
+
+        return folder_path

gpconfig-0.3.2.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: gpconfig
+Version: 0.3.2
+Summary: A type-safe, YAML-based configuration management library built on Pydantic
+Project-URL: Homepage, https://github.com/LinnetCodes/gpconfig
+Project-URL: Documentation, https://linnetcodes.github.io/gpconfig
+Project-URL: Repository, https://github.com/LinnetCodes/gpconfig
+Project-URL: Issues, https://github.com/LinnetCodes/gpconfig/issues
+Author-email: HAN Lin <lin_han@foxmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,configuration,pydantic,settings,type-safe,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gpconfig
+
+[简体中文](README.zh-CN.md) | English
+
+General Purpose Configuration management library for Python projects.
+
+A type-safe, YAML-based configuration management library built on Pydantic.
+
+## Features
+
+- **Type-safe configuration** - Built on Pydantic with full type validation
+- **YAML-based** - Human-readable configuration files
+- **Nested configs** - Organize configs in directories (e.g., `llm/openai.yaml`)
+- **Auto-detection** - Automatically detect config classes from YAML files
+- **Configurable objects** - Create object instances directly from configs
+- **Environment variable support** - Configure paths via environment variables
+- **Readonly configs** - Protect sensitive configurations
+
+## Installation
+
+```bash
+pip install gpconfig
+```
+
+## Quick Start
+
+### 1. Define Config Classes
+
+```python
+from typing import ClassVar
+from gpconfig import GPConfig
+
+class DatabaseConfig(GPConfig):
+    cfg_class_name: ClassVar[str] = "DatabaseConfig"
+    host: str
+    port: int = 5432
+    username: str
+    password: str
+    database: str
+```
+
+### 2. Create Config Folder
+
+```
+myapp/
+├── global_env.yaml    # Required: global environment config
+├── database.yaml      # Your config files
+└── llm/               # Nested configs
+    ├── openai.yaml
+    └── anthropic.yaml
+```
+
+**global_env.yaml:**
+```yaml
+version: "1.0.0"
+debug: true
+log_level: INFO
+```
+
+**database.yaml:**
+```yaml
+cfg_class_name: "DatabaseConfig"
+host: localhost
+port: 5432
+username: admin
+password: secret
+database: myapp
+```
+
+### 3. Initialize Manager and Load Configs
+
+```python
+from gpconfig import GPConfigManager
+
+# Config folder search order:
+# 1. Explicit cfg_folder parameter
+# 2. Environment variable: {PROJECT_NAME}_CFG_PATH
+# 3. User directory: ~/.{project_name}/
+manager = GPConfigManager("myapp", cfg_folder="/path/to/myapp")
+
+# Read global_env values
+debug = manager.get_config("global_env.debug")
+
+# Load config (auto-detect class by cfg_class_name)
+db_config = manager.get_config("database")
+
+# Load nested config
+llm_config = manager.get_config("llm.openai")
+
+# Read specific field
+host = manager.get_config("database.host")
+```
+
+### 4. Create Configurable Objects
+
+```python
+from gpconfig import GPConfigurable
+
+class Database(GPConfigurable):
+    def __init__(self, config: DatabaseConfig) -> None:
+        super().__init__(config)
+        self.host = config.host
+        self.port = config.port
+        self.username = config.username
+        self.password = config.password
+        self.database = config.database
+
+    @property
+    def connection_string(self) -> str:
+        return f"postgresql://{self.username}:{self.password}@{self.host}:{self.port}/{self.database}"
+
+# Register classes
+GPConfigManager.register_config_class(DatabaseConfig)
+GPConfigManager.register_configurable_class(Database)
+
+# Create object instance
+db = manager.get_object("database")
+print(db.connection_string)
+```
+
+**Note:** Add `configured_class_name` to your YAML for `get_object()`:
+
+```yaml
+cfg_class_name: "DatabaseConfig"
+configured_class_name: "Database"
+host: localhost
+port: 5432
+```
+
+### 5. Save Configs
+
+```python
+# Modify and save
+db_config.port = 5433
+db_config.save()
+
+# Save to new location
+manager.save(db_config, "backups/database_backup")
+```
+
+## Core Components
+
+| Component | Description |
+|-----------|-------------|
+| `GPConfig` | Base class for all config classes |
+| `GPConfigurable` | Base class for objects created from configs |
+| `GPConfigManager` | Manages config folder, loading, and object creation |
+
+## Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `GPConfigError` | Base exception for all gpconfig errors |
+| `ConfigFolderError` | Config folder not found or invalid |
+| `ConfigNotFoundError` | Requested config path does not exist |
+| `ConfigReadonlyError` | Attempted to modify readonly config |
+| `RegistrationError` | Class registration issues |
+| `ConfigValidationError` | Config file validation failed |
+
+## API Reference
+
+See the [API documentation](docs/api/en/index.md) for detailed usage.
+
+## License
+
+MIT

gpconfig-0.3.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+gpconfig/__init__.py,sha256=NVlzJrH_rzjU5cNz9XLSSXXv8M2AP63-UChHwOBOB7k,734
+gpconfig/config.py,sha256=COOxjsETWZwKcq9OMr4OETomGE5cNyA18FG5wlQ9nf0,1833
+gpconfig/configurable.py,sha256=lUxfZLKmGmo8BZ9DKNM54WL3my2XD9OLYlu7yZeRHKU,864
+gpconfig/exceptions.py,sha256=EbHDkiu50Qj0dtg3IwutQjHOzVDZ3p9-BRqdrM5cJiQ,1180
+gpconfig/manager.py,sha256=PxPydEbg0u3kREZGJkPmEUSS2Z08E0-cmcMxten-eQo,26768
+gpconfig-0.3.2.dist-info/METADATA,sha256=QXn9R-7GORBihAOdLgH7Xvf8axJhemgFkyaJyfTp5Yw,5548
+gpconfig-0.3.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gpconfig-0.3.2.dist-info/licenses/LICENSE,sha256=k7HiaHh7rMfWYAQztyDYhTxCdeuNIuCS-VvOwWgA1iA,1068
+gpconfig-0.3.2.dist-info/RECORD,,

gpconfig-0.3.2.dist-info/WHEEL

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

gpconfig-0.3.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinnetCodes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.