Version 3.2.0 - Stubber Update (#3)

Version 3.2.0 - Stubber Update

### Added

- Stub generators from descriptor config files where you structure out your
  config file and give each value the Python type you expect the config to
  yield in order to generate type-hinting stub-classes that match the structure
  of your config file(s).
- CLI commands for running the stub generation: `alviss-stubber`
- CLI commands for running the config rendering: `alviss-render`
- A bunch of Alviss specific Error Exceptions that are raised e.g.
  when files aren't found or when Fidelius is required but isn't installed

### Changed

- The rendering of static single file configs from Alviss config files and
  expressions has now been moved into its own sub-module with a standard API

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2024-04-22
+
+### Added
+
+- Stub generators from descriptor config files where you structure out your 
+  config file and give each value the Python type you expect the config to
+  yield in order to generate type-hinting stub-classes that match the structure 
+  of your config file(s).
+- CLI commands for running the stub generation: `alviss-stubber`
+- CLI commands for running the config rendering: `alviss-render`
+- A bunch of Alviss specific Error Exceptions that are raised e.g. 
+  when files aren't found or when Fidelius is required but isn't installed
+
+### Changed
+
+- The rendering of static single file configs from Alviss config files and 
+  expressions has now been moved into its own sub-module with a standard API  
+
+
 ## [3.1.0] - 2024-04-12
 
 ### Added

alviss/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '3.1.0'
+__version__ = '3.2.0'
 
 __author__ = 'Thordur Matthiasson <[email protected]>'
 __license__ = 'MIT License'

alviss/cli/render/main.py

@@ -0,0 +1,66 @@
+import argparse
+
+from alviss import __version__ as version
+from alviss.renderers import SimpleStaticRenderer
+from alviss.structs.errors import *
+
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Renders a single static config from an Alviss formatted file and '
+                                                 'its extends, includes and other expressions.',
+                                     epilog=f'Alviss version {version}')
+
+    parser.add_argument('file', help='The Alviss formatted config file to read, parse and render')
+    parser.add_argument('-o', '--output', help='File to write the results to (otherwise its just printed to stdout)',
+                        default='', nargs='?')
+    parser.add_argument('-f', '--force-overwrite', help='Overwrite existing output file if it exists',
+                        action='store_true')
+
+    loudness_group = parser.add_mutually_exclusive_group()
+    loudness_group.add_argument('-s', '--silent', action='store_true',
+                                help='Only outputs the resulting rendered config (and errors print to stderr)')
+    loudness_group.add_argument('-v', '--verbose', action="store_true",
+                                help='Spits out DEBUG level logs')
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+
+    if not args.silent:
+        print(f'Reading and parsing file: {args.file}...')
+
+    try:
+        if args.output:
+            if not args.silent:
+                print(f'Writing output to: {args.output}...')
+
+            SimpleStaticRenderer().render_static_config_to_file(input_file=args.file,
+                                                                output_file=args.output,
+                                                                overwrite_existing=args.force_overwrite)
+
+        else:
+            if not args.silent:
+                print(f'Printing results:')
+                print(f'==================================================')
+            print(SimpleStaticRenderer().render_static_config_from_file(args.file))
+
+            if not args.silent:
+                print(f'==================================================')
+
+        if not args.silent:
+            print(f'Done!')
+
+    except AlvissError as e:
+        if not args.silent:
+            print(f'An error occurred: {e!r}')
+        else:
+            print(f'An error occurred: {e!r}', file=sys.stderr)
+        sys.exit(3)
+
+
+if __name__ == '__main__':
+    main()

alviss/cli/stubber/main.py

@@ -0,0 +1,62 @@
+import argparse
+
+from alviss import __version__ as version
+from alviss import stubber
+from alviss.structs.errors import *
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generates Python dataclass stubs based on the given alviss type descriptor file.',
+                                     epilog=f'Alviss version {version}')
+
+    parser.add_argument('file', help='The Alviss config type descriptor file to generate strubs from.')
+    parser.add_argument('-o', '--output', help='File to write the generated stub code to (otherwise its just printed to stdout)',
+                        default='', nargs='?')
+    parser.add_argument('-f', '--force-overwrite', help='Overwrite existing output file if it exists', action='store_true')
+
+    loudness_group = parser.add_mutually_exclusive_group()
+    loudness_group.add_argument('-s', '--silent', action='store_true',
+                                help='Only outputs the resulting rendered code (and errors print to stderr)')
+    loudness_group.add_argument('-v', '--verbose', action="store_true",
+                                help='Spits out DEBUG level logs')
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+
+    if not args.silent:
+        print(f'Reading and stubbing file: {args.file}...')
+
+    try:
+        if args.output:
+            if not args.silent:
+                print(f'Writing output to: {args.output}...')
+
+            stubber.SimpleStubMaker().render_stub_classes_to_file(input_file=args.file,
+                                                                  output_file=args.output,
+                                                                  overwrite_existing=args.force_overwrite)
+        else:
+            if not args.silent:
+                print(f'Printing results:')
+                print(f'==================================================')
+            print(stubber.SimpleStubMaker().render_stub_classes_from_descriptor_file(args.file))
+
+            if not args.silent:
+                print(f'==================================================')
+
+        if not args.silent:
+            print(f'Done!')
+
+    except AlvissError as e:
+        if not args.silent:
+            print(f'An error occurred: {e!r}')
+        else:
+            print(f'An error occurred: {e!r}', file=sys.stderr)
+        sys.exit(3)
+
+
+if __name__ == '__main__':
+    main()

alviss/loaders/autoloader.py

@@ -25,7 +25,7 @@ def guess_loader_class(file_name: str) -> Type[IAlvissLoader]:
     ext = os.path.splitext(file_name)[-1]
     loader = _EXTENSION_LOADER_MAP.get(ext, None)
     if not loader:
-        raise NotImplementedError(f'dont know how to autoload file extension {ext}')
+        raise AlvissUnknownFileTypeError(f'Dont know how to autoload file extension {ext}', file_name=file_name)
     return loader
 
 

alviss/loaders/base.py

@@ -60,7 +60,7 @@ def _find_fidelius_mode(self):
                 import fidelius
             except ImportError:
                 log.error('ALVISS_FIDELIUS_MODE is ENABLED but fidelius is not installed')
-                raise
+                raise AlvissFideliusNotInstalledError('ALVISS_FIDELIUS_MODE is ENABLED but fidelius is not installed')
 
     @property
     def data(self) -> Dict:
@@ -82,6 +82,9 @@ def load_file(self,
 
         self._file_name = os.path.basename(file_name)
         self._file_path = os.path.dirname(os.path.abspath(file_name))
+        if not os.path.exists(file_name):
+            raise AlvissFileNotFoundError('File not found', file_name=file_name)
+
         with open(file_name, 'r', encoding=encoding) as fin:
             self.load_raw(fin.read(), no_resolve=no_resolve, no_extend=no_extend,
                           no_includes=no_includes, no_env_load=no_env_load, no_fidelius=no_fidelius)
@@ -91,8 +94,11 @@ def _extend(self):
             for inc_file, location in self._extends:
                 extended = self.__class__()
 
-                extended.load_file(os.path.join(self._file_path, inc_file),
-                                   no_resolve=True, no_env_load=self._skip_env_loading, no_fidelius=True)
+                ext_file = os.path.join(self._file_path, inc_file)
+                if not os.path.exists(ext_file):
+                    raise AlvissFileNotFoundError('File to extend not found', file_name=ext_file)
+
+                extended.load_file(ext_file, no_resolve=True, no_env_load=self._skip_env_loading, no_fidelius=True)
 
                 old_data = self._data
                 old_unresolved = self._unresolved
@@ -118,8 +124,11 @@ def _includes(self):
         if self._include:
             for inc_file, location in self._include:
                 inc_loader = self.__class__()
-                inc_loader.load_file(os.path.join(self._file_path, inc_file),
-                                     no_resolve=True, no_env_load=self._skip_env_loading, no_fidelius=True)
+                full_file = os.path.join(self._file_path, inc_file)
+                if not os.path.exists(full_file):
+                    raise AlvissFileNotFoundError('File to include not found', file_name=full_file)
+
+                inc_loader.load_file(full_file, no_resolve=True, no_env_load=self._skip_env_loading, no_fidelius=True)
                 new_data = {}
                 new_unresolved = {}
                 if location:
@@ -160,7 +169,7 @@ def _resolve(self):
             if required_list:
                 for location, value in required_list:
                     log.error(f'Required variable config value is unresolved: {location}, {value}')
-                raise ValueError(f'Required variable config values were unresolved: {required_list!r}')
+                raise AlvissSyntaxError(f'Required variable config values were unresolved: {required_list!r}')
 
     def _fetch_fidelius(self):
         if self._fidelius_keys:
@@ -171,17 +180,17 @@ def _fetch_fidelius(self):
                 if self.get_fidelius_mode() == FideliusMode.ON_DEMAND:
                     for path_tuple, value in self._fidelius_keys.items():
                         log.error(f'Fidelius tag ({path_tuple}, {value}) found but Fidelius is not installed (ALVISS_FIDELIUS_MODE=ON_DEMAND)')
-                raise
+                raise AlvissFideliusNotInstalledError(f'Fidelius tags found but Fidelius is not installed (ALVISS_FIDELIUS_MODE=ON_DEMAND)')
 
             app_var = iters.nested_get(self.data, ('app', 'slug'), iters.nested_get(self.data, ('app', 'module_name')))
             if not app_var:
-                raise ValueError('unable to resolve fidelius keys without app.slug or app.module_name')
+                raise AlvissFideliusSyntaxError('unable to resolve fidelius keys without app.slug or app.module_name')
             group_var = iters.nested_get(self.data, ('app', 'group'))
             if not group_var:
-                raise ValueError('unable to resolve fidelius keys without app.group')
+                raise AlvissFideliusSyntaxError('unable to resolve fidelius keys without app.group')
             env_var = iters.nested_get(self.data, ('app', 'env'))
             if not env_var:
-                raise ValueError('unable to resolve fidelius keys without app.env')
+                raise AlvissFideliusSyntaxError('unable to resolve fidelius keys without app.env')
 
             fidcls = FideliusFactory.get_class('mock' if self.get_fidelius_mode() == FideliusMode.MOCK else 'paramstore')
 
@@ -394,7 +403,7 @@ def _special_key_fidelius(self, value: Dict[str, Any], path: List[str]):
                     import fidelius
                 except ImportError:
                     log.error('ALVISS_FIDELIUS_MODE is ENABLED but fidelius is not installed')
-                    raise
+                    raise AlvissFideliusNotInstalledError('ALVISS_FIDELIUS_MODE is ENABLED but fidelius is not installed')
 
         if 'kwargs' in value:
             if not isinstance(value['kwargs'], dict):

alviss/renderers/__init__.py

@@ -0,0 +1 @@
+from .static import *

alviss/renderers/static/__init__.py

@@ -0,0 +1,2 @@
+from .interface import *
+from ._simple import *

alviss/renderers/static/_simple.py

@@ -0,0 +1,34 @@
+__all__ = [
+    'SimpleStaticRenderer',
+]
+
+from .interface import *
+from alviss import quickloader
+from alviss.structs.errors import *
+
+import os
+import pathlib
+
+import logging
+log = logging.getLogger(__file__)
+
+
+class SimpleStaticRenderer(IStaticRenderer):
+    def render_static_config_from_file(self, file: str) -> str:
+        return quickloader.render_load(file)
+
+    def render_static_config_to_file(self, input_file: str, output_file: str, overwrite_existing: bool = False):
+        out = pathlib.Path(output_file).absolute()
+        if out.exists() and not overwrite_existing:
+            raise AlvissFileAlreadyExistsError('Output file already exists', file_name=output_file)
+
+        results = self.render_static_config_from_file(input_file)
+
+        if not out.parent.exists():
+            log.debug(f'Creating output path: {out.parent}')
+            os.makedirs(out.parent, exist_ok=True)
+
+        with open(output_file, 'w') as fin:
+            fin.write(results)
+
+        return

alviss/renderers/static/interface.py

@@ -0,0 +1,21 @@
+__all__ = [
+    'IStaticRenderer',
+]
+import abc
+
+
+class IStaticRenderer(abc.ABC):
+    @abc.abstractmethod
+    def render_static_config_from_file(self, file: str) -> str:
+        """Renders a single static configuration file from an Alviss formatted
+        file, including all included and/or extended files and resolving all
+        expressions, variables and internal references and such.
+        """
+        pass
+
+    @abc.abstractmethod
+    def render_static_config_to_file(self, input_file: str, output_file: str, overwrite_existing: bool = False):
+        """Writer the results of the `render_static_config_from_file` call to
+        the given output file.
+        """
+        pass

alviss/structs/_base.py

@@ -1 +1,2 @@
 from ccptools.structs import *
+from .errors import *

alviss/structs/cfgstub.py

@@ -0,0 +1,12 @@
+__all__ = [
+    '_BaseCfgStub',
+]
+from ._base import *
+
+
+class _BaseCfgStub(Protocol):
+    """This is the base Protocol for all generated Stubs
+
+    """
+    def __getattr__(self, item) -> Union[Any, Empty]:
+        ...