options expects you to define all feasible and legitimate options at the
class level, and to give them reasonable defaults.
None of the initial settings ever have magic applied. Much of the expected interpretation “magic” will be relative settings, and relative settings require a baseline value. The top level is expected and demanded to provide a reasonable baseline.
Any options set “further down” such as when an instance is created or a method called should set keys that were already-defined at the class level.
However, there are cases where “extra”
**kwargs values may be
provided and make sense. Your object might be a very high level
entry point, for example, representing very large buckets of
functionality, with many options. Some of those options are relevant
to the current instance, while others are intended as pass-throughs
for lower-level modules/objects. This may seem a doubly rarefied
case–and it is, relatively speaking. But it does happen–and when you need multi-level
processing, it’s really, really super amazingly handy to have it.
options supports this in its core
push() method by taking
the values that are known to be part of the class’s options, and
deleting those from
kwargs. Any values left over in the
dict are either errors, or intended for other recipients.
As yet, there is no automatic check for leftovers.