Virtualization
/
meson
mirror of https://gitlab.com/qemu-project/meson.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

hotdoc module: add a bunch more type annotations

This commit is contained in:
Eli Schwartz 2023-08-03 15:41:06 -04:00
parent bf0494fcc0
commit 32e7ebc821
No known key found for this signature in database
GPG Key ID: CEB167EFB5722BD6
1 changed files with 73 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
mesonbuild/modules/hotdoc.py
View File

@ -18,11 +18,9 @@ from __future__ import annotations
import os, subprocess import os, subprocess
import typing as T import typing as T
from mesonbuild import mesonlib from . import ExtensionModule, ModuleReturnValue, ModuleInfo
from mesonbuild import mlog, build from .. import build, mesonlib, mlog
from mesonbuild.mesonlib import MesonException from ..build import CustomTarget, CustomTargetIndex
from . import ModuleReturnValue, ModuleInfo
from . import ExtensionModule
from ..dependencies import Dependency, InternalDependency from ..dependencies import Dependency, InternalDependency
from ..interpreterbase import ( from ..interpreterbase import (
InvalidArguments, noPosargs, noKwargs, typed_kwargs, FeatureDeprecated, InvalidArguments, noPosargs, noKwargs, typed_kwargs, FeatureDeprecated,
@ -30,10 +28,34 @@ from ..interpreterbase import (
) )
from ..interpreter.interpreterobjects import _CustomTargetHolder from ..interpreter.interpreterobjects import _CustomTargetHolder
from ..interpreter.type_checking import NoneType from ..interpreter.type_checking import NoneType
from ..mesonlib import File, MesonException
from ..programs import ExternalProgram from ..programs import ExternalProgram
if T.TYPE_CHECKING:
from typing_extensions import TypedDict
def ensure_list(value): from . import ModuleState
from ..environment import Environment
from ..interpreter import Interpreter
from ..interpreterbase import TYPE_kwargs, TYPE_var
_T = T.TypeVar('_T')
class GenerateDocKwargs(TypedDict):
sitemap: T.Union[str, File, CustomTarget, CustomTargetIndex]
index: T.Union[str, File, CustomTarget, CustomTargetIndex]
project_version: str
html_extra_theme: T.Optional[str]
include_paths: T.List[str]
dependencies: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]]
depends: T.List[T.Union[CustomTarget, CustomTargetIndex]]
gi_c_source_roots: T.List[str]
extra_assets: T.List[str]
extra_extension_paths: T.List[str]
subprojects: T.List['HotdocTarget']
install: bool
def ensure_list(value: T.Union[_T, T.List[_T]]) -> T.List[_T]:
if not isinstance(value, list): if not isinstance(value, list):
return [value] return [value]
return value return value
@ -41,7 +63,7 @@ def ensure_list(value):
MIN_HOTDOC_VERSION = '0.8.100' MIN_HOTDOC_VERSION = '0.8.100'
file_types = (str, mesonlib.File, build.CustomTarget, build.CustomTargetIndex) file_types = (str, File, CustomTarget, CustomTargetIndex)
class HotdocExternalProgram(ExternalProgram): class HotdocExternalProgram(ExternalProgram):
@ -51,29 +73,29 @@ class HotdocExternalProgram(ExternalProgram):
class HotdocTargetBuilder: class HotdocTargetBuilder:
def __init__(self, name, state, hotdoc, interpreter, kwargs): def __init__(self, name: str, state: ModuleState, hotdoc: HotdocExternalProgram, interpreter: Interpreter, kwargs):
self.hotdoc = hotdoc self.hotdoc = hotdoc
self.build_by_default = kwargs.pop('build_by_default', False) self.build_by_default = kwargs.pop('build_by_default', False)
self.kwargs = kwargs self.kwargs = kwargs
self.name = name self.name = name
self.state = state self.state = state
self.interpreter = interpreter self.interpreter = interpreter
self.include_paths = mesonlib.OrderedSet() self.include_paths: mesonlib.OrderedSet[str] = mesonlib.OrderedSet()
self.builddir = state.environment.get_build_dir() self.builddir = state.environment.get_build_dir()
self.sourcedir = state.environment.get_source_dir() self.sourcedir = state.environment.get_source_dir()
self.subdir = state.subdir self.subdir = state.subdir
self.build_command = state.environment.get_build_command() self.build_command = state.environment.get_build_command()
self.cmd = ['conf', '--project-name', name, "--disable-incremental-build", self.cmd: T.List[TYPE_var] = ['conf', '--project-name', name, "--disable-incremental-build",
'--output', os.path.join(self.builddir, self.subdir, self.name + '-doc')] '--output', os.path.join(self.builddir, self.subdir, self.name + '-doc')]
self._extra_extension_paths = set() self._extra_extension_paths = set()
self.extra_assets = set() self.extra_assets = set()
self.extra_depends = [] self.extra_depends = []
self._subprojects = [] self._subprojects = []
def process_known_arg(self, option, argname=None, value_processor=None): def process_known_arg(self, option: str, argname: T.Optional[str] = None, value_processor: T.Optional[T.Callable] = None) -> None:
if not argname: if not argname:
argname = option.strip("-").replace("-", "_") argname = option.strip("-").replace("-", "_")
@ -83,7 +105,7 @@ class HotdocTargetBuilder:
self.set_arg_value(option, value) self.set_arg_value(option, value)
def set_arg_value(self, option, value): def set_arg_value(self, option: str, value: TYPE_var) -> None:
if value is None: if value is None:
return return
@ -116,18 +138,18 @@ class HotdocTargetBuilder:
else: else:
self.cmd.extend([option, value]) self.cmd.extend([option, value])
def check_extra_arg_type(self, arg, value): def check_extra_arg_type(self, arg: str, value: TYPE_var) -> None:
if isinstance(value, list): if isinstance(value, list):
for v in value: for v in value:
self.check_extra_arg_type(arg, v) self.check_extra_arg_type(arg, v)
return return
valid_types = (str, bool, mesonlib.File, build.IncludeDirs, build.CustomTarget, build.CustomTargetIndex, build.BuildTarget) valid_types = (str, bool, File, build.IncludeDirs, CustomTarget, CustomTargetIndex, build.BuildTarget)
if not isinstance(value, valid_types): if not isinstance(value, valid_types):
raise InvalidArguments('Argument "{}={}" should be of type: {}.'.format( raise InvalidArguments('Argument "{}={}" should be of type: {}.'.format(
arg, value, [t.__name__ for t in valid_types])) arg, value, [t.__name__ for t in valid_types]))
def process_extra_args(self): def process_extra_args(self) -> None:
for arg, value in self.kwargs.items(): for arg, value in self.kwargs.items():
option = "--" + arg.replace("_", "-") option = "--" + arg.replace("_", "-")
self.check_extra_arg_type(arg, value) self.check_extra_arg_type(arg, value)
@ -158,7 +180,7 @@ class HotdocTargetBuilder:
return None, None return None, None
def add_extension_paths(self, paths): def add_extension_paths(self, paths: T.Union[T.List[str], T.Set[str]]) -> None:
for path in paths: for path in paths:
if path in self._extra_extension_paths: if path in self._extra_extension_paths:
continue continue
@ -166,10 +188,10 @@ class HotdocTargetBuilder:
self._extra_extension_paths.add(path) self._extra_extension_paths.add(path)
self.cmd.extend(["--extra-extension-path", path]) self.cmd.extend(["--extra-extension-path", path])
def replace_dirs_in_string(self, string): def replace_dirs_in_string(self, string: str) -> str:
return string.replace("@SOURCE_ROOT@", self.sourcedir).replace("@BUILD_ROOT@", self.builddir) return string.replace("@SOURCE_ROOT@", self.sourcedir).replace("@BUILD_ROOT@", self.builddir)
def process_gi_c_source_roots(self): def process_gi_c_source_roots(self) -> None:
if self.hotdoc.run_hotdoc(['--has-extension=gi-extension']) != 0: if self.hotdoc.run_hotdoc(['--has-extension=gi-extension']) != 0:
return return
@ -181,7 +203,7 @@ class HotdocTargetBuilder:
self.cmd += ['--gi-c-source-roots'] + value self.cmd += ['--gi-c-source-roots'] + value
def process_dependencies(self, deps): def process_dependencies(self, deps: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]]) -> T.List[str]:
cflags = set() cflags = set()
for dep in mesonlib.listify(ensure_list(deps)): for dep in mesonlib.listify(ensure_list(deps)):
if isinstance(dep, InternalDependency): if isinstance(dep, InternalDependency):
@ -205,29 +227,29 @@ class HotdocTargetBuilder:
self.include_paths.add(os.path.join(self.builddir, dep.hotdoc_conf.subdir)) self.include_paths.add(os.path.join(self.builddir, dep.hotdoc_conf.subdir))
self.cmd += ['--extra-assets=' + p for p in dep.extra_assets] self.cmd += ['--extra-assets=' + p for p in dep.extra_assets]
self.add_extension_paths(dep.extra_extension_paths) self.add_extension_paths(dep.extra_extension_paths)
elif isinstance(dep, (build.CustomTarget, build.BuildTarget)): elif isinstance(dep, (CustomTarget, build.BuildTarget)):
self.extra_depends.append(dep) self.extra_depends.append(dep)
elif isinstance(dep, build.CustomTargetIndex): elif isinstance(dep, CustomTargetIndex):
self.extra_depends.append(dep.target) self.extra_depends.append(dep.target)
return [f.strip('-I') for f in cflags] return [f.strip('-I') for f in cflags]
def process_extra_assets(self): def process_extra_assets(self) -> None:
self._extra_assets = self.kwargs.pop('extra_assets') self._extra_assets = self.kwargs.pop('extra_assets')
for assets_path in self._extra_assets: for assets_path in self._extra_assets:
self.cmd.extend(["--extra-assets", assets_path]) self.cmd.extend(["--extra-assets", assets_path])
def process_subprojects(self): def process_subprojects(self) -> None:
value = self.kwargs.pop('subprojects') value = self.kwargs.pop('subprojects')
self.process_dependencies(value) self.process_dependencies(value)
self._subprojects.extend(value) self._subprojects.extend(value)
def flatten_config_command(self): def flatten_config_command(self) -> T.List[str]:
cmd = [] cmd = []
for arg in mesonlib.listify(self.cmd, flatten=True): for arg in mesonlib.listify(self.cmd, flatten=True):
if isinstance(arg, mesonlib.File): if isinstance(arg, File):
arg = arg.absolute_path(self.state.environment.get_source_dir(), arg = arg.absolute_path(self.state.environment.get_source_dir(),
self.state.environment.get_build_dir()) self.state.environment.get_build_dir())
elif isinstance(arg, build.IncludeDirs): elif isinstance(arg, build.IncludeDirs):
@ -236,10 +258,10 @@ class HotdocTargetBuilder:
cmd.append(os.path.join(self.builddir, arg.get_curdir(), inc_dir)) cmd.append(os.path.join(self.builddir, arg.get_curdir(), inc_dir))
continue continue
elif isinstance(arg, (build.BuildTarget, build.CustomTarget)): elif isinstance(arg, (build.BuildTarget, CustomTarget)):
self.extra_depends.append(arg) self.extra_depends.append(arg)
arg = self.interpreter.backend.get_target_filename_abs(arg) arg = self.interpreter.backend.get_target_filename_abs(arg)
elif isinstance(arg, build.CustomTargetIndex): elif isinstance(arg, CustomTargetIndex):
self.extra_depends.append(arg.target) self.extra_depends.append(arg.target)
arg = self.interpreter.backend.get_target_filename_abs(arg) arg = self.interpreter.backend.get_target_filename_abs(arg)
@ -247,7 +269,7 @@ class HotdocTargetBuilder:
return cmd return cmd
def generate_hotdoc_config(self): def generate_hotdoc_config(self) -> None:
cwd = os.path.abspath(os.curdir) cwd = os.path.abspath(os.curdir)
ncwd = os.path.join(self.sourcedir, self.subdir) ncwd = os.path.join(self.sourcedir, self.subdir)
mlog.log('Generating Hotdoc configuration for: ', mlog.bold(self.name)) mlog.log('Generating Hotdoc configuration for: ', mlog.bold(self.name))
@ -256,7 +278,7 @@ class HotdocTargetBuilder:
raise MesonException('hotdoc failed to configure') raise MesonException('hotdoc failed to configure')
os.chdir(cwd) os.chdir(cwd)
def ensure_file(self, value): def ensure_file(self, value: T.Union[str, File, CustomTarget, CustomTargetIndex]) -> T.Union[File, CustomTarget, CustomTargetIndex]:
if isinstance(value, list): if isinstance(value, list):
res = [] res = []
for val in value: for val in value:
@ -264,11 +286,11 @@ class HotdocTargetBuilder:
return res return res
if isinstance(value, str): if isinstance(value, str):
return mesonlib.File.from_source_file(self.sourcedir, self.subdir, value) return File.from_source_file(self.sourcedir, self.subdir, value)
return value return value
def ensure_dir(self, value): def ensure_dir(self, value: str) -> str:
if os.path.isabs(value): if os.path.isabs(value):
_dir = value _dir = value
else: else:
@ -279,12 +301,12 @@ class HotdocTargetBuilder:
return os.path.relpath(_dir, os.path.join(self.builddir, self.subdir)) return os.path.relpath(_dir, os.path.join(self.builddir, self.subdir))
def check_forbidden_args(self): def check_forbidden_args(self) -> None:
for arg in ['conf_file']: for arg in ['conf_file']:
if arg in self.kwargs: if arg in self.kwargs:
raise InvalidArguments(f'Argument "{arg}" is forbidden.') raise InvalidArguments(f'Argument "{arg}" is forbidden.')
def make_targets(self): def make_targets(self) -> T.Tuple[HotdocTarget, mesonlib.ExecutableSerialisation]:
self.check_forbidden_args() self.check_forbidden_args()
self.process_known_arg("--index", value_processor=self.ensure_file) self.process_known_arg("--index", value_processor=self.ensure_file)
self.process_known_arg("--project-version") self.process_known_arg("--project-version")
@ -330,7 +352,7 @@ class HotdocTargetBuilder:
subdir=self.subdir, subdir=self.subdir,
subproject=self.state.subproject, subproject=self.state.subproject,
environment=self.state.environment, environment=self.state.environment,
hotdoc_conf=mesonlib.File.from_built_file( hotdoc_conf=File.from_built_file(
self.subdir, hotdoc_config_name), self.subdir, hotdoc_config_name),
extra_extension_paths=self._extra_extension_paths, extra_extension_paths=self._extra_extension_paths,
extra_assets=self._extra_assets, extra_assets=self._extra_assets,
@ -370,28 +392,29 @@ class HotdocTargetBuilder:
class HotdocTargetHolder(_CustomTargetHolder['HotdocTarget']): class HotdocTargetHolder(_CustomTargetHolder['HotdocTarget']):
def __init__(self, target: HotdocTarget, interp): def __init__(self, target: HotdocTarget, interp: Interpreter):
super().__init__(target, interp) super().__init__(target, interp)
self.methods.update({'config_path': self.config_path_method}) self.methods.update({'config_path': self.config_path_method})
@noPosargs @noPosargs
@noKwargs @noKwargs
def config_path_method(self, *args, **kwargs): def config_path_method(self, *args: T.Any, **kwargs: T.Any) -> str:
conf = self.held_object.hotdoc_conf.absolute_path(self.interpreter.environment.source_dir, conf = self.held_object.hotdoc_conf.absolute_path(self.interpreter.environment.source_dir,
self.interpreter.environment.build_dir) self.interpreter.environment.build_dir)
return conf return conf
class HotdocTarget(build.CustomTarget): class HotdocTarget(CustomTarget):
def __init__(self, name, subdir, subproject, hotdoc_conf, extra_extension_paths, extra_assets, def __init__(self, name: str, subdir: str, subproject: str, hotdoc_conf: File,
subprojects, environment, **kwargs): extra_extension_paths: T.Set[str], extra_assets: T.List[str],
subprojects: T.List['HotdocTarget'], environment: Environment, **kwargs: T.Any):
super().__init__(name, subdir, subproject, environment, **kwargs, absolute_paths=True) super().__init__(name, subdir, subproject, environment, **kwargs, absolute_paths=True)
self.hotdoc_conf = hotdoc_conf self.hotdoc_conf = hotdoc_conf
self.extra_extension_paths = extra_extension_paths self.extra_extension_paths = extra_extension_paths
self.extra_assets = extra_assets self.extra_assets = extra_assets
self.subprojects = subprojects self.subprojects = subprojects
def __getstate__(self): def __getstate__(self) -> dict:
# Make sure we do not try to pickle subprojects # Make sure we do not try to pickle subprojects
res = self.__dict__.copy() res = self.__dict__.copy()
res['subprojects'] = [] res['subprojects'] = []
@ -403,7 +426,7 @@ class HotDocModule(ExtensionModule):
INFO = ModuleInfo('hotdoc', '0.48.0') INFO = ModuleInfo('hotdoc', '0.48.0')
def __init__(self, interpreter): def __init__(self, interpreter: Interpreter):
super().__init__(interpreter) super().__init__(interpreter)
self.hotdoc = HotdocExternalProgram('hotdoc') self.hotdoc = HotdocExternalProgram('hotdoc')
if not self.hotdoc.found(): if not self.hotdoc.found():
@ -419,7 +442,7 @@ class HotDocModule(ExtensionModule):
@noKwargs @noKwargs
@typed_pos_args('hotdoc.has_extensions', varargs=str, min_varargs=1) @typed_pos_args('hotdoc.has_extensions', varargs=str, min_varargs=1)
def has_extensions(self, state, args, kwargs): def has_extensions(self, state: ModuleState, args: T.Tuple[T.List[str]], kwargs: TYPE_kwargs) -> bool:
return self.hotdoc.run_hotdoc([f'--has-extension={extension}' for extension in args[0]]) == 0 return self.hotdoc.run_hotdoc([f'--has-extension={extension}' for extension in args[0]]) == 0
@typed_pos_args('hotdoc.generate_doc', str) @typed_pos_args('hotdoc.generate_doc', str)
@ -434,13 +457,13 @@ class HotDocModule(ExtensionModule):
KwargInfo( KwargInfo(
'dependencies', 'dependencies',
ContainerTypeInfo(list, (Dependency, build.StaticLibrary, build.SharedLibrary, ContainerTypeInfo(list, (Dependency, build.StaticLibrary, build.SharedLibrary,
build.CustomTarget, build.CustomTargetIndex)), CustomTarget, CustomTargetIndex)),
listify=True, listify=True,
default=[], default=[],
), ),
KwargInfo( KwargInfo(
'depends', 'depends',
ContainerTypeInfo(list, (build.CustomTarget, build.CustomTargetIndex)), ContainerTypeInfo(list, (CustomTarget, CustomTargetIndex)),
listify=True, listify=True,
default=[], default=[],
since='0.64.1', since='0.64.1',
@ -452,21 +475,21 @@ class HotDocModule(ExtensionModule):
KwargInfo('install', bool, default=False), KwargInfo('install', bool, default=False),
allow_unknown=True allow_unknown=True
) )
def generate_doc(self, state, args, kwargs): def generate_doc(self, state: ModuleState, args: T.Tuple[str], kwargs: GenerateDocKwargs) -> ModuleReturnValue:
project_name = args[0] project_name = args[0]
if any(isinstance(x, (build.CustomTarget, build.CustomTargetIndex)) for x in kwargs['dependencies']): if any(isinstance(x, (CustomTarget, CustomTargetIndex)) for x in kwargs['dependencies']):
FeatureDeprecated.single_use('hotdoc.generate_doc dependencies argument with custom_target', FeatureDeprecated.single_use('hotdoc.generate_doc dependencies argument with custom_target',
'0.64.1', state.subproject, 'use `depends`', state.current_node) '0.64.1', state.subproject, 'use `depends`', state.current_node)
builder = HotdocTargetBuilder(project_name, state, self.hotdoc, self.interpreter, kwargs) builder = HotdocTargetBuilder(project_name, state, self.hotdoc, self.interpreter, kwargs)
target, install_script = builder.make_targets() target, install_script = builder.make_targets()
targets = [target] targets: T.List[T.Union[HotdocTarget, mesonlib.ExecutableSerialisation]] = [target]
if install_script: if install_script:
targets.append(install_script) targets.append(install_script)
return ModuleReturnValue(targets[0], targets) return ModuleReturnValue(target, targets)
def initialize(interpreter): def initialize(interpreter: Interpreter) -> HotDocModule:
mod = HotDocModule(interpreter) mod = HotDocModule(interpreter)
mod.interpreter.append_holder_map(HotdocTarget, HotdocTargetHolder) mod.interpreter.append_holder_map(HotdocTarget, HotdocTargetHolder)
return mod return mod