Interface Specification for FileAPI

Overview

The FileAPI provides a specification for general file-like objects, allowing for the expected read/write interface.

For normal Python file-like objects, the read/write mode is determined when the file is opened, typically with the open() function, which returns the file-like object. The FileAPI interface specifies a slightly different paradigm. Here, you get a file-like object through some other mechanism (e.g. the namespace), and then call the open() method on the object, specifying read or write semantics at that time.

Type Definitions

The following non-OBJECT types are defined by this interface:

Strings

An alias for SEQUENCE OF String

OptionalString

An alias for OPTIONAL String (i.e. a union with NULL)

Exceptions

The following exceptions are defined by this interface:

FileIOError

Exception is raised when any file operation fails.

File Objects

The File object provides a basic file-lock object abstraction. This object has the following methods:

open (mode : String)

Opens the file for reading or writing. mode can be one of the following strings:

• "r" -- open the file for reading
• "w" -- open the file for writing (with truncation)
• "a" -- open the file for appending

Assuming the underlying object implementation supports this, mode can also be "r+", "w+", or "a+" which open the file for updating. mode may also have an optional b flag for opening the file in binary mode.

This method can raise FileIOError if any error occurred while opening the file. Possible error conditions include:

• A file opened for reading does not exist
• Insufficient permission
• An underlying OS resource error (i.e. not enough disk space or inodes)

close ()

Closes the file. Raises FileIOError exception if any problems occurred during the close.

flush ()

Flushes any buffered output. Raises FileIOError exception if any problems occurred during the flush.

read (size : INTEGER) : String

Reads size number of bytes from the file, Returning the bytes read as a String (TBD: this should really return a SEQUENCE OF BYTE!). At EOF, the empty string is returned. If size is negative, reads until EOF. Raises FileIOError if any errors occurred during the read.

readline () : String

Reads a single line and returns it as a String At EOF, the empty string is returned. Raises FileIOError if any errors occurred during the read.

readlines () : Strings

Reads all lines, returning them as a sequence of Strings. At EOF, the empty list is returned. Raises FileIOError if any errors occurred during the read.

seek (offset : INTEGER, whence : INTEGER)

Seeks the file pointer, but only if the underlying implementation supports it. Raises FileIOError if there are any errors occurred during the seek.

whence can be any of the following values:

• 0 -- offset is an absolute file position.
• 1 -- offset is relative to the current file position.
• 2 -- offset is relative to the file's end.

tell () : INTEGER

Returns the file's current position, but only if the underlying implementation supports it. Raises FileIOError if any errors occur.

write (text : String)

Writes the text string to the file. Raises FileIOError if any error occurred during the write.

writelines (lines : Strings)

Writes a list of text strings to the file. Raises FileIOError if any error occurred during the write.