pyffi.object_models — File format description engines

Warning

The documentation of this module is very incomplete.

This module bundles all file format object models. An object model is a group of classes whose instances can hold the information contained in a file whose format is described in a particular way (xml, xsd, and possibly others).

class pyffi.object_models.MetaFileFormat

Bases: type

This metaclass is an abstract base class for transforming a file format description into classes which can be directly used to manipulate files in this format.

A file format is implemented as a particular class (a subclass of FileFormat) with class members corresponding to different (bit)struct types, enum types, basic types, and aliases.

static openfile(filename, filepaths=None)

Find filename in given filepaths, and open it. Raises IOError if file cannot be opened.

Parameters:

• filename (str) – The file to open.
• filepaths (list of strs) – List of paths where to look for the file.

class pyffi.object_models.FileFormat

Bases: object

This class is the base class for all file formats. It implements a number of useful functions such as walking over directory trees (walkData()) and a default attribute naming function (name_attribute()). It also implements the base class for representing file data (FileFormat.Data).

ARCHIVE_CLASSES

Override this with a list of archive formats that may contain files of the format.

class Data

Bases: pyffi.utils.graph.GlobalNode

Base class for representing data in a particular format. Override this class to implement reading and writing.

inspect(stream)

Quickly checks whether the stream appears to contain data of a particular format. Resets stream to original position. Call this function if you simply wish to check that a file is of a particular format without having to parse it completely.

Override this method.

Parameters:stream (file) – The file to inspect. Returns:True if stream is of particular format, False otherwise.

read(stream)

Read data of particular format from stream. Override this method.

Parameters:stream (file) – The file to read from.

user_version

User version (additional version field) of the data.

version

Version of the data.

write(stream)

Write data of particular format to stream. Override this method.

Parameters:stream (file) – The file to write to.

FileFormat.RE_FILENAME

Override this with a regular expression (the result of a re.compile call) for the file extension of the format you are implementing.

classmethod FileFormat.name_attribute(name)

Converts an attribute name, as in the description file, into a name usable by python.

Parameters:name (str) – The attribute name. Returns:Reformatted attribute name, useable by python.

>>> FileFormat.name_attribute('tHis is A Silly naME')
't_his_is_a_silly_na_m_e'
>>> FileFormat.name_attribute('Test:Something')
'test_something'
>>> FileFormat.name_attribute('unknown?')
'unknown'

classmethod FileFormat.name_class(name)

Converts a class name, as in the xsd file, into a name usable by python.

Parameters:name (str) – The class name. Returns:Reformatted class name, useable by python.

>>> FileFormat.name_class('this IS a sillyNAME')
'ThisIsASillyNAME'

classmethod FileFormat.name_parts(name)

Intelligently split a name into parts:

• first, split at non-alphanumeric characters
• next, seperate digits from characters
• finally, if some part has mixed case, it must be camel case so split it further at upper case characters

>>> FileFormat.name_parts("hello_world")
['hello', 'world']
>>> FileFormat.name_parts("HELLO_WORLD")
['HELLO', 'WORLD']
>>> FileFormat.name_parts("HelloWorld")
['Hello', 'World']
>>> FileFormat.name_parts("helloWorld")
['hello', 'World']
>>> FileFormat.name_parts("xs:NMTOKEN")
['xs', 'NMTOKEN']
>>> FileFormat.name_parts("xs:NCName")
['xs', 'N', 'C', 'Name']
>>> FileFormat.name_parts('this IS a sillyNAME')
['this', 'IS', 'a', 'silly', 'N', 'A', 'M', 'E']
>>> FileFormat.name_parts('tHis is A Silly naME')
['t', 'His', 'is', 'A', 'Silly', 'na', 'M', 'E']

static FileFormat.version_number(version_str)

Converts version string into an integer. This default implementation simply returns zero at all times, and works for formats that are not versioned.

Override for versioned formats.

Parameters:version_str (str) – The version string. Returns:A version integer.

classmethod FileFormat.walk(top, topdown=True, mode='rb')

A generator which yields all files in directory top whose filename matches the regular expression RE_FILENAME. The argument top can also be a file instead of a directory. Errors coming from os.walk are ignored.

Note that the caller is not responsible for closing the stream.

This function is for instance used by pyffi.spells to implement modifying a file after reading and parsing.

Parameters:

• top (str) – The top folder.
• topdown (bool) – Determines whether subdirectories should be iterated over first.
• mode (str) – The mode in which to open files.

classmethod FileFormat.walkData(top, topdown=True, mode='rb')

A generator which yields the data of all files in directory top whose filename matches the regular expression RE_FILENAME. The argument top can also be a file instead of a directory. Errors coming from os.walk are ignored.

Note that the caller is not responsible for closing the stream.

This function is for instance used by pyffi.spells to implement modifying a file after reading and parsing.

Parameters:

• top (str) – The top folder.
• topdown (bool) – Determines whether subdirectories should be iterated over first.
• mode (str) – The mode in which to open files.