Sphinx 7.2.6__py3-none-any.whl → 7.3.1__py3-none-any.whl

sphinx/config.py

@@ -2,33 +2,45 @@
 
 from __future__ import annotations
 
+import sys
 import time
 import traceback
 import types
+import warnings
 from os import getenv, path
-from typing import TYPE_CHECKING, Any, Callable, NamedTuple
+from typing import TYPE_CHECKING, Any, Literal, NamedTuple, Union
 
+from sphinx.deprecation import RemovedInSphinx90Warning
 from sphinx.errors import ConfigError, ExtensionError
 from sphinx.locale import _, __
 from sphinx.util import logging
 from sphinx.util.osutil import fs_encoding
-from sphinx.util.typing import NoneType
+from sphinx.util.typing import ExtensionMetadata, NoneType
 
-try:
-    from contextlib import chdir  # type: ignore[attr-defined]
-except ImportError:
+if sys.version_info >= (3, 11):
+    from contextlib import chdir
+else:
     from sphinx.util.osutil import _chdir as chdir
 
 if TYPE_CHECKING:
     import os
-    from collections.abc import Generator, Iterator, Sequence
+    from collections.abc import Collection, Iterator, Sequence, Set
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
     from sphinx.util.tags import Tags
+    from sphinx.util.typing import _ExtensionSetupFunc
 
 logger = logging.getLogger(__name__)
 
+_ConfigRebuild = Literal[
+    '', 'env', 'epub', 'gettext', 'html',
+    # sphinxcontrib-applehelp
+    'applehelp',
+    # sphinxcontrib-devhelp
+    'devhelp',
+]
+
 CONFIG_FILENAME = 'conf.py'
 UNSERIALIZABLE_TYPES = (type, types.ModuleType, types.FunctionType)
 
@@ -36,20 +48,33 @@ UNSERIALIZABLE_TYPES = (type, types.ModuleType, types.FunctionType)
 class ConfigValue(NamedTuple):
     name: str
     value: Any
-    rebuild: bool | str
+    rebuild: _ConfigRebuild
 
 
-def is_serializable(obj: Any) -> bool:
+def is_serializable(obj: object, *, _recursive_guard: frozenset[int] = frozenset()) -> bool:
     """Check if object is serializable or not."""
     if isinstance(obj, UNSERIALIZABLE_TYPES):
         return False
-    elif isinstance(obj, dict):
+
+    # use id() to handle un-hashable objects
+    if id(obj) in _recursive_guard:
+        return True
+
+    if isinstance(obj, dict):
+        guard = _recursive_guard | {id(obj)}
         for key, value in obj.items():
-            if not is_serializable(key) or not is_serializable(value):
+            if (
+                not is_serializable(key, _recursive_guard=guard)
+                or not is_serializable(value, _recursive_guard=guard)
+            ):
                 return False
-    elif isinstance(obj, (list, tuple, set)):
-        return all(is_serializable(i) for i in obj)
+    elif isinstance(obj, (list, tuple, set, frozenset)):
+        guard = _recursive_guard | {id(obj)}
+        return all(is_serializable(item, _recursive_guard=guard) for item in obj)
 
+    # if an issue occurs for a non-serializable type, pickle will complain
+    # since the object is likely coming from a third-party extension (we
+    # natively expect 'simple' types and not weird ones)
     return True
 
 
@@ -59,6 +84,7 @@ class ENUM:
     Example:
         app.add_config_value('latex_show_urls', 'no', None, ENUM('no', 'footnote', 'inline'))
     """
+
     def __init__(self, *candidates: str | bool | None) -> None:
         self.candidates = candidates
 
@@ -69,10 +95,92 @@ class ENUM:
             return value in self.candidates
 
 
+_OptValidTypes = Union[tuple[()], tuple[type, ...], frozenset[type], ENUM]
+
+
+class _Opt:
+    __slots__ = 'default', 'rebuild', 'valid_types'
+
+    default: Any
+    rebuild: _ConfigRebuild
+    valid_types: _OptValidTypes
+
+    def __init__(
+        self,
+        default: Any,
+        rebuild: _ConfigRebuild,
+        valid_types: _OptValidTypes,
+    ) -> None:
+        """Configuration option type for Sphinx.
+
+        The type is intended to be immutable; changing the field values
+        is an unsupported action.
+        No validation is performed on the values, though consumers will
+        likely expect them to be of the types advertised.
+        The old tuple-based interface will be removed in Sphinx 9.
+        """
+        super().__setattr__('default', default)
+        super().__setattr__('rebuild', rebuild)
+        super().__setattr__('valid_types', valid_types)
+
+    def __repr__(self) -> str:
+        return (
+            f'{self.__class__.__qualname__}('
+            f'default={self.default!r}, '
+            f'rebuild={self.rebuild!r}, '
+            f'valid_types={self.valid_types!r})'
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, _Opt):
+            self_tpl = (self.default, self.rebuild, self.valid_types)
+            other_tpl = (other.default, other.rebuild, other.valid_types)
+            return self_tpl == other_tpl
+        return NotImplemented
+
+    def __lt__(self, other: _Opt) -> bool:
+        if self.__class__ is other.__class__:
+            self_tpl = (self.default, self.rebuild, self.valid_types)
+            other_tpl = (other.default, other.rebuild, other.valid_types)
+            return self_tpl > other_tpl
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((self.default, self.rebuild, self.valid_types))
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        if key in {'default', 'rebuild', 'valid_types'}:
+            msg = f'{self.__class__.__name__!r} object does not support assignment to {key!r}'
+            raise TypeError(msg)
+        super().__setattr__(key, value)
+
+    def __delattr__(self, key: str) -> None:
+        if key in {'default', 'rebuild', 'valid_types'}:
+            msg = f'{self.__class__.__name__!r} object does not support deletion of {key!r}'
+            raise TypeError(msg)
+        super().__delattr__(key)
+
+    def __getstate__(self) -> tuple[Any, _ConfigRebuild, _OptValidTypes]:
+        return self.default, self.rebuild, self.valid_types
+
+    def __setstate__(self, state: tuple[Any, _ConfigRebuild, _OptValidTypes]) -> None:
+        default, rebuild, valid_types = state
+        super().__setattr__('default', default)
+        super().__setattr__('rebuild', rebuild)
+        super().__setattr__('valid_types', valid_types)
+
+    def __getitem__(self, item: int | slice) -> Any:
+        warnings.warn(
+            f'The {self.__class__.__name__!r} object tuple interface is deprecated, '
+            "use attribute access instead for 'default', 'rebuild', and 'valid_types'.",
+            RemovedInSphinx90Warning, stacklevel=2)
+        return (self.default, self.rebuild, self.valid_types)[item]
+
+
 class Config:
     r"""Configuration file abstraction.
 
-    The config object makes the values of all config values available as
+    The Config object makes the values of all config options available as
     attributes.
 
     It is exposed via the :py:class:`~sphinx.application.Sphinx`\ ``.config``
@@ -81,97 +189,119 @@ class Config:
     ``app.config.language`` or ``env.config.language``.
     """
 
-    # the values are: (default, what needs to be rebuilt if changed)
+    # The values are:
+    # 1. Default
+    # 2. What needs to be rebuilt if changed
+    # 3. Valid types
 
-    # If you add a value here, don't forget to include it in the
-    # quickstart.py file template as well as in the docs!
+    # If you add a value here, remember to include it in the docs!
 
-    config_values: dict[str, tuple] = {
+    config_values: dict[str, _Opt] = {
         # general options
-        'project': ('Python', 'env', []),
-        'author': ('unknown', 'env', []),
-        'project_copyright': ('', 'html', [str, tuple, list]),
-        'copyright': (lambda c: c.project_copyright, 'html', [str, tuple, list]),
-        'version': ('', 'env', []),
-        'release': ('', 'env', []),
-        'today': ('', 'env', []),
+        'project': _Opt('Python', 'env', ()),
+        'author': _Opt('unknown', 'env', ()),
+        'project_copyright': _Opt('', 'html', frozenset((str, tuple, list))),
+        'copyright': _Opt(
+            lambda c: c.project_copyright, 'html', frozenset((str, tuple, list))),
+        'version': _Opt('', 'env', ()),
+        'release': _Opt('', 'env', ()),
+        'today': _Opt('', 'env', ()),
         # the real default is locale-dependent
-        'today_fmt': (None, 'env', [str]),
-
-        'language': ('en', 'env', [str]),
-        'locale_dirs': (['locales'], 'env', []),
-        'figure_language_filename': ('{root}.{language}{ext}', 'env', [str]),
-        'gettext_allow_fuzzy_translations': (False, 'gettext', []),
-        'translation_progress_classes': (False, 'env',
-                                         ENUM(True, False, 'translated', 'untranslated')),
-
-        'master_doc': ('index', 'env', []),
-        'root_doc': (lambda config: config.master_doc, 'env', []),
-        'source_suffix': ({'.rst': 'restructuredtext'}, 'env', Any),
-        'source_encoding': ('utf-8-sig', 'env', []),
-        'exclude_patterns': ([], 'env', [str]),
-        'include_patterns': (["**"], 'env', [str]),
-        'default_role': (None, 'env', [str]),
-        'add_function_parentheses': (True, 'env', []),
-        'add_module_names': (True, 'env', []),
-        'toc_object_entries': (True, 'env', [bool]),
-        'toc_object_entries_show_parents': ('domain', 'env',
-                                            ENUM('domain', 'all', 'hide')),
-        'trim_footnote_reference_space': (False, 'env', []),
-        'show_authors': (False, 'env', []),
-        'pygments_style': (None, 'html', [str]),
-        'highlight_language': ('default', 'env', []),
-        'highlight_options': ({}, 'env', []),
-        'templates_path': ([], 'html', []),
-        'template_bridge': (None, 'html', [str]),
-        'keep_warnings': (False, 'env', []),
-        'suppress_warnings': ([], 'env', []),
-        'modindex_common_prefix': ([], 'html', []),
-        'rst_epilog': (None, 'env', [str]),
-        'rst_prolog': (None, 'env', [str]),
-        'trim_doctest_flags': (True, 'env', []),
-        'primary_domain': ('py', 'env', [NoneType]),
-        'needs_sphinx': (None, None, [str]),
-        'needs_extensions': ({}, None, []),
-        'manpages_url': (None, 'env', []),
-        'nitpicky': (False, None, []),
-        'nitpick_ignore': ([], None, [set, list, tuple]),
-        'nitpick_ignore_regex': ([], None, [set, list, tuple]),
-        'numfig': (False, 'env', []),
-        'numfig_secnum_depth': (1, 'env', []),
-        'numfig_format': ({}, 'env', []),  # will be initialized in init_numfig_format()
-        'maximum_signature_line_length': (None, 'env', {int, None}),
-        'math_number_all': (False, 'env', []),
-        'math_eqref_format': (None, 'env', [str]),
-        'math_numfig': (True, 'env', []),
-        'tls_verify': (True, 'env', []),
-        'tls_cacerts': (None, 'env', []),
-        'user_agent': (None, 'env', [str]),
-        'smartquotes': (True, 'env', []),
-        'smartquotes_action': ('qDe', 'env', []),
-        'smartquotes_excludes': ({'languages': ['ja'],
-                                  'builders': ['man', 'text']},
-                                 'env', []),
-        'option_emphasise_placeholders': (False, 'env', []),
+        'today_fmt': _Opt(None, 'env', frozenset((str,))),
+
+        'language': _Opt('en', 'env', frozenset((str,))),
+        'locale_dirs': _Opt(['locales'], 'env', ()),
+        'figure_language_filename': _Opt('{root}.{language}{ext}', 'env', frozenset((str,))),
+        'gettext_allow_fuzzy_translations': _Opt(False, 'gettext', ()),
+        'translation_progress_classes': _Opt(
+            False, 'env', ENUM(True, False, 'translated', 'untranslated')),
+
+        'master_doc': _Opt('index', 'env', ()),
+        'root_doc': _Opt(lambda config: config.master_doc, 'env', ()),
+        # ``source_suffix`` type is actually ``dict[str, str | None]``:
+        # see ``convert_source_suffix()`` below.
+        'source_suffix': _Opt(
+            {'.rst': 'restructuredtext'}, 'env', Any),  # type: ignore[arg-type]
+        'source_encoding': _Opt('utf-8-sig', 'env', ()),
+        'exclude_patterns': _Opt([], 'env', frozenset((str,))),
+        'include_patterns': _Opt(["**"], 'env', frozenset((str,))),
+        'default_role': _Opt(None, 'env', frozenset((str,))),
+        'add_function_parentheses': _Opt(True, 'env', ()),
+        'add_module_names': _Opt(True, 'env', ()),
+        'toc_object_entries': _Opt(True, 'env', frozenset((bool,))),
+        'toc_object_entries_show_parents': _Opt(
+            'domain', 'env', ENUM('domain', 'all', 'hide')),
+        'trim_footnote_reference_space': _Opt(False, 'env', ()),
+        'show_authors': _Opt(False, 'env', ()),
+        'pygments_style': _Opt(None, 'html', frozenset((str,))),
+        'highlight_language': _Opt('default', 'env', ()),
+        'highlight_options': _Opt({}, 'env', ()),
+        'templates_path': _Opt([], 'html', ()),
+        'template_bridge': _Opt(None, 'html', frozenset((str,))),
+        'keep_warnings': _Opt(False, 'env', ()),
+        'suppress_warnings': _Opt([], 'env', ()),
+        'show_warning_types': _Opt(False, 'env', frozenset((bool,))),
+        'modindex_common_prefix': _Opt([], 'html', ()),
+        'rst_epilog': _Opt(None, 'env', frozenset((str,))),
+        'rst_prolog': _Opt(None, 'env', frozenset((str,))),
+        'trim_doctest_flags': _Opt(True, 'env', ()),
+        'primary_domain': _Opt('py', 'env', frozenset((NoneType,))),
+        'needs_sphinx': _Opt(None, '', frozenset((str,))),
+        'needs_extensions': _Opt({}, '', ()),
+        'manpages_url': _Opt(None, 'env', ()),
+        'nitpicky': _Opt(False, '', ()),
+        'nitpick_ignore': _Opt([], '', frozenset((set, list, tuple))),
+        'nitpick_ignore_regex': _Opt([], '', frozenset((set, list, tuple))),
+        'numfig': _Opt(False, 'env', ()),
+        'numfig_secnum_depth': _Opt(1, 'env', ()),
+        'numfig_format': _Opt({}, 'env', ()),  # will be initialized in init_numfig_format()
+        'maximum_signature_line_length': _Opt(
+            None, 'env', frozenset((int, NoneType))),
+        'math_number_all': _Opt(False, 'env', ()),
+        'math_eqref_format': _Opt(None, 'env', frozenset((str,))),
+        'math_numfig': _Opt(True, 'env', ()),
+        'tls_verify': _Opt(True, 'env', ()),
+        'tls_cacerts': _Opt(None, 'env', ()),
+        'user_agent': _Opt(None, 'env', frozenset((str,))),
+        'smartquotes': _Opt(True, 'env', ()),
+        'smartquotes_action': _Opt('qDe', 'env', ()),
+        'smartquotes_excludes': _Opt(
+            {'languages': ['ja'], 'builders': ['man', 'text']}, 'env', ()),
+        'option_emphasise_placeholders': _Opt(False, 'env', ()),
     }
 
     def __init__(self, config: dict[str, Any] | None = None,
                  overrides: dict[str, Any] | None = None) -> None:
-        config = config or {}
-        self.overrides = dict(overrides) if overrides is not None else {}
-        self.values = Config.config_values.copy()
-        self._raw_config = config
-        self.setup: Callable | None = config.get('setup', None)
-
-        if 'extensions' in self.overrides:
-            if isinstance(self.overrides['extensions'], str):
-                config['extensions'] = self.overrides.pop('extensions').split(',')
+        raw_config: dict[str, Any] = config or {}
+        self._overrides = dict(overrides) if overrides is not None else {}
+        self._options = Config.config_values.copy()
+        self._raw_config = raw_config
+
+        for name in list(self._overrides.keys()):
+            if '.' in name:
+                real_name, key = name.split('.', 1)
+                raw_config.setdefault(real_name, {})[key] = self._overrides.pop(name)
+
+        self.setup: _ExtensionSetupFunc | None = raw_config.get('setup')
+
+        if 'extensions' in self._overrides:
+            extensions = self._overrides.pop('extensions')
+            if isinstance(extensions, str):
+                raw_config['extensions'] = extensions.split(',')
             else:
-                config['extensions'] = self.overrides.pop('extensions')
-        self.extensions: list[str] = config.get('extensions', [])
+                raw_config['extensions'] = extensions
+        self.extensions: list[str] = raw_config.get('extensions', [])
+
+    @property
+    def values(self) -> dict[str, _Opt]:
+        return self._options
+
+    @property
+    def overrides(self) -> dict[str, Any]:
+        return self._overrides
 
     @classmethod
-    def read(cls, confdir: str | os.PathLike[str], overrides: dict | None = None,
+    def read(cls: type[Config], confdir: str | os.PathLike[str], overrides: dict | None = None,
              tags: Tags | None = None) -> Config:
         """Create a Config object from configuration file."""
         filename = path.join(confdir, CONFIG_FILENAME)
@@ -190,106 +320,103 @@ class Config:
                               "Falling back to 'en' (English)."))
             namespace["language"] = "en"
 
-        return cls(namespace, overrides or {})
+        return cls(namespace, overrides)
 
-    def convert_overrides(self, name: str, value: Any) -> Any:
-        if not isinstance(value, str):
+    def convert_overrides(self, name: str, value: str) -> Any:
+        opt = self._options[name]
+        default = opt.default
+        valid_types = opt.valid_types
+        if valid_types == Any:
             return value
-        else:
-            defvalue = self.values[name][0]
-            if self.values[name][2] == Any:
-                return value
-            elif self.values[name][2] == {bool, str}:
-                if value == '0':
-                    # given falsy string from command line option
-                    return False
-                elif value == '1':
-                    return True
-                else:
-                    return value
-            elif type(defvalue) is bool or self.values[name][2] == [bool]:
-                if value == '0':
-                    # given falsy string from command line option
-                    return False
-                else:
-                    return bool(value)
-            elif isinstance(defvalue, dict):
-                raise ValueError(__('cannot override dictionary config setting %r, '
-                                    'ignoring (use %r to set individual elements)') %
-                                 (name, name + '.key=value'))
-            elif isinstance(defvalue, list):
-                return value.split(',')
-            elif isinstance(defvalue, int):
-                try:
-                    return int(value)
-                except ValueError as exc:
-                    raise ValueError(__('invalid number %r for config value %r, ignoring') %
-                                     (value, name)) from exc
-            elif callable(defvalue):
+        elif (type(default) is bool
+              or (not isinstance(valid_types, ENUM)
+                  and len(valid_types) == 1 and bool in valid_types)):
+            if isinstance(valid_types, ENUM) or len(valid_types) > 1:
+                # if valid_types are given, and non-bool valid types exist,
+                # return the value without coercing to a Boolean.
                 return value
-            elif defvalue is not None and not isinstance(defvalue, str):
-                raise ValueError(__('cannot override config setting %r with unsupported '
-                                    'type, ignoring') % name)
-            else:
-                return value
-
-    def pre_init_values(self) -> None:
-        """
-        Initialize some limited config variables before initializing i18n and loading
-        extensions.
-        """
-        variables = ['needs_sphinx', 'suppress_warnings', 'language', 'locale_dirs']
-        for name in variables:
+            # given falsy string from a command line option
+            return value not in {'0', ''}
+        elif isinstance(default, dict):
+            raise ValueError(__('cannot override dictionary config setting %r, '
+                                'ignoring (use %r to set individual elements)') %
+                             (name, f'{name}.key=value'))
+        elif isinstance(default, list):
+            return value.split(',')
+        elif isinstance(default, int):
             try:
-                if name in self.overrides:
-                    self.__dict__[name] = self.convert_overrides(name, self.overrides[name])
-                elif name in self._raw_config:
-                    self.__dict__[name] = self._raw_config[name]
+                return int(value)
             except ValueError as exc:
-                logger.warning("%s", exc)
+                raise ValueError(__('invalid number %r for config value %r, ignoring') %
+                                 (value, name)) from exc
+        elif callable(default):
+            return value
+        elif default is not None and not isinstance(default, str):
+            raise ValueError(__('cannot override config setting %r with unsupported '
+                                'type, ignoring') % name)
+        else:
+            return value
+
+    @staticmethod
+    def pre_init_values() -> None:
+        # method only retained for compatibility
+        pass
+        # warnings.warn(
+        #     'Config.pre_init_values() will be removed in Sphinx 9.0 or later',
+        #     RemovedInSphinx90Warning, stacklevel=2)
 
     def init_values(self) -> None:
-        config = self._raw_config
-        for valname, value in self.overrides.items():
+        # method only retained for compatibility
+        self._report_override_warnings()
+        # warnings.warn(
+        #     'Config.init_values() will be removed in Sphinx 9.0 or later',
+        #     RemovedInSphinx90Warning, stacklevel=2)
+
+    def _report_override_warnings(self) -> None:
+        for name in self._overrides:
+            if name not in self._options:
+                logger.warning(__('unknown config value %r in override, ignoring'), name)
+
+    def __repr__(self) -> str:
+        values = []
+        for opt_name in self._options:
             try:
-                if '.' in valname:
-                    realvalname, key = valname.split('.', 1)
-                    config.setdefault(realvalname, {})[key] = value
-                    continue
-                if valname not in self.values:
-                    logger.warning(__('unknown config value %r in override, ignoring'),
-                                   valname)
-                    continue
-                if isinstance(value, str):
-                    config[valname] = self.convert_overrides(valname, value)
-                else:
-                    config[valname] = value
-            except ValueError as exc:
-                logger.warning("%s", exc)
-        for name in config:
-            if name in self.values:
-                self.__dict__[name] = config[name]
-
-    def post_init_values(self) -> None:
-        """
-        Initialize additional config variables that are added after init_values() called.
-        """
-        config = self._raw_config
-        for name in config:
-            if name not in self.__dict__ and name in self.values:
-                self.__dict__[name] = config[name]
-
-        check_confval_types(None, self)
+                opt_value = getattr(self, opt_name)
+            except Exception:
+                opt_value = '<error!>'
+            values.append(f"{opt_name}={opt_value!r}")
+        return self.__class__.__qualname__ + '(' + ', '.join(values) + ')'
 
     def __getattr__(self, name: str) -> Any:
+        if name in self._options:
+            # first check command-line overrides
+            if name in self._overrides:
+                value = self._overrides[name]
+                if not isinstance(value, str):
+                    self.__dict__[name] = value
+                    return value
+                try:
+                    value = self.convert_overrides(name, value)
+                except ValueError as exc:
+                    logger.warning("%s", exc)
+                else:
+                    self.__dict__[name] = value
+                    return value
+            # then check values from 'conf.py'
+            if name in self._raw_config:
+                self.__dict__[name] = value = self._raw_config[name]
+                return value
+            # finally, fall back to the default value
+            default = self._options[name].default
+            if callable(default):
+                return default(self)
+            self.__dict__[name] = default
+            return default
         if name.startswith('_'):
-            raise AttributeError(name)
-        if name not in self.values:
-            raise AttributeError(__('No such config value: %s') % name)
-        default = self.values[name][0]
-        if callable(default):
-            return default(self)
-        return default
+            msg = f'{self.__class__.__name__!r} object has no attribute {name!r}'
+            raise AttributeError(msg)
+        msg = __('No such config value: %r') % name
+        raise AttributeError(msg)
 
     def __getitem__(self, name: str) -> Any:
         return getattr(self, name)
@@ -301,46 +428,68 @@ class Config:
         delattr(self, name)
 
     def __contains__(self, name: str) -> bool:
-        return name in self.values
+        return name in self._options
 
-    def __iter__(self) -> Generator[ConfigValue, None, None]:
-        for name, value in self.values.items():
-            yield ConfigValue(name, getattr(self, name), value[1])
+    def __iter__(self) -> Iterator[ConfigValue]:
+        for name, opt in self._options.items():
+            yield ConfigValue(name, getattr(self, name), opt.rebuild)
 
-    def add(self, name: str, default: Any, rebuild: bool | str, types: Any) -> None:
-        if name in self.values:
+    def add(self, name: str, default: Any, rebuild: _ConfigRebuild,
+            types: type | Collection[type] | ENUM) -> None:
+        if name in self._options:
             raise ExtensionError(__('Config value %r already present') % name)
-        self.values[name] = (default, rebuild, types)
 
-    def filter(self, rebuild: str | Sequence[str]) -> Iterator[ConfigValue]:
+        # standardise rebuild
+        if isinstance(rebuild, bool):
+            rebuild = 'env' if rebuild else ''
+
+        # standardise valid_types
+        valid_types = _validate_valid_types(types)
+        self._options[name] = _Opt(default, rebuild, valid_types)
+
+    def filter(self, rebuild: Set[_ConfigRebuild]) -> Iterator[ConfigValue]:
         if isinstance(rebuild, str):
-            rebuild = [rebuild]
+            return (value for value in self if value.rebuild == rebuild)
         return (value for value in self if value.rebuild in rebuild)
 
     def __getstate__(self) -> dict:
         """Obtains serializable data for pickling."""
         # remove potentially pickling-problematic values from config
-        __dict__ = {}
-        for key, value in self.__dict__.items():
-            if key.startswith('_') or not is_serializable(value):
-                pass
-            else:
-                __dict__[key] = value
-
-        # create a picklable copy of values list
-        __dict__['values'] = {}
-        for key, value in self.values.items():
-            real_value = getattr(self, key)
+        __dict__ = {
+            key: value
+            for key, value in self.__dict__.items()
+            if not key.startswith('_') and is_serializable(value)
+        }
+        # create a picklable copy of ``self._options``
+        __dict__['_options'] = _options = {}
+        for name, opt in self._options.items():
+            real_value = getattr(self, name)
             if not is_serializable(real_value):
+                if opt.rebuild:
+                    # if the value is not cached, then any build that utilises this cache
+                    # will always mark the config value as changed,
+                    # and thus always invalidate the cache and perform a rebuild.
+                    logger.warning(
+                        __('cannot cache unpickable configuration value: %r'),
+                        name,
+                        type='config',
+                        subtype='cache',
+                        once=True,
+                    )
                 # omit unserializable value
                 real_value = None
-
-            # types column is also omitted
-            __dict__['values'][key] = (real_value, value[1], None)
+            # valid_types is also omitted
+            _options[name] = real_value, opt.rebuild
 
         return __dict__
 
     def __setstate__(self, state: dict) -> None:
+        self._overrides = {}
+        self._options = {
+            name: _Opt(real_value, rebuild, ())
+            for name, (real_value, rebuild) in state.pop('_options').items()
+        }
+        self._raw_config = {}
         self.__dict__.update(state)
 
 
@@ -373,6 +522,29 @@ def eval_config_file(filename: str, tags: Tags | None) -> dict[str, Any]:
     return namespace
 
 
+def _validate_valid_types(
+    valid_types: type | Collection[type] | ENUM, /,
+) -> tuple[()] | tuple[type, ...] | frozenset[type] | ENUM:
+    if not valid_types:
+        return ()
+    if isinstance(valid_types, (frozenset, ENUM)):
+        return valid_types
+    if isinstance(valid_types, type):
+        return frozenset((valid_types,))
+    if isinstance(valid_types, set):
+        return frozenset(valid_types)
+    if not isinstance(valid_types, tuple):
+        try:
+            valid_types = tuple(valid_types)
+        except TypeError:
+            logger.warning(__('Failed to convert %r to a set or tuple'), valid_types)
+            return valid_types  # type: ignore[return-value]
+    try:
+        return frozenset(valid_types)
+    except TypeError:
+        return valid_types
+
+
 def convert_source_suffix(app: Sphinx, config: Config) -> None:
     """Convert old styled source_suffix to new styled one.
 
@@ -388,7 +560,7 @@ def convert_source_suffix(app: Sphinx, config: Config) -> None:
         config.source_suffix = {source_suffix: None}  # type: ignore[attr-defined]
     elif isinstance(source_suffix, (list, tuple)):
         # if list, considers as all of them are default filetype
-        config.source_suffix = {s: None for s in source_suffix}  # type: ignore[attr-defined]
+        config.source_suffix = dict.fromkeys(source_suffix, None)  # type: ignore[attr-defined]
     elif not isinstance(source_suffix, dict):
         logger.warning(__("The config value `source_suffix' expects "
                           "a string, list of strings, or dictionary. "
@@ -463,7 +635,7 @@ def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
     if copyright_line[4] != '-':
         return copyright_line
 
-    if copyright_line[5:9].isdigit() and copyright_line[9] in ' ,':
+    if copyright_line[5:9].isdigit() and copyright_line[9:10] in {'', ' ', ','}:
         return copyright_line[:5] + replace_year + copyright_line[9:]
 
     return copyright_line
@@ -473,54 +645,64 @@ def check_confval_types(app: Sphinx | None, config: Config) -> None:
     """Check all values for deviation from the default value's type, since
     that can result in TypeErrors all over the place NB.
     """
-    for confval in config:
-        default, rebuild, annotations = config.values[confval.name]
+    for name, opt in config._options.items():
+        default = opt.default
+        valid_types = opt.valid_types
+        value = getattr(config, name)
 
         if callable(default):
             default = default(config)  # evaluate default value
-        if default is None and not annotations:
-            continue  # neither inferable nor expliclitly annotated types
-
-        if annotations is Any:
-            # any type of value is accepted
-            pass
-        elif isinstance(annotations, ENUM):
-            if not annotations.match(confval.value):
+        if default is None and not valid_types:
+            continue  # neither inferable nor explicitly annotated types
+
+        if valid_types is Any:  # any type of value is accepted
+            continue
+
+        if isinstance(valid_types, ENUM):
+            if not valid_types.match(value):
                 msg = __("The config value `{name}` has to be a one of {candidates}, "
                          "but `{current}` is given.")
-                logger.warning(msg.format(name=confval.name,
-                                          current=confval.value,
-                                          candidates=annotations.candidates), once=True)
-        else:
-            if type(confval.value) is type(default):
-                continue
-            if type(confval.value) in annotations:
-                continue
-
-            common_bases = (set(type(confval.value).__bases__ + (type(confval.value),)) &
-                            set(type(default).__bases__))
-            common_bases.discard(object)
-            if common_bases:
-                continue  # at least we share a non-trivial base class
-
-            if annotations:
-                msg = __("The config value `{name}' has type `{current.__name__}'; "
-                         "expected {permitted}.")
-                wrapped_annotations = [f"`{c.__name__}'" for c in annotations]
-                if len(wrapped_annotations) > 2:
-                    permitted = (", ".join(wrapped_annotations[:-1])
-                                 + f", or {wrapped_annotations[-1]}")
-                else:
-                    permitted = " or ".join(wrapped_annotations)
-                logger.warning(msg.format(name=confval.name,
-                                          current=type(confval.value),
-                                          permitted=permitted), once=True)
+                logger.warning(
+                    msg.format(name=name, current=value, candidates=valid_types.candidates),
+                    once=True,
+                )
+            continue
+
+        type_value = type(value)
+        type_default = type(default)
+
+        if type_value is type_default:  # attempt to infer the type
+            continue
+
+        if type_value in valid_types:  # check explicitly listed types
+            continue
+
+        common_bases = ({*type_value.__bases__, type_value}
+                        & set(type_default.__bases__))
+        common_bases.discard(object)
+        if common_bases:
+            continue  # at least we share a non-trivial base class
+
+        if valid_types:
+            msg = __("The config value `{name}' has type `{current.__name__}'; "
+                     "expected {permitted}.")
+            wrapped_valid_types = sorted(f"`{c.__name__}'" for c in valid_types)
+            if len(wrapped_valid_types) > 2:
+                permitted = (", ".join(wrapped_valid_types[:-1])
+                             + f", or {wrapped_valid_types[-1]}")
             else:
-                msg = __("The config value `{name}' has type `{current.__name__}', "
-                         "defaults to `{default.__name__}'.")
-                logger.warning(msg.format(name=confval.name,
-                                          current=type(confval.value),
-                                          default=type(default)), once=True)
+                permitted = " or ".join(wrapped_valid_types)
+            logger.warning(
+                msg.format(name=name, current=type_value, permitted=permitted),
+                once=True,
+            )
+        else:
+            msg = __("The config value `{name}' has type `{current.__name__}', "
+                     "defaults to `{default.__name__}'.")
+            logger.warning(
+                msg.format(name=name, current=type_value, default=type_default),
+                once=True,
+            )
 
 
 def check_primary_domain(app: Sphinx, config: Config) -> None:
@@ -545,7 +727,7 @@ def check_root_doc(app: Sphinx, env: BuildEnvironment, added: set[str],
     return changed
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('config-inited', convert_source_suffix, priority=800)
     app.connect('config-inited', convert_highlight_options, priority=800)
     app.connect('config-inited', init_numfig_format, priority=800)