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

1"""Core library. 

2 

3The lowest layer of GWS. It provides the basic types, the object tree, logging, constants and 

4general utilities that every other module depends on. Nothing in ``gws.core`` imports from 

5other GWS packages. 

6 

7Most of the package is not imported directly. The ``gws`` package (``gws/__init__.py``) is generated 

8from ``gws/__init__.pyinc``, which includes the ``*.pyinc`` fragments of this package (and of other 

9packages) verbatim, and it re-exports the plain modules under short names: ``gws.c``, ``gws.u``, 

10``gws.log``, ``gws.debug`` and ``gws.env``. 

11 

12Submodules: 

13 

14- ``_data.pyinc``: ``gws.Data``, the basic attribute container, which returns ``None`` for missing attributes. 

15- ``_basic.pyinc``: ``gws.Enum``, common type aliases (``Extent``, ``Point``, ``Duration`` and others), 

16 the base ``Config`` and ``Props`` classes, command ``Request`` and ``Response`` types, 

17 ``AttributeType`` and ``GeometryType``. 

18- ``_access.pyinc``: access modes (``gws.Access``), ACL types and the ``ConfigWithAccess`` base config. 

19- ``_error.pyinc``: the ``gws.Error`` exception hierarchy. 

20- ``_tree.pyinc``: the object tree interfaces ``gws.Object``, ``gws.Node`` and ``gws.Root``. 

21- ``tree_impl``: the implementation of the ``Node`` and ``Root`` methods. 

22- ``util``: general helpers for data structures, type conversion, files, locks and caching (``gws.u``). 

23- ``const``: system directories, role names and other constants (``gws.c``). 

24- ``env``: environment variables that override configuration values (``gws.env``). 

25- ``log``: a minimal logger writing to stdout (``gws.log``). 

26- ``debug``: debugging and profiling helpers (``gws.debug``). 

27 

28Object tree: 

29 

30All configurable objects are ``gws.Node`` instances in a tree under a ``gws.Root``. 

31A node is created with ``Root.create`` (or ``Node.create_child``), which looks up the class in the 

32spec runtime, assigns a uid and calls ``Node.initialize``. Initialization stores the config, computes 

33the permissions from ``access`` and ``permissions``, and then runs ``pre_configure`` and ``configure``. 

34These hooks are invoked for every class in the MRO that defines them, base classes first, 

35so a ``configure`` method does not need to call ``super().configure()``. 

36If initialization fails, the error is recorded in ``Root.configErrors`` and the node is not created. 

37After the whole tree is built, ``Root.post_initialize`` runs ``post_configure`` on all nodes, 

38in the reverse order of creation. ``Root.activate`` calls ``activate`` on all nodes; it is run 

39after the configuration has been loaded. 

40 

41The ``.pyinc`` fragments and ``tree_impl`` are linked at import time: ``gws/__init__.py`` sets the 

42``Access``, ``Error``, ``Data``, ``Props`` and ``Object`` placeholders in ``tree_impl``, 

43and replaces ``util.is_data_object`` and ``util.to_data_object`` with the real implementations. 

44 

45Example:: 

46 

47 import gws 

48 

49 class Object(gws.Node): 

50 def configure(self): 

51 self.title = self.cfg('title', default='') 

52 self.layers = self.create_children(gws.ext.object.layer, self.cfg('layers')) 

53 

54 def props(self, user): 

55 return gws.Props(title=self.title, layers=self.layers) 

56 

57Example:: 

58 

59 import gws 

60 

61 d = gws.Data(a=1) 

62 d.b # None 

63 gws.u.get({'a': {'b': [10, 20]}}, 'a.b.1') # 20 

64 gws.u.to_uid('Strasse 1') # 'strasse_1' 

65 

66 with gws.u.server_lock('my_task', timeout=5): 

67 gws.log.info('lock acquired') 

68"""