Module history_medium
Module history_medium defines class HistoryMedium and four of its
children, Memory, Event, TextFile, and ColumnarFile. Other history media can be defined by
the user to connect to other file formats.
An instance of HistoryMedium is an object that can store records, each
record consisting of series of name and value pairs. Different children of HistoryMedium
are available for storing these records in different media and formats. Four media are
supplied by default: Memory, TextFile, ColumnarFile, and Event.
When a name and value pair is written to a specific medium, it may be
necessary to map the name onto one which is accepted by that particular medium. For that
purpose method external_name can be redefined in heirs.
Normally users do not use this module directly. Instead, they use the
tag-creating functions in modules "history", "columnar_history", and
other heirs of HistoryMedium. (See Creating New Media,
below.)
Attributes
registry -- a map of external names to cycle last written
is_open -- true if the record is currently open
record_number -- number of calls that have been made to
end_record ()
cycle, time -- latest arguments to begin_record (cycle,
time) (After an end_record(), cycle and registry[name] should agree in all cases)
Methods
Normally, the user does not invoke these routines directly, but rather by calling the
sample methods in class HistoryCollector, usually on the standard collector.
begin_record (cycle, time) begins the collection of
history items at a given cycle and time.
end_record () completes the collection of history items at the time
and cycle given by the previous call to begin_record.
write (name, value) writes the value to the medium
under the calculated from name by method external_name.
external_name (name) calculates a legal name for the
particular medium from the desired name. The default version of this routine in
HistoryMedium simply returns name.
history (name) returns the history named
name, if supported in the medium. Otherwise an exception is thrown.
Columnar text files are suitable for recording small numbers of scalar-valued
quantities sampled over time.
TextFile (filename = None)
returns an instance of a history medium based on a columnar text file with the given
name.If no file name is given at creation, set_name must be called before use.
set_name (name) must be called when is_open
is false. It sets the name of the text file to be used for future records. This method may
be called between records to begin using a new file to store records, typically to prevent
a file from becoming too large.
history (name) is unsupported, and will throw an exception.
Columnar text files are suitable for recording small numbers of scalar-valued
quantities sampled over time.
ColumnarFile (filename = None)
returns an instance of a history medium based on a columnar text file with the given
name.If no file name is given at creation, set_name must be called before use.
set_name (name) must be called when is_open
is false. It sets the name of the text file to be used for future records. This method may
be called between records to begin using a new file to store records, typically to prevent
a file from becoming too large.
history (name) is unsupported, and will throw an exception.
Class Memory
Class Memory is a medium that stores histories in memory. Obviously, the user must be
careful not to define items that will use too much memory. Class Memory supports the
history(name) method from class Tag.
Memory () creates a instance of class Memory.
history (name) returns the current history stored as name.
Class Event
Events are a peculiar sort of history medium: they never store anything. Instead,
events are used in event tags which can be used as a general trigger mechanism for periods
events and data-driven events.
Event () creates an instance of Event. Event's _write method simplies
does nothing.
history (name) is unsupported, and will throw an exception.
The recommended way to add a new medium is to create a new module which does
from history import *
and to add to it a child of HistoryMedium and a tag-creating function similar
to textfile_tag. See history.py and pdb_history.py for examples. Usually you would redefine at least begin_record,
end_record, _write, and __repr__. The method _write is
where you catch the individual name and value pairs to be written for each record. The
actual deed of writing onto your medium of choice might occur there or in end_record.
