Coverage for gws-app/gws/config/__init__.py: 100%

1"""Configuration loading. 

2 

3This package turns configuration sources (files or Python dicts) into a 

4validated ``gws.Config`` tree and builds the object tree (``gws.Root``) from it. 

5It also saves the configured root on disk and loads it back in the server 

6processes. 

7 

8Submodules: 

9 

10- ``gws.config.parser``: reads configuration files (``.cx``, ``.json``, 

11 ``.yaml``/``.yml``, ``.py``), converts them to plain dicts and validates them 

12 against the specs. Application configs are handled specially: the server time 

13 zone is set first, and projects are parsed separately, from the inline 

14 ``projects`` list, from ``projectPaths`` and from files in ``projectDirs``. 

15- ``gws.config.loader``: drives the whole process. It creates the specs, runs the 

16 parser, creates and initializes the root object, collects errors and warnings 

17 into a ``gws.ConfigResult`` and logs a report. It also saves the root 

18 (``gws.save_root``) and loads it back (``gws.load_root``), logging the user, 

19 time and memory used. 

20- ``gws.config.util``: helpers used by ``configure`` methods of objects to 

21 create common children (templates, models, finders) and to find providers, 

22 database providers and source layers. 

23 

24Errors do not stop the process. The parser and the loader collect them into a 

25``gws.ConfigContext`` as ``gws.ConfigErrorInfo`` objects, together with the 

26errors and warnings that objects report while being configured. The result 

27contains the root object (unless configuration failed or the manifest requires 

28a strict configuration), the parsed config and all errors and warnings. 

29 

30If no config path is given, the path is taken from the ``GWS_CONFIG`` 

31environment variable or one of the default paths ``/data/config.cx``, 

32``/data/config.json``, ``/data/config.yaml``, ``/data/config.py``. 

33 

34This ``__init__.py`` re-exports the main loader functions and the 

35``CONFIG_PATH_PATTERN`` used to find config files in directories. 

36 

37Example:: 

38 

39 import gws.config 

40 

41 cr = gws.config.configure(config_path='/data/config.cx') 

42 gws.config.log_report(cr) 

43 if cr.root: 

44 gws.config.save(cr.root) 

45 

46 # later, in a server process 

47 root = gws.config.load() 

48 

49Example:: 

50 

51 # parse only, without creating objects 

52 cr = gws.config.parse(config_path='/data/config.cx') 

53 for err in cr.errors: 

54 print(err.message, err.path, err.line) 

55""" 

56 

57from .loader import ( 

58 configure, 

59 initialize, 

60 parse, 

61 load, 

62 save, 

63 log_report, 

64) 

65from .parser import CONFIG_PATH_PATTERN 

66from . import loader, parser