Introduction
The grizzled.file.includer module contains a class that can be used to
process includes within a text file, returning a file-like object. It also
contains some utility functions that permit using include-enabled files in
other contexts.
Include Syntax
The include syntax is defined by a regular expression; any line that matches
the regular expression is treated as an include directive. The default
regular expression matches include directives like this:
%include "/absolute/path/to/file"
%include "../relative/path/to/file"
%include "local_reference"
%include "http://localhost/path/to/my.config"
Relative and local file references are relative to the including file or URL.
That, if an Includer is processing file "/home/bmc/foo.txt" and encounters
an attempt to include file "bar.txt", it will assume "bar.txt" is to be found
in "/home/bmc".
Similarly, if an Includer is processing URL "http://localhost/bmc/foo.txt"
and encounters an attempt to include file "bar.txt", it will assume "bar.txt"
is to be found at "http://localhost/bmc/bar.txt".
Nested includes are permitted; that is, an included file may, itself, include
other files. The maximum recursion level is configurable and defaults to 100.
The include syntax can be changed by passing a different regular expression to
the Includer class constructor.
Usage
This module provides an Includer class, which processes include directives
in a file and behaves like a file-like object. See the class documentation for
more details.
The module also provides a preprocess() convenience function that can be
used to preprocess a file; it returns the path to the resulting preprocessed
file.
Examples
Preprocess a file containing include directives, then read the result:
import includer
import sys
inc = includer.Includer(path)
for line in inc:
sys.stdout.write(line)
Use an include-enabled file with the standard Python logging module:
import logging
import includer
logging.fileConfig(includer.preprocess("mylog.cfg"))