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"))