Several config options in this manual use import specifications for importing custom objects at various places. Synopsis has a utility function called import_object which can import an object from a file or from an import path.
To do this you write a 'spec', instead of just a module name. The import_object function decides what to do with the spec, depending on extra parameters given to it (base package and default attribute). Wherever you see mention of an import specification in this manual, it will also say whether a base package or default attribute is given to the import_object function.
'spec' must be either a string or a tuple of two strings:
A tuple of two strings means load the module from the first string, and look for an attribute using the second string. The default attribute and base package specifications make no difference in this case.
E.g.: spec is ('config.py', 'MyModule'), import_module loads the 'config.py' file, then looks for the MyModule object inside that and returns it.
One string is interpreted according to the optional arguments.
Load the module and look for the default attribute in the module and return that.
E.g.: default attribute is 'htmlPageClass', spec is 'MyPage.py', import_object loads MyPage.py and then looks for an htmlPageClass attribute in the file.
Prepend the base package and then import the module and return that.
E.g.: base package is 'Synopsis.Formatter.HTML.', spec is 'XRefPages.XRefPages', import_object loads 'Synopsis.Formatter.HTML.XRefPages' and returns the class XRefPages inside the XRefPages module as the loaded object.
Prepend the base package and import the module, then look for the default attribute in the module and return that. Note that the last element in the spec doesn't have to be a module... it could be a class or any object, as long as it has the default attribute in it.
E.g.: base package is 'Synopsis.Formatter.HTML.', default attribute is 'htmlPageClass', spec is 'XRefPages'. import_object loads 'Synopsis.Formatter.HTML.XRefPages', looks for the htmlPageClass attribute in the loaded module, and returns that. In this example the htmlPageClass attribute is actually an alias to the XRefPages class inside the module, allowing us to easily get the class object without giving all the classes the same name, i.e.:
class XRefPages:
# .. stuff ..
htmlPageClass = XRefPages