PyTables User's Guide: Hierarchical datasets in Python - Release 1.3.3
Prev |  | Next

# Chapter 4. Library Reference

`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. Finally, there exists a function called `whichLibVersion` that informs about the versions of the underlying C libraries (for example, the `HDF5` or the `Zlib`).

Let's start discussing the first-level variables and functions available to the user, then the different classes defined in `PyTables`.

# 4.1. tables variables and functions

## 4.1.1. Global variables

__version__

  The `PyTables` version number.

hdf5Version

  The underlying HDF5 library version number.

## 4.1.2. Global functions

### 4.1.2.1. copyFile(srcfilename, dstfilename, overwrite=False, **kwargs)

An easy way of copying one PyTables file to another.

This function allows you to copy an existing PyTables file named `srcfilename` to another file called `dstfilename`. The source file must exist and be readable. The destination file can be overwritten in place if existing by asserting the `overwrite` argument.

This function is a shorthand for the `File.copyFile()` method, which acts on an already opened file. `kwargs` takes keyword arguments used to customize the copying process. See the documentation of `File.copyFile()` (see 4.2.2) for a description of those arguments.

### 4.1.2.2. isHDF5File(filename)

Determine whether a file is in the HDF5 format.

When successful, it returns a true value if the file is an HDF5 file, false otherwise. If there were problems identifying the file, an `HDF5ExtError` is raised.

### 4.1.2.3. isPyTablesFile(filename)

Determine whether a file is in the PyTables format.

When successful, it returns a true value if the file is a PyTables file, false otherwise. The true value is the format version string of the file. If there were problems identifying the file, an `HDF5ExtError` is raised.

### 4.1.2.4. openFile(filename, mode='r', title='', trMap={}, rootUEP="/", filters=None)

Open a `PyTables` (or generic `HDF5`) file and returns a `File` object.

filename

  The name of the file (supports environment variable expansion). It is suggested that it should have any of `".h5"`, `".hdf"` or `".hdf5"` extensions, although this is not mandatory.

mode

  The mode to open the file. It can be one of the following:

  'r'

    read-only; no data can be modified.

  'w'

    write; a new file is created (an existing file with the same name would be deleted).

  'a'

    append; an existing file is opened for reading and writing, and if the file does not exist it is created.

  'r+'

    is similar to 'a', but the file must already exist.

title

  If filename is new, this will set a title for the root group in this file. If filename is not new, the title will be read from disk, and this will not have any effect.

trMap

  A dictionary to map names in the object tree Python namespace into different HDF5 names in file namespace. The keys are the Python names, while the values are the HDF5 names. This is useful when you need to use HDF5 node names with invalid or reserved words in Python.

rootUEP

  The root User Entry Point. This is a group in the HDF5 hierarchy which will be taken as the starting point to create the object tree. The group has to be named after its HDF5 name and can be a path. If it does not exist, an `HDF5ExtError` exception is issued. Use this if you do not want to build the entire object tree, but rather only a subtree of it.

filters

  An instance of the `Filters` class (see section 4.17.1) that provides information about the desired I/O filters applicable to the leaves that hang directly from root (unless other filters properties are specified for these leaves). Besides, if you do not specify filter properties for its child groups, they will inherit these ones. So, if you open a new file with this parameter set, all the leaves that would be created in the file will recursively inherit this filtering properties (again, if you don't prevent that from happening by specifying other filters on the child groups or leaves).

nodeCacheSize

  The number of unreferenced nodes to be kept in memory. Least recently used nodes are unloaded from memory when this number of loaded nodes is reached. To load a node again, simply access it as usual. Nodes referenced by user variables are not taken into account nor unloaded.

### 4.1.2.5. whichLibVersion(name)

Get version information about a C library.

If the library indicated by `name` is available, this function returns a 3-tuple containing the major library version as an integer, its full version as a string, and the version date as a string. If the library is not available, `None` is returned.

The currently supported library names are `hdf5`, `zlib`, `lzo`, `ucl` (in process of being deprecated) and `bzip2`. If another name is given, a `ValueError` is raised.

Prev | Home | Next
Other examples in PyTables distribution | Up | The File class