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

1"""Specs for the GWS app. 

2 

3Specs are a set of metadata that describe GWS configuration and runtime objects. 

4Specs are generated from the source code before the app is run or a build step is performed. 

5 

6The Specs support module consists of two main components: 

7 

8- Generator (`gws.spec.generator.main`) that creates Specs from sources 

9- Runtime (`gws.spec.runtime`) that loads Specs and provides methods to validate configuration or request objects 

10 

11Generated Specs are also used by the Client builder and documentation generators. 

12 

13Spec Data 

14========= 

15 

16`gws.spec.core.SpecData` is the central data object produced by the Generator and consumed by the Runtime. 

17 

18It contains the following fields: 

19 

20- `meta`: Build-time metadata. Includes the application manifest, manifest path, and generator version. 

21 

22- `chunks`: Source-code "chunks" (collections of related files) that make up the application. 

23 

24- `serverTypes`: All types the server needs at runtime — configuration types, request/response types, and command descriptors. 

25 

26- `strings`: Localised documentation strings keyed first by language code (e.g. ``'en'``, ``'de'``) and then by type uid. 

27 

28Server Types 

29------------ 

30 

31Each entry in `serverTypes` is a `gws.spec.core.Type` instance. The `c` field (a `gws.spec.core.TypeKind` string) 

32determines what kind of type it represents and which other fields are populated. 

33 

34It contains the following fields (not all are populated for every type; see `c`): 

35 

36- `c`: Type kind (see below). 

37- `uid`: Unique string identifier, used as key throughout the spec. 

38- `name`: Short name (e.g. class name, property name). 

39- `ident`: Fully qualified source-code identifier, used in docs. 

40- `constValue`: Value for ``CONSTANT`` types. 

41- `defaultExpression`: Source-expression string for computed defaults. 

42- `defaultValue`: Literal default value. 

43- `doc`: Inline docstring from the source. 

44- `enumDocs`: For ``ENUM`` — ``{member_name → docstring}`` dict. 

45- `enumValues`: For ``ENUM`` — ``{member_name → value}`` dict. 

46- `extName`: ``gws.ext`` name, set only for extension types and commands. 

47- `hasDefault`: ``True`` when a default exists. 

48- `literalValues`: For ``LITERAL`` — list of allowed literal values. 

49- `modName` / `modPath`: Module that defines this type. 

50- `pos`: Source file position (``file:line``). 

51- `tArg`: For ``METHOD`` — uid of the last (request) argument. 

52- `tArgs`: For ``METHOD`` — uids of all arguments in order. 

53- `tItem`: For ``LIST``, ``SET``, ``DICT`` — uid of the element type. 

54- `tItems`: For ``UNION``, ``TUPLE`` — uids of member types. 

55- `tKey`: For ``DICT`` — uid of the key type. 

56- `tMembers`: For ``VARIANT`` — ``{tag → uid}`` map of discriminated members. 

57- `tModule`: uid of the module type that contains this type. 

58- `tOwner`: For ``PROPERTY`` — uid of the owning class. 

59- `tProperties`: For ``CLASS`` — ``{name → uid}`` map of property types. 

60- `tReturn`: For ``METHOD`` — uid of the return type. 

61- `tSupers`: For ``CLASS`` — uids of base classes. 

62- `tTarget`: For ``TYPE``, ``EXT`` — uid of the aliased/target type. 

63- `tValue`: For ``PROPERTY`` — uid of the property's value type. 

64 

65The `gws.spec.core.TypeKind` (``c``) field can be one of the following values defined in `gws.spec.core.c`: 

66 

67- ``ATOM``: Built-in primitive: ``any``, ``bool``, ``bytes``, ``float``, ``int``, ``str``. 

68- ``CALLABLE``: Untyped callable argument. 

69- ``CLASS``: User-defined data class (config, props, request, response objects). Uses ``tProperties``, ``tSupers``. 

70- ``COMMAND``: A ``gws.ext.command.*`` endpoint. Uses ``tArg``, ``tOwner``, ``extName``. 

71- ``CONSTANT``: Named constant; value stored in ``constValue``. 

72- ``DICT``: Generic ``dict[K, V]``. Uses ``tKey``, ``tItem``. 

73- ``ENUM``: Python ``Enum`` subclass. Uses ``enumValues``, ``enumDocs``. 

74- ``EXPR``: Compile-time expression; not validated at runtime. 

75- ``EXT``: A ``gws.ext.*`` alias pointing to an extension type. Uses ``tTarget``, ``extName``. 

76- ``FUNCTION``: Stand-alone callable. Uses ``tArgs``, ``tReturn``. 

77- ``LIST``: Generic ``list[T]``. Uses ``tItem``. 

78- ``LITERAL``: ``Literal[v1, v2, …]``. Uses ``literalValues``. 

79- ``METHOD``: Class method / command handler. Uses ``tArg``, ``tArgs``, ``tReturn``, ``tOwner``. 

80- ``MODULE``: Python module node; groups types by source file. 

81- ``NONE``: The ``None`` / ``NoneType`` singleton. 

82- ``OPTIONAL``: ``Optional[T]`` (i.e. ``T | None``). Uses ``tItem``. 

83- ``PROPERTY``: A single property slot inside a ``CLASS``. Uses ``tOwner``, ``tValue``. 

84- ``SET``: Generic ``set[T]``. Uses ``tItem``. 

85- ``TUPLE``: Generic ``tuple[T, …]``. Uses ``tItems``. 

86- ``TYPE``: Type alias (``TypeAlias``). Uses ``tTarget``. 

87- ``UNDEFINED``: Placeholder for a type that could not be resolved. 

88- ``UNION``: ``Union[T1, T2, …]`` (untagged). Uses ``tItems``. 

89- ``VARIANT``: Tagged union discriminated by a ``type`` property. Uses ``tMembers``. 

90 

91"""