conveoconfi 0.1.0__py3-none-any.whl

conveoconfi/__init__.py

@@ -0,0 +1,21 @@
+"""Public compatibility entrypoint for conveoconfi."""
+
+from .config_files import (
+    append_config_file,
+    complete_config_file,
+    config_file_exists,
+    config_file_path,
+    create_and_read_config_file,
+    get_param,
+    overwrite_config_file,
+)
+
+__all__ = [
+    "append_config_file",
+    "complete_config_file",
+    "config_file_exists",
+    "config_file_path",
+    "create_and_read_config_file",
+    "get_param",
+    "overwrite_config_file",
+]

conveoconfi/config_files.py

@@ -0,0 +1,192 @@
+"""Legacy-compatible config file API surface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def _not_implemented(function_name: str) -> None:
+    raise NotImplementedError(f"{function_name} is not implemented yet")
+
+
+def _read_yaml_file(path: Path) -> Any:
+    with path.open("r", encoding="utf-8") as file:
+        return yaml.safe_load(file)
+
+
+def _write_yaml_file(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as file:
+        yaml.safe_dump(data, file, sort_keys=False, allow_unicode=True)
+
+
+def _default_template_path(
+    file_name: str,
+    default_files_dir: str | Path | None = None,
+    default_template_dir: str | Path | None = None,
+) -> Path:
+    if default_files_dir is not None and default_template_dir is not None:
+        raise ValueError(
+            "Pass only one of default_files_dir or default_template_dir, not both"
+        )
+
+    template_dir = default_files_dir if default_files_dir is not None else default_template_dir
+    if template_dir is None:
+        raise FileNotFoundError(
+            "A default template directory is required. Pass default_files_dir "
+            "or default_template_dir."
+        )
+
+    template_path = Path(template_dir).expanduser() / file_name
+    if not template_path.is_file():
+        raise FileNotFoundError(
+            f"Default template for {file_name!r} was not found at {template_path}"
+        )
+
+    return template_path
+
+
+def _read_default_template(
+    file_name: str,
+    default_files_dir: str | Path | None = None,
+    default_template_dir: str | Path | None = None,
+) -> Any:
+    template_path = _default_template_path(
+        file_name,
+        default_files_dir=default_files_dir,
+        default_template_dir=default_template_dir,
+    )
+    data = _read_yaml_file(template_path)
+    if data is None:
+        raise ValueError(f"Default template {template_path} is empty")
+    return data
+
+
+def _complete_config_data(current_data: Any, default_data: Any) -> Any:
+    if not isinstance(current_data, dict) or not isinstance(default_data, dict):
+        return current_data
+
+    completed_data = dict(current_data)
+    for key, default_value in default_data.items():
+        if key not in completed_data:
+            completed_data[key] = default_value
+            continue
+
+        current_value = completed_data[key]
+        if isinstance(current_value, dict) and isinstance(default_value, dict):
+            completed_data[key] = _complete_config_data(current_value, default_value)
+
+    return completed_data
+
+
+def create_and_read_config_file(
+    file_name: str,
+    default_app_dir: str | Path,
+    force_default: bool = False,
+    complete_file: bool = True,
+    default_files_dir: str | Path | None = None,
+    default_template_dir: str | Path | None = None,
+):
+    """Create a missing config file from a YAML template and return parsed data."""
+    path = config_file_path(file_name, default_app_dir)
+    if force_default or not path.exists():
+        data = _read_default_template(
+            file_name,
+            default_files_dir=default_files_dir,
+            default_template_dir=default_template_dir,
+        )
+        _write_yaml_file(path, data)
+        return data
+
+    data = _read_yaml_file(path)
+    if data is None:
+        data = _read_default_template(
+            file_name,
+            default_files_dir=default_files_dir,
+            default_template_dir=default_template_dir,
+        )
+        _write_yaml_file(path, data)
+    elif complete_file:
+        data = complete_config_file(
+            file_name,
+            default_app_dir,
+            default_files_dir=default_files_dir,
+            default_template_dir=default_template_dir,
+        )
+    return data
+
+
+def complete_config_file(
+    file_name: str,
+    default_app_dir: str | Path,
+    default_files_dir: str | Path | None = None,
+    default_template_dir: str | Path | None = None,
+):
+    """Complete a config file with missing values from its default template."""
+    path = config_file_path(file_name, default_app_dir)
+    data = _read_yaml_file(path)
+    default_data = _read_default_template(
+        file_name,
+        default_files_dir=default_files_dir,
+        default_template_dir=default_template_dir,
+    )
+
+    if data is None:
+        _write_yaml_file(path, default_data)
+        return default_data
+
+    completed_data = _complete_config_data(data, default_data)
+    if completed_data != data:
+        _write_yaml_file(path, completed_data)
+    return completed_data
+
+
+def overwrite_config_file(file_name: str, default_app_dir: str | Path, data: Any) -> None:
+    """Overwrite a config file with YAML data."""
+    _write_yaml_file(config_file_path(file_name, default_app_dir), data)
+
+
+def append_config_file(file_name: str, default_app_dir: str | Path, data: Any) -> Any:
+    """Append YAML data to a config file, then rewrite normalized YAML."""
+    path = config_file_path(file_name, default_app_dir)
+    with path.open("a", encoding="utf-8") as file:
+        yaml.safe_dump(data, file, sort_keys=False, allow_unicode=True)
+
+    normalized_data = _read_yaml_file(path)
+    _write_yaml_file(path, normalized_data)
+    return normalized_data
+
+
+def get_param(
+    parent_param: str,
+    param: str,
+    default_app_dir: str | Path,
+    default_files_dir: str | Path | None = None,
+    default_template_dir: str | Path | None = None,
+):
+    """Read a child parameter from the root config.yaml file."""
+    data = create_and_read_config_file(
+        "config.yaml",
+        default_app_dir,
+        default_files_dir=default_files_dir,
+        default_template_dir=default_template_dir,
+    )
+    try:
+        return data[parent_param][param]
+    except (KeyError, TypeError):
+        raise Exception(
+            f"Parameter {param!r} was not found in {parent_param!r}"
+        ) from None
+
+
+def config_file_exists(file_name: str, default_app_dir: str | Path) -> bool:
+    return config_file_path(file_name, default_app_dir).is_file()
+
+
+def config_file_path(file_name: str, default_app_dir: str | Path) -> Path:
+    app_dir = Path(default_app_dir).expanduser()
+    app_dir.mkdir(parents=True, exist_ok=True)
+    return app_dir / file_name

conveoconfi-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: conveoconfi
+Version: 0.1.0
+Summary: Reusable YAML template-backed configuration file helpers.
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# conveoconfi
+
+Reusable YAML template-backed configuration helpers for Python applications.
+
+`conveoconfi` provides a small function-based API for convention-over-
+configuration behavior:
+
+- create missing application config directories
+- create missing YAML config files from application-owned default templates
+- complete existing YAML files with newly added defaults
+- preserve existing user-provided values and extra keys
+- read child parameters from `config.yaml`
+
+## Installation
+
+Install the package with pip, or declare it in your project's dependency
+metadata.
+
+```bash
+pip install conveoconfi
+```
+
+`conveoconfi` declares `PyYAML` as a runtime dependency, so applications do not
+need to add a separate YAML dependency for these helpers.
+
+## Default Templates
+
+Applications keep their own YAML default templates, such as `config.yaml`,
+`logging.yaml`, or `feature_flags.yaml`. Pass that template directory explicitly
+when reading or completing config files.
+
+```python
+from pathlib import Path
+
+from conveoconfi import create_and_read_config_file
+
+
+APP_DIR = Path.home() / ".myapp"
+DEFAULT_FILES_DIR = Path(__file__).parent / "default_files"
+
+config = create_and_read_config_file(
+    "config.yaml",
+    APP_DIR,
+    default_files_dir=DEFAULT_FILES_DIR,
+)
+```
+
+The equivalent keyword `default_template_dir` is also supported. Pass only one
+of `default_files_dir` or `default_template_dir`.
+
+Template lookup failures are explicit. If a default directory is omitted, or the
+requested template file is missing, `conveoconfi` raises a `FileNotFoundError`
+that names the lookup problem.
+
+## Template Discovery Decision
+
+The public API requires applications to pass their template directory
+explicitly with `default_files_dir` or `default_template_dir`. `conveoconfi`
+does not search for templates in its own package directory because those files
+belong to the consuming application, not to this reusable dependency.
+
+Explicit template paths keep behavior predictable in tests, work with any
+project layout, and fail with a direct `FileNotFoundError` when templates are
+not configured. Projects that want a shorter call site can wrap `conveoconfi`
+once in their own code and bind the app's template path there.
+
+## Public API
+
+The public API exposes these function names from the package root:
+
+- `create_and_read_config_file(file_name, default_app_dir, force_default=False, complete_file=True, default_files_dir=None, default_template_dir=None)`
+- `complete_config_file(file_name, default_app_dir, default_files_dir=None, default_template_dir=None)`
+- `overwrite_config_file(file_name, default_app_dir, data)`
+- `append_config_file(file_name, default_app_dir, data)`
+- `get_param(parent_param, param, default_app_dir, default_files_dir=None, default_template_dir=None)`
+- `config_file_exists(file_name, default_app_dir)`
+- `config_file_path(file_name, default_app_dir)`
+
+`config_file_path` creates the application config directory before returning the
+path. `get_param` reads from `config.yaml`.
+
+## Completion Behavior
+
+By default, `create_and_read_config_file` completes existing config files from
+the matching default template and writes the completed result back to disk.
+Completion is recursive for dictionaries:
+
+```yaml
+# Existing user config
+notifications:
+  email:
+    enabled: false
+
+# Default template
+notifications:
+  email:
+    enabled: true
+    sender: hello@example.com
+```
+
+The completed file keeps the user's `enabled: false` value and adds only the
+missing `sender` value. User-defined extra keys are preserved. If a
+current value and default value disagree on shape, such as a scalar versus a
+dictionary, the current user value is preserved.
+
+Use `force_default=True` to deliberately replace an existing config file with
+template defaults. Use `complete_file=False` to read an existing file without
+mutating it.

conveoconfi-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+conveoconfi/__init__.py,sha256=7oz23y3d-zeHyTwhN60Jyuu4dESC4haP4p6V3iPbiFk,457
+conveoconfi/config_files.py,sha256=C2NF-feI5Nlz7bXrfNR3xp5Cg9tVeVh1O1c08Ae3ZbY,6259
+conveoconfi-0.1.0.dist-info/METADATA,sha256=mPRTkYediebZYxo8et99NjcpiNEcpSnxU19M89Zhz70,4113
+conveoconfi-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+conveoconfi-0.1.0.dist-info/RECORD,,

conveoconfi-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