API Documentation

ConfigConvert is a set of ConversionKit converters designed specifically to help you create Python objects from options set in a text file.

exception configconvert.ConfigFileError

configconvert.existingDirectory(try_to_create=False, raise_on_create_error=False, uniform_path=False)

Ensure the directory specified as the input exists and is not a file, otherwise set an error.

If try_to_create is True, the converter will try to create the directory if it doesn’t exist. In that case you can set raise_on_create_error to True to have any problems creating the directory trigger an exception instead of setting a conversion error.

If the directory exists (or has been created) the directory path is set as the conversion result. If uniform_path is set to True, the absolute, normalized path is set instead of the value given as the input.

configconvert.existingFile(try_to_create=False, raise_on_create_error=False, file_content='', uniform_path=False)

Ensure the file specified as the input exists and is not a directory, otherwise set an error.

If try_to_create is True, the converter will try to create the file if it doesn’t exist with the content file_content which defaults to ‘’`. The file is opened with mode 'wb' (write binary) so the contents of file_content should be a binary string in the encoding you wish to use. If the content is an ordinary Python string, that is fine. If it is a Unicode string you’ll need to encode it to an appropriate format first. For example:

existingFile(try_to_create=True, file_content=unicode_string.encode('utf8'))

If you have set try_to_create to True you can set raise_on_create_error to True so that any problems which are encountered when creating the file trigger an exception instead of setting a conversion error.

If the file exists (or has been created) the file path is set as the conversion result. If uniform_path is set to True, the absolute, normalized path is set instead of the value given as the input.

configconvert.handle_option_error(conversion, base=None)

configconvert.handle_section_error(flow, option, example)

configconvert.parse_config(filename, encoding='utf8')

Parse a config file with a strict format.

The config file is made of options and values which are each defined on a single line terminated by a \n character and separtated by only the three characters space equals space. For example:

option = value

The parsed config file results in a dictionary with the options as ASCII strings for the keys and the values as unicode strings for the values. The options must start with the letters a-z, A-Z or _ and should contain only letters, numbers or the _ character. Thus the option values have the same naming rules as Python variables.

If you don’t leave a space each side of the = character it is considered a syntax error. Any extra space characters after the space after the equals sign are treated as part of the value. For example this:

option =  value

would result in the option 'option' taking the value u' value'. Any extra spaces after the option name are ignored though.

The file must use UNIX style line endings (ie each line ends in \n) and must be encoded as UTF-8. Values can therefore take any Unicode character as long as the file is encoded correctly.

You can also specify multiline values. You do so by specifying the first line of the multiline value on the same line as the option starting immediately after the space after the equals sign (once again any extra spaces will be treated as part of the value). All subsequent lines have to be indented 4 spaces. Any characters after those 4 spaces are treated as part of the line. In fact the first line doesn’t have to contain any text if you are using a multiline value, in which case the value will start with a \n character. Here are two examples:

option1 = This
    is
        a
    multiline string
option2 = 
    and
    so is this

Note: The implementation doesn’t enforce all the option naming conventions yet

configconvert.split_options(options)

configconvert.stringToObject()

Takes a string written in the format "path.to.module:object" and returns the object.

configconvert.unicodeToObject()

Takes a string written in the format "path.to.module:object" and returns the object.