Config.validate keeps 'mdx_configs' values across different instances

[oprypin]

import mkdocs.config

# 1. OK
conf = mkdocs.config.Config(mkdocs.config.DEFAULT_SCHEMA)
conf.load_dict({'site_name': 'foo'})
conf.validate()
assert conf['mdx_configs'].get('toc') == None

# 2. OK
conf = mkdocs.config.Config(mkdocs.config.DEFAULT_SCHEMA)
conf.load_dict({'site_name': 'foo', 'markdown_extensions': [{"toc": {"permalink": "aaa"}}]})
conf.validate()
assert conf['mdx_configs'].get('toc') == {'permalink': 'aaa'}

# 3. Identical to 1 but not OK.
conf = mkdocs.config.Config(mkdocs.config.DEFAULT_SCHEMA)
conf.load_dict({'site_name': 'foo'})
conf.validate()
assert conf['mdx_configs'].get('toc') == None
# fails, actually is {'permalink': 'aaa'}

[waylan]

It took me a couple minutes but I figured out the issue. The data is not shared across instances of the mkdocs.config.config_options.MarkdownExtensions class, however, because you are using mkdocs.config.DEFAULT_SCHEMA each time, then the same instance is being reused each time. The fix you provide in #2290 certainly would address that, but I wonder if we could fix it elsewhere. After all, that fix is non-intuitive and the sort of problem I would expect to get repeated in the future (either with this option or some other options).

Of course, this matters when using the live reload server. Each reload also reloads and validates the config. A change to the config should be reflected in the reload. I wonder if perhaps we need to change the way we are loading the DEFAULT_SCHEMA so that each reload gives us a new instance of each config option class. The tricky part is that the existing API is already in use by plugins, so we need to be careful not to break backward compatibility here.

[waylan]

Perhaps we should add some sort of reset to each config option class. Of course, some options won't need it, but for those that do, each reload of the config would call the reset, which would reset any variables which hold data. That way it would just be an add-on feature and wouldn't break existing plugins. A do-nothing reset method would be defined on the base class so all subclasses would have it. Then we simply ensure it is called on each reload.

[oprypin]

I don't think I agree with your assessment that this is a general / likely recurring problem. Here it really is specific to the way mkdocs.config.config_options.MarkdownExtensions operates. It has a one-of-a-kind interaction between two config keys and the implementation just forgets that an instance of OptionallyRequired doesn't represent a value, but rather a slot for values, and so instance members can't be used for purposes specific to one particular value. While that's a little confusing, I think that this rule isn't too difficult to follow and probably has no other violations (and the reason that made it prone to violation here is specific to the 2-field interaction).

I also see that good care was taken not to accidentally mutate defaults from a schema, which could've been a whole another class of bugs and is what I suspected initially.

Anyway, so how could we make this less confusing? Make those instances actually act as classes that can themselves be instantiated? Are we delving into metaclasses?

Let me just cut myself short there,... from what I said above I just think that this doesn't require any significant rework.

And sure, you could introduce this reset, with the sole user being MarkdownExtensions. But that does nothing towards detecting preventing such bugs anyway.

[waylan]

And sure, you could introduce this reset, with the sole user being MarkdownExtensions. But that does nothing towards detecting preventing such bugs anyway.

The thinking was that potential future options or options for third party plugins could also run into this issue. True, the classes would need to make use of the rest method to get the benefits, but at least we would have an official API for it. In reality, the fix in #2290 does a "reset" as the first step of the run_validation method., but it is not some official API.

However, it is probably better to not even need to consider that when creating option classes. One simple solution that occurs to me is to regenerate the scheme each time. Therefore, in mkdocs.config.default, instead of having:

DEFAULT_SCHEME = (
    ...
)

we would have:

def get_scheme():
    return (
        ...
    )

Then where we currently make reference to mkdocs.config.DEFAULT_SCHEME, we would instead use mkdocs.config.default.get_scheme(). This would ensure that a new instance of each config option class would be used each time that the config is reloaded.