Package grizzled :: Package file :: Module includer
[hide private]
[frames] | no frames]

Module includer

source code

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"))
Classes [hide private]
  IncludeError
Thrown by Includer when an error occurs while processing the file.
  Includer
An Includer object preprocesses a path or file-like object, expanding include references.
Functions [hide private]
string
preprocess(file_or_url, output=None, temp_suffix='.txt', temp_prefix='inc')
Process all include directives in the specified file, returning a path to a temporary file that contains the results of the expansion.
source code
 
_complain_if_closed(closed) source code
Variables [hide private]
  log = logging.getLogger('includer')
  __package__ = 'grizzled.file'
Function Details [hide private]

preprocess(file_or_url, output=None, temp_suffix='.txt', temp_prefix='inc')

source code 
Process all include directives in the specified file, returning a path to a temporary file that contains the results of the expansion. The temporary file is automatically removed when the program exits, though the caller is free to remove it whenever it is no longer needed.
Parameters:
  • file_or_url (file or str) - URL or path to file to be expanded; or, a file-like object
  • output (file) - A file or file-like object to receive the output.
  • temp_suffix (str) - suffix to use with temporary file that holds preprocessed output
  • temp_prefix (str) - prefix to use with temporary file that holds preprocessed output
Returns: string
output, if output is not None; otherwise, the path to temporary file containing expanded content