Debian Codegraph @

subprojects/meson-docs/docs/refman/loaderyaml.py

raw
1 # SPDX-License-Identifier: Apache-2.0
2 # Copyright 2021 The Meson development team
3
4 from .loaderbase import LoaderBase
5 from .model import (
6 Type,
7 PosArg,
8 VarArgs,
9 Kwarg,
10 Function,
11 Method,
12 ObjectType,
13 Object,
14 ReferenceManual,
15 )
16
17 from mesonbuild import mlog
18 from mesonbuild import mesonlib
19
20 from pathlib import Path
21 import typing as T
22
23 class Template:
24 d_feature_check: T.Dict[str, T.Any] = {}
25 s_posarg: T.Dict[str, T.Any] = {}
26 s_varargs: T.Dict[str, T.Any] = {}
27 s_kwarg: T.Dict[str, T.Any] = {}
28 s_function: T.Dict[str, T.Any] = {}
29 s_object: T.Dict[str, T.Any] = {}
30
31 class StrictTemplate(Template):
32 def __init__(self) -> None:
33 from strictyaml import Map, MapPattern, Optional, Str, Seq, Int, Bool, EmptyList, OrValidator # type: ignore[import-untyped]
34
35 d_named_object = {
36 'name': Str(),
37 'description': Str(),
38 }
39
40 d_feture_check = {
41 Optional('since', default=''): Str(),
42 Optional('deprecated', default=''): Str(),
43 }
44
45 self.s_posarg = Map({
46 **d_feture_check,
47 'description': Str(),
48 'type': Str(),
49 Optional('default', default=''): Str(),
50 })
51
52 self.s_varargs = Map({
53 **d_named_object, **d_feture_check,
54 'type': Str(),
55 Optional('min_varargs', default=-1): Int(),
56 Optional('max_varargs', default=-1): Int(),
57 })
58
59 self.s_kwarg = Map({
60 **d_feture_check,
61 'type': Str(),
62 'description': Str(),
63 Optional('required', default=False): Bool(),
64 Optional('default', default=''): Str(),
65 })
66
67 self.s_function = Map({
68 **d_named_object, **d_feture_check,
69 'returns': Str(),
70 Optional('notes', default=[]): OrValidator(Seq(Str()), EmptyList()),
71 Optional('warnings', default=[]): OrValidator(Seq(Str()), EmptyList()),
72 Optional('example', default=''): Str(),
73 Optional('posargs'): MapPattern(Str(), self.s_posarg),
74 Optional('optargs'): MapPattern(Str(), self.s_posarg),
75 Optional('varargs'): self.s_varargs,
76 Optional('posargs_inherit', default=''): Str(),
77 Optional('optargs_inherit', default=''): Str(),
78 Optional('varargs_inherit', default=''): Str(),
79 Optional('kwargs'): MapPattern(Str(), self.s_kwarg),
80 Optional('kwargs_inherit', default=[]): OrValidator(OrValidator(Seq(Str()), EmptyList()), Str()),
81 Optional('arg_flattening', default=True): Bool(),
82 })
83
84 self.s_object = Map({
85 **d_named_object, **d_feture_check,
86 'long_name': Str(),
87 Optional('extends', default=''): Str(),
88 Optional('notes', default=[]): OrValidator(Seq(Str()), EmptyList()),
89 Optional('warnings', default=[]): OrValidator(Seq(Str()), EmptyList()),
90 Optional('example', default=''): Str(),
91 Optional('methods'): Seq(self.s_function),
92 Optional('is_container', default=False): Bool()
93 })
94
95 class FastTemplate(Template):
96 d_feature_check: T.Dict[str, T.Any] = {
97 'since': '',
98 'deprecated': '',
99 }
100
101 s_posarg = {
102 **d_feature_check,
103 'default': '',
104 }
105
106 s_varargs: T.Dict[str, T.Any] = {
107 **d_feature_check,
108 'min_varargs': -1,
109 'max_varargs': -1,
110 }
111
112 s_kwarg = {
113 **d_feature_check,
114 'required': False,
115 'default': '',
116 }
117
118 s_function = {
119 **d_feature_check,
120 'notes': [],
121 'warnings': [],
122 'example': '',
123 'posargs': {},
124 'optargs': {},
125 'varargs': None,
126 'posargs_inherit': '',
127 'optargs_inherit': '',
128 'varargs_inherit': '',
129 'kwargs': {},
130 'kwargs_inherit': [],
131 'arg_flattening': True,
132 }
133
134 s_object = {
135 **d_feature_check,
136 'extends': '',
137 'notes': [],
138 'warnings': [],
139 'example': '',
140 'methods': [],
141 'is_container': False,
142 }
143
144 class LoaderYAML(LoaderBase):
145 def __init__(self, yaml_dir: Path, strict: bool=True) -> None:
146 super().__init__()
147 self.yaml_dir = yaml_dir
148 self.func_dir = self.yaml_dir / 'functions'
149 self.elem_dir = self.yaml_dir / 'elementary'
150 self.objs_dir = self.yaml_dir / 'objects'
151 self.builtin_dir = self.yaml_dir / 'builtins'
152 self.modules_dir = self.yaml_dir / 'modules'
153 self.strict = strict
154
155 template: Template
156 if self.strict:
157 import strictyaml
158 def loader(file: str, template: T.Any, label: str) -> T.Dict:
159 r: T.Dict = strictyaml.load(file, template, label=label).data
160 return r
161
162 self._load = loader
163 template = StrictTemplate()
164 else:
165 import yaml
166 from yaml import CLoader
167 def loader(file: str, template: T.Any, label: str) -> T.Dict:
168 return {**template, **yaml.load(file, Loader=CLoader)}
169
170 self._load = loader
171 template = FastTemplate()
172
173 self.template = template
174
175 def _fix_default(self, v: T.Dict) -> None:
176 if v["default"] is False:
177 v["default"] = "false"
178 elif v["default"] is True:
179 v["default"] = "true"
180 else:
181 v["default"] = str(v["default"])
182
183 def _process_function_base(self, raw: T.Dict, obj: T.Optional[Object] = None) -> Function:
184 # Handle arguments
185 posargs = raw.pop('posargs', {})
186 optargs = raw.pop('optargs', {})
187 varargs = raw.pop('varargs', None)
188 kwargs = raw.pop('kwargs', {})
189
190 # Fix kwargs_inherit
191 if isinstance(raw['kwargs_inherit'], str):
192 raw['kwargs_inherit'] = [raw['kwargs_inherit']]
193
194 # Parse args
195 posargs_mapped: T.List[PosArg] = []
196 optargs_mapped: T.List[PosArg] = []
197 varargs_mapped: T.Optional[VarArgs] = None
198 kwargs_mapped: T.Dict[str, Kwarg] = {}
199
200 for k, v in posargs.items():
201 if not self.strict:
202 v = {**self.template.s_posarg, **v}
203 self._fix_default(v)
204 v['type'] = Type(v['type'])
205 posargs_mapped += [PosArg(name=k, **v)]
206
207 for k, v in optargs.items():
208 if not self.strict:
209 v = {**self.template.s_posarg, **v}
210 self._fix_default(v)
211 v['type'] = Type(v['type'])
212 optargs_mapped += [PosArg(name=k, **v)]
213
214 for k, v in kwargs.items():
215 if not self.strict:
216 v = {**self.template.s_kwarg, **v}
217 self._fix_default(v)
218 v['type'] = Type(v['type'])
219 kwargs_mapped[k] = Kwarg(name=k, **v)
220
221 if varargs is not None:
222 if not self.strict:
223 varargs = {**self.template.s_varargs, **varargs}
224 varargs['type'] = Type(varargs['type'])
225 varargs_mapped = VarArgs(**varargs)
226
227 raw['returns'] = Type(raw['returns'])
228
229 # Build function object
230 if obj is not None:
231 return Method(
232 posargs=posargs_mapped,
233 optargs=optargs_mapped,
234 varargs=varargs_mapped,
235 kwargs=kwargs_mapped,
236 obj=obj,
237 **raw,
238 )
239 return Function(
240 posargs=posargs_mapped,
241 optargs=optargs_mapped,
242 varargs=varargs_mapped,
243 kwargs=kwargs_mapped,
244 **raw,
245 )
246
247 def _load_function(self, path: Path, obj: T.Optional[Object] = None) -> Function:
248 path_label = path.relative_to(self.yaml_dir).as_posix()
249 mlog.log('Loading', mlog.bold(path_label))
250 raw = self._load(self.read_file(path), self.template.s_function, label=path_label)
251 return self._process_function_base(raw)
252
253 def _load_object(self, obj_type: ObjectType, path: Path) -> Object:
254 path_label = path.relative_to(self.yaml_dir).as_posix()
255 mlog.log(f'Loading', mlog.bold(path_label))
256 raw = self._load(self.read_file(path), self.template.s_object, label=path_label)
257
258 def as_methods(mlist: T.List[Function]) -> T.List[Method]:
259 res: T.List[Method] = []
260 for i in mlist:
261 assert isinstance(i, Method)
262 res += [i]
263 return res
264
265 methods = raw.pop('methods', [])
266 obj = Object(methods=[], obj_type=obj_type, **raw)
267
268 newmethods = []
269 for x in methods:
270 if not self.strict:
271 x = {**self.template.s_function, **x}
272 newmethods += [self._process_function_base(x, obj)]
273 obj.methods = as_methods(newmethods)
274 return obj
275
276 def _load_module(self, path: Path) -> T.List[Object]:
277 assert path.is_dir()
278 module = self._load_object(ObjectType.MODULE, path / 'module.yaml')
279 objs = []
280 for p in path.iterdir():
281 if p.name == 'module.yaml':
282 continue
283 obj = self._load_object(ObjectType.RETURNED, p)
284 obj.defined_by_module = module
285 objs += [obj]
286 return [module, *objs]
287
288 def load_impl(self) -> ReferenceManual:
289 mlog.log('Loading YAML reference manual')
290 with mlog.nested():
291 manual = ReferenceManual(
292 functions=[self._load_function(x) for x in self.func_dir.iterdir()],
293 objects=mesonlib.listify([
294 [self._load_object(ObjectType.ELEMENTARY, x) for x in self.elem_dir.iterdir()],
295 [self._load_object(ObjectType.RETURNED, x) for x in self.objs_dir.iterdir()],
296 [self._load_object(ObjectType.BUILTIN, x) for x in self.builtin_dir.iterdir()],
297 [self._load_module(x) for x in self.modules_dir.iterdir()]
298 ], flatten=True)
299 )
300
301 if not self.strict:
302 mlog.warning('YAML reference manual loaded using the best-effort fastyaml loader. Results are not guaranteed to be stable or correct.')
303
304 return manual