added CLI tool to genearte stub files

Author: shadowy-pycoder

README.md

@@ -17,6 +17,7 @@
 - Automatically `merge` default and production configuration files
 - Convert keys in configuration files to `snake_case`
 - YAML validation with `Pydantic` models
+- Generate stub files for your dynamic configuration with `pyya` CLI tool.
 
 ## Installation
 
@@ -60,6 +61,7 @@ database:
 Import configuration files in your Python code with `pyya`:
 
 ```python
+# config.py
 import json
 
 from pyya import init_config, logger
@@ -138,6 +140,18 @@ allow_extra_sections=True
 warn_extra_sections=True
 ```
 
+By default autocompletion does not work with attribute-style configurations generated by `pyya`.
+However, you can generate special stub files with `.pyi` extension to make you LSP or `mypy` to properly suggest configuration fields.
+
+With `pyya` it actually very straightforward (assuming you have `config.py` file like in the example above):
+
+```shell
+# pyya is a CLI tool installed automatically when you run pip install
+pyya --input "default.config.yaml" --output "config.pyi"
+```
+
+This will create a special file with type hints for `config.py` file (note that both files should have the same basename).
+
 ## Contributing
 
 Are you a developer?

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyya"
-version = "0.1.8"
+version = "0.1.9"
 description = "Convert YAML configuration files to Python objects"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -33,6 +33,9 @@ Homepage = "https://github.com/shadowy-pycoder/pyya"
 Issues = "https://github.com/shadowy-pycoder/pyya/issues"
 Repository = "https://github.com/shadowy-pycoder/pyya"
 
+[project.scripts]
+pyya = "pyya.__main__:main"
+
 [tool.mypy]
 python_version = "3.8"
 cache_dir = ".mypy_cache/strict"

pyya.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyya
-Version: 0.1.8
+Version: 0.1.9
 Summary: Convert YAML configuration files to Python objects
 Author-email: shadowy-pycoder <[email protected]>
 Project-URL: Homepage, https://github.com/shadowy-pycoder/pyya
@@ -44,6 +44,7 @@ Requires-Dist: types-pyyaml>=6.0.12.20240917
 - Automatically `merge` default and production configuration files
 - Convert keys in configuration files to `snake_case`
 - YAML validation with `Pydantic` models
+- Generate stub files for your dynamic configuration with `pyya` CLI tool.
 
 ## Installation
 
@@ -87,6 +88,7 @@ database:
 Import configuration files in your Python code with `pyya`:
 
 ```python
+# config.py
 import json
 
 from pyya import init_config, logger
@@ -165,6 +167,18 @@ allow_extra_sections=True
 warn_extra_sections=True
 ```
 
+By default autocompletion does not work with attribute-style configurations generated by `pyya`.
+However, you can generate special stub files with `.pyi` extension to make you LSP or `mypy` to properly suggest configuration fields.
+
+With `pyya` it actually very straightforward (assuming you have `config.py` file like in the example above):
+
+```shell
+# pyya is a CLI tool installed automatically when you run pip install
+pyya --input "default.config.yaml" --output "config.pyi"
+```
+
+This will create a special file with type hints for `config.py` file (note that both files should have the same basename).
+
 ## Contributing
 
 Are you a developer?

pyya.egg-info/SOURCES.txt

@@ -2,9 +2,11 @@ LICENSE
 README.md
 pyproject.toml
 pyya/__init__.py
+pyya/__main__.py
 pyya/py.typed
 pyya.egg-info/PKG-INFO
 pyya.egg-info/SOURCES.txt
 pyya.egg-info/dependency_links.txt
+pyya.egg-info/entry_points.txt
 pyya.egg-info/requires.txt
 pyya.egg-info/top_level.txt

pyya.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyya = pyya.__main__:main

pyya/__init__.py

@@ -3,7 +3,7 @@
 from copy import deepcopy
 from pathlib import Path
 from pprint import pformat
-from typing import Any, Dict, List, Optional, Type, Union
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
 
 import yaml as _yaml
 from camel_converter import to_snake as _to_snake
@@ -37,6 +37,8 @@ def init_config(
     validate_data_types: bool = True,
     allow_extra_sections: bool = True,
     warn_extra_sections: bool = True,
+    _generate_stub: bool = False,
+    _stub_variable_name: str = 'config',
 ) -> PyyaConfig:
     """Initialize attribute-stylish configuration from YAML file.
 
@@ -154,24 +156,85 @@ def extra_flat(self) -> Any:
                     extra_flat.update(data)
             return extra_flat
 
-    def _model_from_dict(name: str, data: Dict[str, Any]) -> Type[BaseModel]:
+    def _model_and_stub_from_dict(
+        name: str, data: Dict[str, Any], path: Optional[List[str]] = None
+    ) -> Tuple[Type[ExtraBase], str]:
         fields: Dict[Any, Any] = {}
+        if path is None:
+            path = []
+        class_name = ''.join(part.capitalize() if i > 0 else part for i, part in enumerate(path + [name]))
+        stub_lines = [f'class {class_name}:']
+        nested_stubs = []
+        py_type: Any
         for section, entry in data.items():
             if isinstance(entry, Dict):
-                nested_model = _model_from_dict(section, entry)
+                nested_model, nested_stub = _model_and_stub_from_dict(section, entry, path + [name])
+                if not keyword.iskeyword(section) and section.isidentifier():
+                    stub_lines.append(f'    {section}: {class_name + section.capitalize()}')
+                    nested_stubs.append(nested_stub)
                 fields[section] = (nested_model, entry)
             elif isinstance(entry, list) and entry:
                 first_item = entry[0]
                 if isinstance(first_item, Dict):
-                    nested_model = _model_from_dict(f'{section.capitalize()}Item', first_item)
+                    nested_model, nested_stub = _model_and_stub_from_dict(
+                        f'{section.capitalize()}_item', first_item, path + [name]
+                    )
+                    if not keyword.iskeyword(section) and section.isidentifier():
+                        stub_lines.append(f'    {section}: List[{class_name + section.capitalize()}_item]')
+                        nested_stubs.append(nested_stub)
                     fields[section] = (List[nested_model], entry)  # type: ignore
                 else:
-                    fields[section] = (List[type(first_item)], entry)  # type: ignore
+                    py_type = type(first_item)
+                    if not keyword.iskeyword(section) and section.isidentifier():
+                        stub_lines.append(f'    {section}: List[{py_type.__name__}]')
+                    fields[section] = (List[py_type], entry)
             elif isinstance(entry, list):
+                if not keyword.iskeyword(section) and section.isidentifier():
+                    stub_lines.append(f'    {section}: List[Any]')
                 fields[section] = (List[Any], entry)
             else:
-                fields[section] = (type(entry), entry)
-        return create_model(name, **fields, __base__=ExtraBase)
+                py_type = type(entry)
+                if not keyword.iskeyword(section) and section.isidentifier():
+                    stub_lines.append(f'    {section}: {py_type.__name__}')
+                fields[section] = (py_type, entry)
+        stub_code = '\n\n'.join(nested_stubs + ['\n'.join(stub_lines)]).replace('-', '_')
+        return create_model(name, **fields, __base__=ExtraBase), stub_code
+
+    def _get_default_raw_data() -> ConfigType:
+        try:
+            try:
+                with open(Path(default_config)) as fstream:
+                    _default_raw_data: Optional[ConfigType] = _yaml.safe_load(fstream)
+            except _yaml.YAMLError as e:
+                err_msg = f'{default_config} file is corrupted: {e}'
+                logger.error(err_msg)
+                raise PyyaError(err_msg) from None
+            if _default_raw_data is None:
+                raise FileNotFoundError()
+        except FileNotFoundError as e:
+            logger.error(e)
+            raise PyyaError(f'{default_config} file is missing or empty') from None
+        _default_raw_data = _sanitize_keys(_default_raw_data)
+        return _default_raw_data
+
+    if _generate_stub:
+        output_file = Path(config)
+        if output_file.exists():
+            err_msg = f'{output_file} already exists'
+            logger.error(err_msg)
+            raise PyyaError(err_msg)
+        _default_raw_data = _get_default_raw_data()
+        _, stub = _model_and_stub_from_dict('Config', _default_raw_data)
+        stub_full = (
+            f'# {output_file} was autogenerated with pyya CLI tool, see `pyya -h`\nfrom typing import Any, List\n\n'
+            f'{stub}\n\n'
+            '# for type hints to work the variable name created with pyya.init_config\n'
+            '# should have the same name (e.g. config = pyya.init_config())\n'
+            f'{_stub_variable_name}: Config\n'
+        )
+        output_file.write_text(stub_full)
+        logger.info(f'{output_file} created')
+        return PyyaConfig()
 
     try:
         with open(Path(config)) as fstream:
@@ -194,26 +257,13 @@ def _model_from_dict(name: str, data: Dict[str, Any]) -> Type[BaseModel]:
             err_msg = f'Failed parsing `sections_ignored_on_merge`: {e!r}'
             logger.error(err_msg)
             raise PyyaError(err_msg) from None
-        try:
-            try:
-                with open(Path(default_config)) as fstream:
-                    _default_raw_data: Optional[ConfigType] = _yaml.safe_load(fstream)
-                    _default_raw_data = _sanitize_keys(_default_raw_data)
-            except _yaml.YAMLError as e:
-                err_msg = f'{default_config} file is corrupted: {e}'
-                logger.error(err_msg)
-                raise PyyaError(err_msg) from None
-            if _default_raw_data is None:
-                raise FileNotFoundError()
-        except FileNotFoundError as e:
-            logger.error(e)
-            raise PyyaError(f'{default_config} file is missing or empty') from None
+        _default_raw_data = _get_default_raw_data()
         # create copy for logging (only overwritten fields)
         _raw_data_copy = deepcopy(_raw_data)
         _merge_configs(_raw_data, _default_raw_data)
         logger.debug(f'Resulting config after merge:\n{pformat(_raw_data)}')
         if validate_data_types:
-            ConfigModel = _model_from_dict('ConfigModel', _default_raw_data)
+            ConfigModel, _ = _model_and_stub_from_dict('ConfigModel', _default_raw_data)
             try:
                 validated_raw_data = ConfigModel.model_validate(_raw_data)
                 if extra_sections := validated_raw_data.extra_flat:  # type: ignore
@@ -231,7 +281,7 @@ def _model_from_dict(name: str, data: Dict[str, Any]) -> Type[BaseModel]:
             logger.info(f'The following sections were overwritten:\n{pformat(_raw_data_copy)}')
     try:
         logger.debug(f'Resulting config:\n{pformat(_raw_data)}')
-        return _munchify(_raw_data)
+        return PyyaConfig(_munchify(_raw_data))
     except Exception as e:
         err_msg = f'Failed parsing config file: {e!r}'
         logger.error(err_msg)

pyya/__main__.py

@@ -0,0 +1,41 @@
+import argparse
+import logging
+import sys
+
+from pyya import PyyaError, init_config, logger
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description='stub generator for pyya')
+    parser.add_argument(
+        '-i', '--input', default='default.config.yaml', help='path to YAML file from which to generate stub file'
+    )
+    parser.add_argument('-o', '--output', default='config.pyi', help='path to resulting stub pyi file')
+    parser.add_argument('--var-name', default='config', help='variable name to refer to config object')
+    parser.add_argument('--to-snake', action='store_true', help='convert config section names to snake case')
+    parser.add_argument('--add-prefix', action='store_true', help='add underscore prefix to Python keywords')
+    parser.add_argument('--debug', action='store_true', help='print debug messages')
+    args = parser.parse_args()
+    logger.setLevel(logging.INFO)
+    if args.debug:
+        logger.setLevel(logging.DEBUG)
+    try:
+        init_config(
+            args.output,
+            args.input,
+            convert_keys_to_snake_case=args.to_snake,
+            add_underscore_prefix_to_keywords=args.add_prefix,
+            _generate_stub=True,
+            _stub_variable_name=args.var_name,
+        )
+    except PyyaError:
+        parser.print_usage()
+        sys.exit(2)
+    except Exception as e:
+        print(repr(e))
+        parser.print_usage()
+        sys.exit(2)
+
+
+if __name__ == '__main__':
+    main()