Skip to content

fully type safe hotdoc module #15790

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dcbaker wants to merge 5 commits into
base: master
Choose a base branch
from
+39 −41
Open

fully type safe hotdoc module #15790

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cd886b4
modules/hotdoc: use SubProject instead of str
dcbaker May 8, 2026
9afb4a6
modules/hotdoc: Add assert for option values
dcbaker May 8, 2026
8134313
modules/hotdoc: Fix missing and incorrect annotations
dcbaker May 8, 2026
99096dc
modules/hotdoc: fix issues with the kwargs the TypedDict
dcbaker May 8, 2026
5f94c01
run_mypy: all modules are now type safe!
dcbaker May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 38 additions & 15 deletions mesonbuild/modules/hotdoc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,17 @@
from . import ModuleState
from ..environment import Environment
from ..interpreter import Interpreter
from ..interpreterbase import TYPE_kwargs, TYPE_var
from ..interpreter.kwargs import TargetDepends
from ..interpreterbase import TYPE_kwargs, TYPE_var, SubProject

_T = T.TypeVar('_T')

class GenerateDocKwargs(TypedDict):
# there is currently no way to represent the arbitrary key/value paris that
# the hotdoc module allows.
#
# PEP-728, which is due in Python 3.15, will fix this, we can then add a new
# extra_items=str keyword argument.
class GenerateDocKwargs(TypedDict, total=False):
sitemap: T.Union[str, File, CustomTarget, CustomTargetIndex]
index: T.Union[str, File, CustomTarget, CustomTargetIndex]
project_version: str
Expand All @@ -45,6 +51,8 @@ class GenerateDocKwargs(TypedDict):
extra_extension_paths: T.List[str]
subprojects: T.List['HotdocTarget']
install: bool
build_by_default: bool


def ensure_list(value: T.Union[_T, T.List[_T]]) -> T.List[_T]:
if not isinstance(value, list):
Expand All @@ -64,7 +72,7 @@ def run_hotdoc(self, cmd: T.List[str]) -> int:

class HotdocTargetBuilder:

def __init__(self, name: str, state: ModuleState, hotdoc: HotdocExternalProgram, interpreter: Interpreter, kwargs):
def __init__(self, name: str, state: ModuleState, hotdoc: HotdocExternalProgram, interpreter: Interpreter, kwargs: GenerateDocKwargs):
self.hotdoc = hotdoc
self.build_by_default = kwargs.pop('build_by_default', False)
self.kwargs = kwargs
Expand All @@ -81,16 +89,15 @@ def __init__(self, name: str, state: ModuleState, hotdoc: HotdocExternalProgram,
self.cmd: T.List[TYPE_var] = ['conf', '--project-name', name, "--disable-incremental-build",
'--output', os.path.join(self.builddir, self.subdir, self.name + '-doc')]

self._extra_extension_paths = set()
self.extra_assets = set()
self.extra_depends = []
self._subprojects = []
self._extra_extension_paths: set[str] = set()
self.extra_depends: list[build.BuildTargetTypes] = []
self._subprojects: list[HotdocTarget] = []

def process_known_arg(self, option: str, argname: T.Optional[str] = None, value_processor: T.Optional[T.Callable] = None) -> None:
if not argname:
argname = option.strip("-").replace("-", "_")

value = self.kwargs.pop(argname)
value = self.kwargs.pop(argname) # type: ignore[misc]
if value is not None and value_processor:
value = value_processor(value)

Expand Down Expand Up @@ -143,8 +150,8 @@ def check_extra_arg_type(self, arg: str, value: TYPE_var) -> None:
def process_extra_args(self) -> None:
for arg, value in self.kwargs.items():
option = "--" + arg.replace("_", "-")
self.check_extra_arg_type(arg, value)
self.set_arg_value(option, value)
self.check_extra_arg_type(arg, value) # type: ignore[arg-type]
self.set_arg_value(option, value) # type: ignore[arg-type]

def add_extension_paths(self, paths: T.Union[T.List[str], T.Set[str]]) -> None:
for path in paths:
Expand All @@ -169,7 +176,9 @@ def process_gi_c_source_roots(self) -> None:

self.cmd += ['--gi-c-source-roots'] + value

def process_dependencies(self, deps: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]]) -> T.List[str]:
def process_dependencies(self, deps: T.Sequence[TargetDepends | Dependency | File | build.ExtractedObjects | build.StructuredSources]) -> T.List[str]:
# build.StructuredSources and build.ExtractedObjects shouldn't actually
# happen here, but we get them from Dependency.
cflags = set()
for dep in mesonlib.listify(ensure_list(deps)):
if isinstance(dep, InternalDependency):
Expand Down Expand Up @@ -241,9 +250,18 @@ def generate_hotdoc_config(self) -> None:
raise MesonException('hotdoc failed to configure')
os.chdir(cwd)

def ensure_file(self, value: T.Union[str, File, CustomTarget, CustomTargetIndex]) -> T.Union[File, CustomTarget, CustomTargetIndex]:
@T.overload
def ensure_file(self, value: list[str | File | CustomTarget | CustomTargetIndex]
) -> list[File | CustomTarget | CustomTargetIndex]: ...

@T.overload
def ensure_file(self, value: str | File | CustomTarget | CustomTargetIndex
) -> File | CustomTarget | CustomTargetIndex: ...

def ensure_file(self, value: str | File | CustomTarget | CustomTargetIndex | list[str | File | CustomTarget | CustomTargetIndex]
) -> File | CustomTarget | CustomTargetIndex | list[File | CustomTarget | CustomTargetIndex]:
if isinstance(value, list):
res = []
res: list[File | CustomTarget | CustomTargetIndex] = []
for val in value:
res.append(self.ensure_file(val))
return res
Expand Down Expand Up @@ -329,7 +347,11 @@ def make_targets(self) -> T.Tuple[HotdocTarget, mesonlib.ExecutableSerialisation

install_script = None
if install:
datadir = os.path.join(self.state.get_option('prefix'), self.state.get_option('datadir'))
prefix = self.state.get_option('prefix')
assert isinstance(prefix, str), 'for mypy'
datadir = self.state.get_option('datadir')
assert isinstance(datadir, str), 'for mypy'
datadir = os.path.join(prefix, datadir)
devhelp = self.kwargs.get('devhelp_activate', False)
if not isinstance(devhelp, bool):
FeatureDeprecated.single_use('hotdoc.generate_doc() devhelp_activate must be boolean', '1.1.0', self.state.subproject)
Expand Down Expand Up @@ -365,7 +387,7 @@ def config_path_method(self, *args: T.Any, **kwargs: T.Any) -> str:


class HotdocTarget(CustomTarget):
def __init__(self, name: str, subdir: str, subproject: str, hotdoc_conf: File,
def __init__(self, name: str, subdir: str, subproject: SubProject, hotdoc_conf: File,
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)
Expand Down Expand Up @@ -433,6 +455,7 @@ def has_extensions(self, state: ModuleState, args: T.Tuple[T.List[str]], kwargs:
KwargInfo('extra_extension_paths', ContainerTypeInfo(list, str), listify=True, default=[]),
KwargInfo('subprojects', ContainerTypeInfo(list, HotdocTarget), listify=True, default=[]),
KwargInfo('install', bool, default=False),
KwargInfo('build_by_default', bool, default=False),
allow_unknown=True
)
def generate_doc(self, state: ModuleState, args: T.Tuple[str], kwargs: GenerateDocKwargs) -> ModuleReturnValue:
Expand Down
27 changes: 1 addition & 26 deletions run_mypy.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
'mesonbuild/interpreter/primitives/',
'mesonbuild/interpreterbase/',
'mesonbuild/linkers/',
'mesonbuild/modules/',
'mesonbuild/scripts/',
'mesonbuild/templates/',
'mesonbuild/utils/',
Expand Down Expand Up @@ -54,32 +55,6 @@
'mesonbuild/mintro.py',
'mesonbuild/mlog.py',
'mesonbuild/msubprojects.py',
'mesonbuild/modules/__init__.py',
'mesonbuild/modules/cmake.py',
'mesonbuild/modules/codegen.py',
'mesonbuild/modules/cuda.py',
'mesonbuild/modules/dlang.py',
'mesonbuild/modules/external_project.py',
'mesonbuild/modules/fs.py',
'mesonbuild/modules/gnome.py',
'mesonbuild/modules/i18n.py',
'mesonbuild/modules/icestorm.py',
'mesonbuild/modules/java.py',
'mesonbuild/modules/keyval.py',
'mesonbuild/modules/modtest.py',
'mesonbuild/modules/pkgconfig.py',
'mesonbuild/modules/python.py',
'mesonbuild/modules/python3.py',
'mesonbuild/modules/_qt.py',
'mesonbuild/modules/qt4.py',
'mesonbuild/modules/qt5.py',
'mesonbuild/modules/qt6.py',
'mesonbuild/modules/rust.py',
'mesonbuild/modules/simd.py',
'mesonbuild/modules/snippets.py',
'mesonbuild/modules/sourceset.py',
'mesonbuild/modules/wayland.py',
'mesonbuild/modules/windows.py',
'mesonbuild/mparser.py',
'mesonbuild/msetup.py',
'mesonbuild/mtest.py',
Expand Down
Loading