PyTables implements several classes to represent the different nodes in the object tree. They are named File, Group, Leaf, Table, Array, CArray, EArray, VLArray and UnImplemented. Another one allows the user to complement the information on these different objects; its name is AttributeSet. Finally, another important class called IsDescription allows to build a Table record description by declaring a subclass of it. Many other classes are defined in PyTables, but they can be regarded as helpers whose goal is mainly to declare the data type properties of the different first class objects and will be described at the end of this chapter as well.
An important function, called openFile is responsible to create, open or append to files. In addition, a few utility functions are defined to guess if the user supplied file is a PyTables or HDF5 file. These are called isPyTablesFile() and isHDF5File(), respectively. There exists also a function called whichLibVersion() that informs about the versions of the underlying C libraries (for example, HDF5 or Zlib) and another called print_versions() that prints all the versions of the software that PyTables relies on. Finally, test() lets you run the complete test suite from a Python console interactively.
Let’s start discussing the first-level variables and functions available to the user, then the different classes defined in PyTables.
Important
Caveat: The following methods are documented for completeness, and they can be used without any problem. However, you should use the high-level counterpart methods in the File class (see The File Class, because they are most used in documentation and examples, and are a bit more powerful than those exposed here.
The following methods are provided in addition to those in Node (see The Node class):
Following are described the methods that automatically trigger actions when a Group instance is accessed in a special way.
This class defines the __setattr__(), __getattr__() and __delattr__() methods, and they set, get and delete ordinary Python attributes as normally intended. In addition to that, __getattr__() allows getting child nodes by their name for the sake of easy interaction on the command line, as long as there is no Python attribute with the same name. Groups also allow the interactive completion (when using readline) of the names of child nodes. For instance:
# get a Python attribute
nchild = group._v_nchildren
# Add a Table child called 'table' under 'group'.
h5file.createTable(group, 'table', myDescription)
table = group.table # get the table child instance
group.table = 'foo' # set a Python attribute
# (PyTables warns you here about using the name of a child node.)
foo = group.table # get a Python attribute
del group.table # delete a Python attribute
table = group.table # get the table child instance again
The size of this leaf’s data in bytes when it is fully loaded into memory.
The following are just easier-to-write aliases to their Node (see The Node class) counterparts (indicated between parentheses):
An Atom (see The Atom class and its descendants) instance representing the type and shape of the atomic objects to be saved.
On iterators, this is the index of the current row.
The following methods automatically trigger actions when an Array instance is accessed in a special way (e.g. array[2:3,...,::2] will be equivalent to a call to array.__getitem__((slice(2, 3, None), Ellipsis, slice(None, None, 2)))).
The following methods automatically trigger actions when a VLArray instance is accessed in a special way (e.g., vlarray[2:5] will be equivalent to a call to vlarray.__getitem__(slice(2, 5, None)).
The following methods are useful for copying, moving, renaming and removing links.
The following methods are specific for dereferrencing and representing soft links.
The following methods are specific for dereferrencing and representing external links.
In this section a series of classes that are meant to declare datatypes that are required for creating primary PyTables datasets are described.
Now, there come three special classes, ObjectAtom, VLStringAtom and VLUnicodeAtom, that actually do not descend from Atom, but which goal is so similar that they should be described here. Pseudo-atoms can only be used with VLArray datasets (see The VLArray class), and they do not support multidimensional values, nor multiple values per row.
They can be recognised because they also have kind, type and shape attributes, but no size, itemsize or dflt ones. Instead, they have a base atom which defines the elements used for storage.
See examples/vlarray1.py and examples/vlarray2.py for further examples on VLArray datasets, including object serialization and string management.
In addition to the variables that they inherit from the Atom class, Col instances have the following attributes.
The relative position of this column with regard to its column siblings.
This section describes some classes that do not fit in any other section and that mainly serve for ancillary purposes.
The number of currently indexed rows for this column.
In the exceptions module exceptions and warnings that are specific to PyTables are declared.