Class Configuration

source code

The session's configuration is managed through this object.

The session can be configured using the SetParameter() method. However,
sometimes when a certain parameter is modified, some code needs to run in
response. For example, if the filename is modified, the profile must be
recalculated.

It is not sufficient to attach setter methods to every such parameter
though, because there is no guarantee which order these parameters are
configured. For example, suppose we want to set both the filename and the
profile:

session.SetParameter("filename", filename)
session.SetParameter("profile", "nt/...")

Since the profile is explicitly set we should not guess it, but if a simple
set hook is used, there is no way for the _set_filename() hook to determine
that the profile is explicitly given. So what will happen now is that the
filename will be changed, then a profile will be autodetected, then it will
be immediately overwritten with the user set profile.

To avoid this issue we use a context manager to essentially group
SetParameter() calls into an indivisible unit. The hooks are all run _after_
all the parameters are set:

with session:
    session.SetParameter("filename", filename)
    session.SetParameter("profile", "nt/...")

Now the _set_filename() hook can see that the profile is explicitly set so
it should not be auto-detected.

Upon entering the context manager, we create a new temporary place to store
configuration parameters. Then, when exiting the context manager we ensure
that those parameters with hooks are called. The hooks are passed the newly
set parameters. Each hook returns the value that will actually be set in the
session (so the hook may actually modify the value).

new empty dictionary