What’s new in PyTables 1.0¶
| Author: | Francesc Altet |
|---|---|
| Contact: | faltet@carabos.com |
| Author: | Ivan Vilata i Balaguer |
| Contact: | ivilata@carabos.com |
This document details the modifications to PyTables since version 0.9.1. Its main purpose is help you ensure that your programs will be runnable when you switch from PyTables 0.9.1 to PyTables 1.0.
API additions¶
- The new
Table.col()method can be used to get a column from a table as aNumArrayorCharArrayobject. This is preferred over the syntaxtable['colname']. - The new
Table.readCoordinates()method reads a set of rows given their indexes into an in-memory object. - The new
Table.readAppend()method Append rows fullfilling the condition to a destination table.
Backward-incompatible changes¶
- Trying to open a nonexistent file or a file of unknown type raises
IOErrorinstead ofRuntimeError. Using an invalid mode raisesValueErrorinstead ofRuntimeError. - Getting a child node from a closed group raises
ValueErrorinstead ofRuntimeError. - Running an action on the wrong type of node now (i.e. using
file.listNodes()on a leaf) raises aTypeErrorinstead of aNodeError. - Removing a non-existing child now raises a
NoSuchNodeError, instead of doing nothing. - Removing a non-empty child group using
del group.childfails with aNodeErrorinstead of recursively doing the removal. This is because of the potential damage it may cause when used inadvertently. If a recursive behavior is needed, use the_f_remove()method of the child node. - The recursive flag of
Group._f_walkNodes()isTrueby default now. Before it wasFalse. - Now, deleting and getting a non-existing attribute raises an
AttributeErrorinstead of aRuntimeError. - Swapped last two arguments of
File.copyAttrs()to match the other methods. Please useFile.copyNodeAttrs()anyway. - Failing to infer the size of a string column raises
ValueErrorinstead ofRuntimeError. - Excessive table column name length and number of columns now raise
ValueErrorinstead ofIndexErrorandNameError. - Excessive table row length now raises
ValueErrorinstead ofRuntimeError. table[integer]returns anumarray.records.Recordobject instead of a tuple. This was the original behavior before PyTables 0.9 and proved to be more consistent than the last one (tables do not have an explicit ordering of columns).- Specifying a nonexistent column in
Table.read()raises aValueErrorinstead of aLookupError. - When
start >= stopan empty iterator is returned byTable.iterrows()instead of an emptyRecArray. Thanks to Ashley Walsh for noting this. - The interface of
isHDF5File()andisPyTablesFile()file has been unified so that they both return true or false values on success and raiseHDF5ExtErroror errors. The true value inisPyTablesFile()is the format version string of the file. Table.whereIndexed()andTable.whereInRange()are now private methods, since theTable.where()method is able to choose the most adequate option.- The global variables
ExtVersionandHDF5Versionhave been renamed toextVersionandhdf5Version, respectively. whichLibVersion()returnsNoneon querying unavailable libraries, and raisesValueErroron unknown ones.
The following modifications, though being (strictly speaking) modifications of the API, will most probably not cause compatibility problems (but your mileage may vary):
The default values for
nameandclassnamearguments inFile.getNode()are nowNone, although the empty string is still allowed for backwards compatibility. File hierarchy manipulation and attribute handling operations using those arguments have changed to reflect this.Copy operations (
Group._f_copyChildren(),File.copyChildren(),File.copyNode()...) do no longer return a tuple with the new node and statistics. Instead, they only return the new node, and statistics are collected via an optional keyword argument.The
copyFile()function inFile.pyhas changed its signature from:copyFile(srcfilename=None, dstfilename=None, title=None, filters=None, copyuserattrs=True, overwrite=False, stats=None)
to:
copyFile(srcfilename, dstfilename, overwrite=False, **kwargs)
Thus, the function allows the same options as
File.copyFile().The
File.copyFile()method has changed its signature from:copyFile(self, dstfilename=None, title=None, filters=None, copyuserattrs=1, overwrite=0, stats=None):to:
copyFile(self, dstfilename, overwrite=False, **kwargs)
This enables this method to pass on arbitrary flags and options supported by copying methods of inner nodes in the hierarchy.
The
File.copyChildren()method has changed its signature from:copyChildren(self, wheresrc, wheredst, recursive=False, filters=None, copyuserattrs=True, start=0, stop=None, step=1, overwrite=False, stats=None)
to:
copyChildren(self, srcgroup, dstgroup, overwrite=False, recursive=False, **kwargs):Thus, the function allows the same options as
Group._f_copyChildren().The
Group._f_copyChildren()method has changed its signature from:_f_copyChildren(self, where, recursive=False, filters=None, copyuserattrs=True, start=0, stop=None, step=1, overwrite=False, stats=None)
to:
_f_copyChildren(self, dstgroup, overwrite=False, recursive=False, **kwargs)
This enables this method to pass on arbitrary flags and options supported by copying methods of inner nodes in the group.
Renamed
srcFilenameanddstFilenamearguments incopyFile()andFile.copyFile()tosrcfilenameanddstfilename, respectively. RenamedwhereSrcandwhereDstarguments inFile.copyChildren()towheresrcandwheredst, respectively. RenameddstNodeargument inFile.copyAttrs()todstnode. Tose arguments should be easier to type in interactive sessions (although 99% of the time it is not necessary to specify them).Renamed
objectargument inEArray.append()tosequence.The
rowsargument inTable.append()is now compulsory.The
startargument inTable.removeRows()is now compulsory.
API refinements¶
The
isHDF5()function has been deprecated in favor ofisHDF5File().Node attribute-handling methods in
Filehave been renamed for a better coherence and understanding of their purpose:getAttrNode()is now calledgetNodeAttr()setAttrNode()is now calledsetNodeAttr()delAttrNode()is now calleddelNodeAttr()copyAttrs()is now calledcopyNodeAttrs()
They keep their respective signatures, and the old versions still exist for backwards compatibility, though they issue a
DeprecationWarning.Using
VLArray.append()with multiple arguments is now deprecated for its ambiguity. You should put the arguments in a single sequence object (list, tuple, array...) and pass it as the only argument.Using
table['colname']is deprecated. Usingtable.col('colname')(with the newcol()method) is preferred.
Bug fixes (affecting API)¶
Table.iterrows()returns an empty iterator when no rows are selected, instead of returningNone.
Enjoy data!
—The PyTables Team