diff options
author | Eli Schwartz <eschwartz@archlinux.org> | 2023-08-16 12:59:58 -0400 |
---|---|---|
committer | Eli Schwartz <eschwartz@archlinux.org> | 2023-08-18 11:16:15 -0400 |
commit | 184277bb4abbc0aa194ac02f592192d91fb109e1 (patch) | |
tree | ed2e59e74030bd8d59445c29e620ecae1b0b921b /docs/refman | |
parent | 2edcbb452ee30bb173518e51f28f7c192dc070e3 (diff) | |
download | meson-184277bb4abbc0aa194ac02f592192d91fb109e1.zip meson-184277bb4abbc0aa194ac02f592192d91fb109e1.tar.gz meson-184277bb4abbc0aa194ac02f592192d91fb109e1.tar.bz2 |
docs: use future annotations for genrefman types in typing_extensions
And in fact *use* typing_extensions, which is sometimes the only way to
get access to TypedDict.
Mostly, reindent almost but not quite an entire file to only define
annotation classes under TYPE_CHECKING.
Diffstat (limited to 'docs/refman')
-rw-r--r-- | docs/refman/generatorjson.py | 1 | ||||
-rw-r--r-- | docs/refman/jsonschema.py | 137 |
2 files changed, 71 insertions, 67 deletions
diff --git a/docs/refman/generatorjson.py b/docs/refman/generatorjson.py index d41cb71..a2edc18 100644 --- a/docs/refman/generatorjson.py +++ b/docs/refman/generatorjson.py @@ -1,5 +1,6 @@ # SPDX-License-Identifer: Apache-2.0 # Copyright 2021 The Meson development team +from __future__ import annotations from pathlib import Path import json diff --git a/docs/refman/jsonschema.py b/docs/refman/jsonschema.py index e64bf06..283d3a2 100644 --- a/docs/refman/jsonschema.py +++ b/docs/refman/jsonschema.py @@ -10,79 +10,82 @@ import typing as T VERSION_MAJOR = 1 # Changes here indicate breaking format changes (changes to existing keys) VERSION_MINOR = 1 # Changes here indicate non-breaking changes (only new keys are added to the existing structure) -class BaseObject(T.TypedDict): - ''' - Base object for most dicts in the JSON doc. +if T.TYPE_CHECKING: + from typing_extensions import TypedDict - All objects inheriting from BaseObject will support - the keys specified here: - ''' - name: str - description: str - since: T.Optional[str] - deprecated: T.Optional[str] - notes: T.List[str] - warnings: T.List[str] + class BaseObject(TypedDict): + ''' + Base object for most dicts in the JSON doc. -class Type(T.TypedDict): - obj: str # References an object from `root.objects` - holds: T.Sequence[object] # Mypy does not support recursive dicts, but this should be T.List[Type]... + All objects inheriting from BaseObject will support + the keys specified here: + ''' + name: str + description: str + since: T.Optional[str] + deprecated: T.Optional[str] + notes: T.List[str] + warnings: T.List[str] -class Argument(BaseObject): - ''' - Object that represents any type of a single function or method argument. - ''' - type: T.List[Type] # A non-empty list of types that are supported. - type_str: str # Formatted version of `type`. Is guaranteed to not contain any whitespaces. - required: bool - default: T.Optional[str] - min_varargs: T.Optional[int] # Only relevant for varargs, must be `null` for all other types of arguments - max_varargs: T.Optional[int] # Only relevant for varargs, must be `null` for all other types of arguments + class Type(TypedDict): + obj: str # References an object from `root.objects` + holds: T.Sequence[object] # Mypy does not support recursive dicts, but this should be T.List[Type]... -class Function(BaseObject): - ''' - Represents a function or method. - ''' - returns: T.List[Type] # A non-empty list of types that are supported. - returns_str: str # Formatted version of `returns`. Is guaranteed to not contain any whitespaces. - example: T.Optional[str] - posargs: T.Dict[str, Argument] - optargs: T.Dict[str, Argument] - kwargs: T.Dict[str, Argument] - varargs: T.Optional[Argument] - arg_flattening: bool + class Argument(BaseObject): + ''' + Object that represents any type of a single function or method argument. + ''' + type: T.List[Type] # A non-empty list of types that are supported. + type_str: str # Formatted version of `type`. Is guaranteed to not contain any whitespaces. + required: bool + default: T.Optional[str] + min_varargs: T.Optional[int] # Only relevant for varargs, must be `null` for all other types of arguments + max_varargs: T.Optional[int] # Only relevant for varargs, must be `null` for all other types of arguments -class Object(BaseObject): - ''' - Represents all types of Meson objects. The specific object type is stored in the `object_type` field. - ''' - example: T.Optional[str] - object_type: str # Defines the object type: Must be one of: ELEMENTARY, BUILTIN, MODULE, RETURNED - methods: T.Dict[str, Function] - is_container: bool - extends: T.Optional[str] - returned_by: T.List[str] - extended_by: T.List[str] - defined_by_module: T.Optional[str] + class Function(BaseObject): + ''' + Represents a function or method. + ''' + returns: T.List[Type] # A non-empty list of types that are supported. + returns_str: str # Formatted version of `returns`. Is guaranteed to not contain any whitespaces. + example: T.Optional[str] + posargs: T.Dict[str, Argument] + optargs: T.Dict[str, Argument] + kwargs: T.Dict[str, Argument] + varargs: T.Optional[Argument] + arg_flattening: bool -class ObjectsByType(T.TypedDict): - ''' - References to other objects are stored here for ease of navigation / filtering - ''' - elementary: T.List[str] - builtins: T.List[str] - returned: T.List[str] - modules: T.Dict[str, T.List[str]] + class Object(BaseObject): + ''' + Represents all types of Meson objects. The specific object type is stored in the `object_type` field. + ''' + example: T.Optional[str] + object_type: str # Defines the object type: Must be one of: ELEMENTARY, BUILTIN, MODULE, RETURNED + methods: T.Dict[str, Function] + is_container: bool + extends: T.Optional[str] + returned_by: T.List[str] + extended_by: T.List[str] + defined_by_module: T.Optional[str] + class ObjectsByType(TypedDict): + ''' + References to other objects are stored here for ease of navigation / filtering + ''' + elementary: T.List[str] + builtins: T.List[str] + returned: T.List[str] + modules: T.Dict[str, T.List[str]] -class Root(T.TypedDict): - ''' - The root object of the JSON reference manual - ''' - version_major: int # See the description above for - version_minor: int # VERSION_MAJOR and VERSION_MINOR - meson_version: str - functions: T.Dict[str, Function] # A mapping of <name> to a `Function` object for *all* Meson functions - objects: T.Dict[str, Object] # A mapping of <name> to a `Object` object for *all* Meson objects (including modules, elementary, etc.) - objects_by_type: ObjectsByType + + class Root(TypedDict): + ''' + The root object of the JSON reference manual + ''' + version_major: int # See the description above for + version_minor: int # VERSION_MAJOR and VERSION_MINOR + meson_version: str + functions: T.Dict[str, Function] # A mapping of <name> to a `Function` object for *all* Meson functions + objects: T.Dict[str, Object] # A mapping of <name> to a `Object` object for *all* Meson objects (including modules, elementary, etc.) + objects_by_type: ObjectsByType |