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

1"""Spec generator: creates the specs from the Python sources. 

2 

3The generator collects the source files of the application and its plugins, 

4parses the Python sources into ``Type`` records, normalizes them and extracts 

5the types the server needs. It also generates the TypeScript API for the 

6client, collects the documentation strings and renders the configuration 

7references. 

8 

9Modules: 

10 

11- ``main``: entry points (``generate``, ``generate_and_write``) and JSON 

12 storage of the specs (``to_path``, ``from_path``). Sets up the chunks and 

13 runs the pipeline. 

14- ``base``: the ``Generator`` state object shared by all steps, a simple 

15 ``Data`` class and the generator logger. 

16- ``manifest``: reads ``MANIFEST.json`` files. 

17- ``parser``: parses Python modules with ``ast`` and creates types for 

18 classes, enums, properties, type aliases, constants, ``gws.ext`` 

19 declarations and command methods. 

20- ``normalizer``: resolves aliases, evaluates default expressions, 

21 synthesizes variant types and ``type`` properties for ``gws.ext`` classes 

22 and collects the inherited properties of classes. 

23- ``extractor``: selects the server types, starting from the application 

24 ``Config``, the application ``Object`` and all ``gws.ext`` types. 

25- ``typescript``: generates the TypeScript API (``gws.generated.ts``) for 

26 the client from the request, response and props classes and the API 

27 commands. 

28- ``strings``: collects documentation strings from docstrings and 

29 ``strings.ini`` files. 

30- ``configref``: renders the configuration reference in Markdown, in English 

31 and German. 

32- ``util``: file, JSON and ini helpers. 

33 

34Pipeline 

35======== 

36 

37``main`` creates a ``base.Generator`` and runs the steps in order: 

38 

391. Init: read ``VERSION`` and the manifest, create chunks for the system 

40 packages, the built-in plugins and the manifest plugins, and assign the 

41 source files of each chunk to file kinds. 

422. ``parser.parse``: add a type for each spec'able source construct to 

43 ``Generator.typeDict``; imports become entries in ``Generator.aliases``. 

443. ``normalizer.normalize``: resolve the aliases and finish the types. 

454. ``extractor.extract``: fill ``Generator.serverTypes``. 

465. ``typescript.create``, ``strings.collect`` and ``configref.create``. 

47 

48With ``debug``, the generator state is dumped as JSON after each step. 

49``generate_and_write`` writes ``specs.json``, ``gws.generated.ts``, 

50``configref.en.md`` and ``configref.de.md`` to the output directory. 

51 

52Example:: 

53 

54 import gws.spec.generator.main as generator_main 

55 

56 specs = generator_main.generate(manifest_path='/data/MANIFEST.json') 

57 generator_main.to_path('/tmp/specs.json', specs) 

58 

59 generator_main.generate_and_write(out_dir='/tmp/specs', manifest_path='/data/MANIFEST.json') 

60"""