plasTeX 3.0 — A Python Framework for Processing LaTeX Documents: Configuration Option Types

6.2.3 Configuration Option Types

class ConfigOption[T](description, options, default )

This class represents an option whose value has a “simple” type. Specifically, we require T(s) to correctly converts a string s to an object of type T. The type is determined at runtime based on the type of the default value. More complex options should inherit this class.

From the point of view of the external API, every option item is expected to inherit ConfigOption, and is expected to implement the methods described below correctly. Moreover, the instance attribute value is expected to hold the value of the option.

On the other hand, custom __init__ implementations are not required to set the other instance attributes (i.e. description, options and name) described below.



description: description of this option to be used in the plastex --help output.



options: space separated list of command line argument that correspond to this option. The behaviour of this variable may be customized by implementations of ConfigOption.

name

the key used by argparse to store the value read from the command line. Note that argparse does not group the argument values by section, so one has to be careful to avoid collision.

This is set to the first entry in self.option with leading -s stripped.



value: the actual value of the option






registerArgparse(group ): this function should add the command line arguments for this configuration to the argparse._ArgumentGroup object group .






updateFromDict(data ): sets the value of the option based on the data in data . The format of data is defined to be what is returned by vars(parser.parse_args()), where parser is populated by registerArgparse. This is intended to be used in conjuction with registerArgparse.

class BooleanConfigOption([ConfigOption arguments] )

Boolean options are simply options that allow you to specify an ‘on’ or ‘off’ state. In a config file, the value is converted to a boolean via the builtin bool function. Boolean options on the command-line do not take an argument; simply specifying the option sets the state to true.

One interesting feature of boolean options is in specifying the command-line options. Since you cannot specify a value on the command-line (the existence of the option indicates the state), there must be a way to set the state to false. This is done using the ‘not’ operator (!). When specifying the options argument of the constructor, if you prefix an command-line option with an exclamation point, the existence of that option indicates a false state rather than a true state. Below is an example of an options value that has a way to turn debugging information on (--debug) or off (--no-debug).

BooleanOption("", options = '--debug !--no-debug', default=True)




class FloatOption([ConfigOption arguments] ): A FloatOption is an option that accepts a floating point number.




class IntegerOption([ConfigOption arguments] ): An IntegerOption is an option that accepts an integer value.




class StringOption([ConfigOption arguments] ): A StringOption is an option that accepts an arbitrary string.

class MultiStringOption([ConfigOption arguments] )

A MultiStringOption is an option that is intended to be used multiple times on the command-line, or take a list of values. Other options when specified more than once simply overwrite the previous value. MultiStringOptions will append the new values to a list.

In the configuration file, this is a space separated list, interpreted in the same ways as shell arguments (with the same escaping/quoting rules for strings that contains whitespaces). In fact, it is processed by shlex.split.

The individual values of MultiStringOption are strings. This can, of course, be made generic, but such a use case has not arisen.

class DictOption[T]([ConfigOption arguments] )

This is an abstract base class for options whose value is a Dict[str, T]. This receives special treatment by ConfigManager.read — in a config file, any line whose key is unrecognized (i.e. not the key of an existing option) is added to the first DictOption in the section. Usually, such sections only contain a single option which is a DictOption.

The value can also be set directly, in the form

data=a=b,c=d,e=f

There is no implementor in ConfigManager.py, but is used by CountersOption , LinksOption , ImageScaleOption and LogOption in Config.py.

Note that all implementors of DictOption must also implement registerArgparse (and can optionally implement other methods of ConfigOption).






entryFromString(entry ): a class method to convert a string to the desired value entry. This is used by the in the default implementation of set.






set(key, value ): sets the value of the dict. The value is assumed to be a string.