source: nappy/trunk/notes_on_improving_write_api.txt @ 3427

Proposed change to NAppy so write is separated out from openNAFile() ====================================================================

Currently when you do:

>>> x = openNAFile("myfile.na", "w", na_dict)

the NASA Ames file is opened and na_dict is written to it all in that one action.

We propose that it would make more sense to split the process into stages as follows:

>>> x = openNAFile("myfile.na", "w")
>>> x.write(na_dict)
>>> x.close()

NOTE: need to include the following safety measures:

1. No writing is done:

>>> x = openNAFile("myfile.na", "w")
>>> x.close()

Means that myfile.na is a zero-sized file - which is probably OK.

2. User tries to write to closed file:

>>> x = openNAFile("myfile.na", "w")
>>> x.write(na_dict)
>>> x.close()

>>> x.write(na_dict_2)
WARNING! NASA Ames file instance is closed and cannot be written to.

3. User tries to write multiple na_dict objects to the file:

>>> x = openNAFile("myfile.na", "w")
>>> x.write(na_dict_1)
>>> x.write(na_dict_2)
WARNING! Cannot write multiple NASA Ames dictionaries to a single file. Please open a new NASA Ames file instance to write new data to.

Also, I propose that we always do an x.file.flush() to make sure the data was written so even if user doesn't do x.close() before the process ends the data will always have been written.

4. If opened as read only then disable write:

>>> x = openNAFile("myfile.na")
>>> x.write(na_dict)
WARNING: You cannot write to a read-only file! If you want to write to a file you must open with 'mode="w"'.