Added ignoring for merging sections, bumped to v0.1.5

Author: shadowy-pycoder

README.md

@@ -44,6 +44,10 @@ database:
     port: 5432
     username: postgres
     password: postgres
+
+redis:
+    host: localhost
+    port: 6379
 ```
 
 ```yaml
@@ -53,7 +57,7 @@ database:
     password: password
 ```
 
-Import configuration files in your Python code with pyya:
+Import configuration files in your Python code with `pyya`:
 
 ```python
 import json
@@ -63,13 +67,14 @@ from pyya import init_config
 config = init_config(
     'config.yaml', 'default.config.yaml', 
     merge_configs = True,
+    sections_ignored_on_merge = ['redis'], # do not include redis on your config
     convert_keys_to_snake_case = False,
     add_underscore_prefix_to_keywords = False
     raise_error_non_identifiers = False)
-print(json.dumps(config.database))
+print(json.dumps(config))
 
 # Output:
-# {"host": "localhost", "port": 5432, "username": "username", "password": "password"}
+# {database: {"host": "localhost", "port": 5432, "username": "username", "password": "password"}}
 
 ```
 
@@ -86,6 +91,11 @@ Under the hood `pyya` uses [PyYAML](https://pypi.org/project/PyYAML/) to parse Y
 # `False` means "open config file and apply `ymal.safe_load` and `munchify` with no formatting"
 merge_configs=True 
 ```
+```python
+# list of sections to ignore when merging configs
+# it is useful when you have examples in your default config but do not want to have in the main one
+sections_ignored_on_merge: Optional[List[str]] = None
+```
 ```python 
 # convert `camelCase` or `PascalCase` keys to `snake_case`
 convert_keys_to_snake_case=True 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyya"
-version = "0.1.4"
+version = "0.1.5"
 authors = [
   { name="shadowy-pycoder", email="[email protected]" },
 ]
@@ -45,7 +45,7 @@ warn_no_return = true
 disallow_any_unimported = false
 warn_unused_configs = true
 disallow_any_generics = true
-disallow_subclassing_any = true
+disallow_subclassing_any = false
 disallow_untyped_calls = false
 disallow_untyped_defs = true
 disallow_incomplete_defs = true

pyya.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyya
-Version: 0.1.4
+Version: 0.1.5
 Summary: Convert YAML configuration files to Python objects
 Author-email: shadowy-pycoder <[email protected]>
 Project-URL: Homepage, https://github.com/shadowy-pycoder/pyya
@@ -28,6 +28,7 @@ Requires-Dist: types-pyyaml>=6.0.12.20240917
 
 ![PyPI - Downloads](https://img.shields.io/pypi/dd/pyya)
 [![ClickPy Dashboard](https://img.shields.io/badge/clickpy-dashboard-orange)](https://clickpy.clickhouse.com/dashboard/pyya)
+![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/shadowy-pycoder/pyya/total)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyya)
 [![PyPI - Link](https://img.shields.io/badge/pypi-link-blue)](https://pypi.org/project/pyya/)
 ![PyPI - Version](https://img.shields.io/pypi/v/pyya)
@@ -49,6 +50,13 @@ Requires-Dist: types-pyyaml>=6.0.12.20240917
 pip install pyya
 ```
 
+Or download a specific version from [Releases](https://github.com/shadowy-pycoder/pyya/releases) page and install it with:
+
+```shell    
+pip install /path/to/pyya-[version]-py3-none-any.whl
+```
+
+
 ## Usage
 
 ### Example
@@ -62,6 +70,10 @@ database:
     port: 5432
     username: postgres
     password: postgres
+
+redis:
+    host: localhost
+    port: 6379
 ```
 
 ```yaml
@@ -71,7 +83,7 @@ database:
     password: password
 ```
 
-Import configuration files in your Python code with pyya:
+Import configuration files in your Python code with `pyya`:
 
 ```python
 import json
@@ -81,13 +93,14 @@ from pyya import init_config
 config = init_config(
     'config.yaml', 'default.config.yaml', 
     merge_configs = True,
+    sections_ignored_on_merge = ['redis'], # do not include redis on your config
     convert_keys_to_snake_case = False,
     add_underscore_prefix_to_keywords = False
     raise_error_non_identifiers = False)
-print(json.dumps(config.database))
+print(json.dumps(config))
 
 # Output:
-# {"host": "localhost", "port": 5432, "username": "username", "password": "password"}
+# {database: {"host": "localhost", "port": 5432, "username": "username", "password": "password"}}
 
 ```
 
@@ -104,6 +117,11 @@ Under the hood `pyya` uses [PyYAML](https://pypi.org/project/PyYAML/) to parse Y
 # `False` means "open config file and apply `ymal.safe_load` and `munchify` with no formatting"
 merge_configs=True 
 ```
+```python
+# list of sections to ignore when merging configs
+# it is useful when you have examples in your default config but do not want to have in the main one
+sections_ignored_on_merge: Optional[List[str]] = None
+```
 ```python 
 # convert `camelCase` or `PascalCase` keys to `snake_case`
 convert_keys_to_snake_case=True 

pyya/__init__.py

@@ -1,11 +1,12 @@
 import keyword
 import logging
 from pathlib import Path
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 import yaml
-from camel_converter import to_snake
-from munch import Munch, munchify
+from camel_converter import to_snake as _to_snake
+from munch import Munch as _Munch
+from munch import munchify as _munchify
 
 
 logging.basicConfig(format='%(asctime)-15s \t%(levelname)-8s \t%(name)-8s \t%(message)s')
@@ -15,6 +16,9 @@
 ConfigType = Dict[str, Any]
 
 
+class PyyaConfig(_Munch): ...
+
+
 class PyyaError(RuntimeError): ...
 
 
@@ -23,29 +27,37 @@ def init_config(
     default_config: Union[str, Path] = 'default.config.yaml',
     *,
     merge_configs: bool = True,
+    sections_ignored_on_merge: Optional[List[str]] = None,
     convert_keys_to_snake_case: bool = False,
     add_underscore_prefix_to_keywords: bool = False,
     raise_error_non_identifiers: bool = False,
-) -> Munch:
-    """
-    Initialize attribute-stylish configuration from YAML file.
+) -> PyyaConfig:
+    """Initialize attribute-stylish configuration from YAML file.
 
     Args:
         config: path to config file
         default_config: path to default config file
         merge_configs: merge default config with config (setting to `False` disables other flags)
-        convert_keys_to_snake_case: convert config keys to snake case
+        sections_ignored_on_merge: list of sections to ignore when merging configs
+        convert_keys_to_snake_case: convert config section names to snake case
         add_underscore_prefix_to_keywords: add underscore prefix to Python keywords
-        raise_error_non_identifiers: raise error if config key is not a valid identifier
+        raise_error_non_identifiers: raise error if config section name is not a valid identifier
     """
 
     def _merge_configs(_raw_data: ConfigType, _default_raw_data: ConfigType) -> None:
         for section, entry in _default_raw_data.items():
+            if sections_ignored_on_merge:
+                if section in sections_ignored_on_merge:
+                    logger.debug(f'section `{section}` ignored on merge')
+                    continue
+                elif isinstance(entry, dict):
+                    # is it fine to proccess already poped dicts on recursion?
+                    entry = _pop_ignored_keys(entry)
             if section not in _raw_data or _raw_data[section] is None:
                 f_section = _sanitize_section(section)
                 if f_section not in _raw_data:
                     _raw_data[f_section] = entry
-                    logger.warning(f'section `{f_section}` with value `{entry}` taken from {default_config}')
+                    logger.info(f'section `{f_section}` with value `{entry}` taken from {default_config}')
                 else:
                     logger.debug(f'section `{f_section}` already exists in {config}, skipping')
             elif isinstance(entry, dict):
@@ -61,16 +73,25 @@ def _merge_configs(_raw_data: ConfigType, _default_raw_data: ConfigType) -> None
     def _sanitize_section(section: str) -> str:
         if convert_keys_to_snake_case:
             logger.debug(f'converting section `{section}` to snake case')
-            section = to_snake(section)
+            section = _to_snake(section)
         if raise_error_non_identifiers and not section.isidentifier():
             err_msg = f'section `{section}` is not a valid identifier, aborting'
             logger.error(err_msg)
             raise PyyaError(err_msg)
         if add_underscore_prefix_to_keywords and keyword.iskeyword(section):
-            logger.warning(f'section `{section}` is a keyword, renaming to `_{section}`')
+            logger.info(f'section `{section}` is a keyword, renaming to `_{section}`')
             section = f'_{section}'
         return section
 
+    def _pop_ignored_keys(data: ConfigType) -> ConfigType:
+        for key, entry in data.copy().items():
+            if key in sections_ignored_on_merge:
+                data.pop(key)
+                logger.debug(f'section `{key}` ignored on merge')
+            elif isinstance(entry, dict):
+                _pop_ignored_keys(entry)
+        return data
+
     try:
         with open(Path(config)) as fstream:
             _raw_data: ConfigType = yaml.safe_load(fstream) or {}
@@ -79,7 +100,7 @@ def _sanitize_section(section: str) -> str:
         logger.error(err_msg)
         raise PyyaError(err_msg) from None
     except FileNotFoundError:
-        logger.warning(f'{config} file not found, using {default_config}')
+        logger.info(f'{config} file not found, using {default_config}')
         _raw_data = {}
 
     if merge_configs:
@@ -98,7 +119,7 @@ def _sanitize_section(section: str) -> str:
             raise PyyaError(f'{default_config} file is missing or empty') from None
         _merge_configs(_raw_data, _default_raw_data)
     try:
-        return munchify(_raw_data)
+        return _munchify(_raw_data)
     except Exception as e:
         err_msg = f'Failed parsing config file: {e}'
         logger.error(err_msg)