Top

grizzled.file.includer module

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"

Relative and local file references are relative to the including file. That is, 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".

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

Functions

def preprocess(

file, encoding='utf8', 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. 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 (file or str): path to file to be expanded, or file-like object
  • encoding (str): String encoding for input file. Defaults to UTF-8.
  • 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

output, if output is not None; otherwise, the path to temporary file containing expanded content

Classes

class IncludeError

Thrown by Includer when an error occurs while processing the file. An IncludeError object always contains a single string value that contains an error message describing the problem.

Ancestors (in MRO)

  • IncludeError
  • builtins.Exception
  • builtins.BaseException
  • builtins.object

Class variables

var args

Static methods

def __init__(

self, message)

Initialize self. See help(type(self)) for accurate signature.

Instance variables

var message

class Includer

An Includer object preprocesses a path or file-like object, expanding include references. The resulting Includer object is a file-like object, offering the same methods and capabilities as an open file.

By default, Includer supports this include syntax:

%include "path"
%include "url"

However, the include directive syntax is controlled by a regular expression, so it can be configured.

See the module documentation for details.

Ancestors (in MRO)

Static methods

def __init__(

self, source, include_regex='^%include\\s"([^"]+)"', max_nest_level=100, output=None, encoding='utf-8')

Create a new Includer object.

Parameters

  • source (file or str): The source to be read and expanded. May be an open file-like object or a path name.
  • include_regex (str): Regular expression defining the include syntax. Must contain a single parenthetical group that can be used to extract the included file.
  • max_nest_level (int): Maximum include nesting level. Exceeding this level will cause Includer to throw an IncludeError.
  • output (str or file): A string (path name) or file-like object to which to save the expanded output.
  • encoding (str): The encoding to use to open the files. Defaults to "utf-8".

Raises

IncludeError on error

def close(

self)

Close the includer, preventing any further I/O operations.

def fileno(

self)

Get the file descriptor. Returns the descriptor of the file being read.

def flush(

self)

No-op.

def getvalue(

self)

Retrieve the entire contents of the file, as a string, with includes expanded, at any time before the close() method is called.

def isatty(

self)

Determine whether the file being processed is a TTY or not.

def read(

self, n=-1)

Read n bytes from the open file.

Parameters

  • n (int): Number of bytes to read. A negative number instructs the method to read all remaining bytes.

Returns

the bytes read

def readline(

self, length=-1)

Read the next line from the file.

Parameters

  • length (int): a length hint, or negative if you don't care

Returns

the line read

def readlines(

self, sizehint=0)

Read all remaining lines in the file.

def seek(

self, pos, mode=0)

Seek to the specified file offset in the include-processed file.

Parameters

  • pos (int): file offset
  • mode (int): the seek mode, as specified to a Python file's seek() method

def tell(

self)

Get the current file offset.

Returns

the current file offset

def truncate(

self, size=None)

Not supported, since Includer objects are read-only.

def write(

self, s)

Not supported, since Includer objects are read-only.

def writelines(

self, iterable)

Not supported, since Includer objects are read-only.

Instance variables

var closed

var mode

var name

Get the name of the file being processed.

class MaxNestingExceededError

Thrown by Includer when the maximum include file nesting level is exceeded.

Ancestors (in MRO)

Class variables

var args

Static methods

def __init__(

self, message)

Inheritance: IncludeError.__init__

Initialize self. See help(type(self)) for accurate signature.