Clarify that Private config can be accessed, add a type annotation …

…to `mdx_configs`

mkdocs/config/config_options.py

@@ -821,14 +821,10 @@ def _repr_item(cls, value) -> str:
  return f"a {type(value).__name__}: {value!r}"
 
 
-class Private(BaseConfigOption):
- """
- Private Config Option
-
- A config option only for internal use. Raises an error if set by the user.
- """
+class Private(Generic[T], BaseConfigOption[T]):
+ """A config option that can only be populated programmatically. Raises an error if set by the user."""
 
- def run_validation(self, value: object):
+ def run_validation(self, value: object) -> None:
  if value is not None:
  raise ValidationError('For internal use only.')
 
@@ -855,7 +851,7 @@ def __init__(
  self.builtins = builtins or []
  self.configkey = configkey
 
- def validate_ext_cfg(self, ext, cfg):
+ def validate_ext_cfg(self, ext: object, cfg: object) -> None:
  if not isinstance(ext, str):
  raise ValidationError(f"'{ext}' is not a valid Markdown Extension name.")
  if not cfg:
@@ -864,7 +860,7 @@ def validate_ext_cfg(self, ext, cfg):
  raise ValidationError(f"Invalid config options for Markdown Extension '{ext}'.")
  self.configdata[ext] = cfg
 
- def run_validation(self, value: object):
+ def run_validation(self, value: object) -> list[str]:
  self.configdata: dict[str, dict] = {}
  if not isinstance(value, (list, tuple, dict)):
  raise ValidationError('Invalid Markdown Extensions configuration')

mkdocs/config/defaults.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Dict
+
 from mkdocs.config import base
 from mkdocs.config import config_options as c
 
@@ -97,7 +99,7 @@ class MkDocsConfig(base.Config):
  )
  """PyMarkdown extension names."""
 
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
  """PyMarkdown Extension Configs. For internal use only."""
 
  strict = c.Type(bool, default=False)

mkdocs/tests/config/config_options_tests.py

@@ -8,7 +8,7 @@
 import sys
 import textwrap
 import unittest
-from typing import TYPE_CHECKING, Any, List, Optional, TypeVar
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, TypeVar
 from unittest.mock import patch
 
 if TYPE_CHECKING:
@@ -1213,7 +1213,7 @@ def test_warns_for_dict(self) -> None:
 class PrivateTest(TestCase):
  def test_defined(self) -> None:
  class Schema(Config):
- option = c.Private()
+ option = c.Private[Any]()
 
  with self.expect_error(option="For internal use only."):
  self.get_config(Schema, {'option': 'somevalue'})
@@ -1380,21 +1380,22 @@ class MarkdownExtensionsTest(TestCase):
  def test_simple_list(self, mock_md) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions()
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': ['foo', 'bar'],
  }
  conf = self.get_config(Schema, config)
  assert_type(conf.markdown_extensions, List[str])
+ assert_type(conf.mdx_configs, Dict[str, dict])
  self.assertEqual(conf.markdown_extensions, ['foo', 'bar'])
  self.assertEqual(conf.mdx_configs, {})
 
  @patch('markdown.Markdown')
  def test_list_dicts(self, mock_md) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions()
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': [
@@ -1417,7 +1418,7 @@ class Schema(Config):
  def test_mixed_list(self, mock_md) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions()
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': [
@@ -1438,7 +1439,7 @@ class Schema(Config):
  def test_dict_of_dicts(self, mock_md) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions()
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': {
@@ -1461,7 +1462,7 @@ class Schema(Config):
  def test_builtins(self, mock_md) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions(builtins=['meta', 'toc'])
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': ['foo', 'bar'],
@@ -1473,7 +1474,7 @@ class Schema(Config):
  def test_duplicates(self) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions(builtins=['meta', 'toc'])
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': ['meta', 'toc'],
@@ -1485,7 +1486,7 @@ class Schema(Config):
  def test_builtins_config(self) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions(builtins=['meta', 'toc'])
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': [
@@ -1500,7 +1501,7 @@ class Schema(Config):
  def test_configkey(self, mock_md) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions(configkey='bar')
- bar = c.Private()
+ bar = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': [
@@ -1519,7 +1520,7 @@ class Schema(Config):
  def test_missing_default(self) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions()
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  conf = self.get_config(Schema, {})
  self.assertEqual(conf.markdown_extensions, [])
@@ -1528,7 +1529,7 @@ class Schema(Config):
  def test_none(self) -> None:
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions(default=[])
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  config = {
  'markdown_extensions': None,
@@ -1603,7 +1604,7 @@ def test_multiple_markdown_config_instances(self) -> None:
  # config instances that didn't specify extensions.
  class Schema(Config):
  markdown_extensions = c.MarkdownExtensions()
- mdx_configs = c.Private()
+ mdx_configs = c.Private[Dict[str, dict]]()
 
  conf = self.get_config(
  Schema,