Databases Reference
In-Depth Information
Keep in mind that this can lead to odd-looking consequences. For example, when you
use the
.parent
property on the retrieved object, it points to the root group of the
external file, not the file in which the link resides:
>>>
f2
[
'/linkname'
]
.
parent
==
f2
[
'/'
]
False
Both the file and object names are checked when you create the external link. So if HDF5
can't find the file, or the specified object within the file, you'll get an exception:
>>>
f2
[
'anotherlink'
]
=
h5py
.
ExternalLink
(
'missing.hdf5'
,
'/'
)
ValueError: unable to create link (Links: Unable to initialize object)
The two main hazards when dealing with external links are (1) that the file the link
points to won't be around when it's accessed, and (2) by simply traversing the links in
the file, you can “wander” into a different file.
There's not too much we can do about (1); it's up to you to keep files organized and be
mindful of what links to what. Hazard (2) is a little more dangerous, particularly since
all the “Pythonic” methods of accessing group members, like iteration,
items()
, and so
on, will include external links. If it's undesirable for your application to cross file bound‐
aries, be sure to check the
.file
property to see where the objects actually reside.
At the moment, there's no way to set a “search path” from h5py. When an external link
is encountered, HDF5 will first look for the destination file in the same directory as the
file with the link, and then in the current working directory. That's it.
A Note on Object Names
You might have noticed that when you retrieve the name of an object, it comes out as a
Python Unicode object:
>>>
f
[
'/foo'
]
.
name
u'/foo'
This is intentional, and following the improved Unicode support of HDF5 1.8 (and
Python 3) it was introduced in h5py version 2.0. Object names in the file are always
treated as “text” strings, which means they represent sequences of characters. In con‐
trast, “byte” strings are sequences of 8-bit numbers that can often but not always store
ASCII or Latin-1 encoded text.
The great thing about this is that international characters are supported for all object
names in the file; you don't have to “ASCII-ize” anything to fit it into the HDF5 system.
Names are stored using the most-compatible storage strategy possible for maximum
compatibility with older versions (1.6) of HDF5.
To take advantage of this, simply supply a Unicode string when creating an object or
making a new link:
