1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
============================
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 a
``NumArray`` or ``CharArray`` object. This is preferred over the syntax
``table['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 fulfilling the condition
to a destination table.
Backward-incompatible changes
=============================
- Trying to open a nonexistent file or a file of unknown type raises
``IOError`` instead of ``RuntimeError``. Using an invalid mode raises
``ValueError`` instead of ``RuntimeError``.
- Getting a child node from a closed group raises ``ValueError`` instead of
``RuntimeError``.
- Running an action on the wrong type of node now (i.e. using
``file.listNodes()`` on a leaf) raises a ``TypeError`` instead of a
``NodeError``.
- Removing a non-existing child now raises a ``NoSuchNodeError``, instead of
doing nothing.
- Removing a non-empty child group using ``del group.child`` fails with a
``NodeError`` instead 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()`` is ``True`` by default now.
Before it was ``False``.
- Now, deleting and getting a non-existing attribute raises an
``AttributeError`` instead of a ``RuntimeError``.
- Swapped last two arguments of ``File.copyAttrs()`` to match the other
methods. Please use ``File.copyNodeAttrs()`` anyway.
- Failing to infer the size of a string column raises ``ValueError`` instead
of ``RuntimeError``.
- Excessive table column name length and number of columns now raise
``ValueError`` instead of ``IndexError`` and ``NameError``.
- Excessive table row length now raises ``ValueError`` instead of
``RuntimeError``.
- ``table[integer]`` returns a ``numarray.records.Record`` object 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 a ``ValueError``
instead of a ``LookupError``.
- When ``start >= stop`` an empty iterator is returned by ``Table.iterrows()``
instead of an empty ``RecArray``. Thanks to Ashley Walsh for noting this.
- The interface of ``isHDF5File()`` and ``isPyTablesFile()`` file has been
unified so that they both return true or false values on success and raise
``HDF5ExtError`` or errors. The true value in ``isPyTablesFile()`` is the
format version string of the file.
- ``Table.whereIndexed()`` and ``Table.whereInRange()`` are now *private*
methods, since the ``Table.where()`` method is able to choose the most
adequate option.
- The global variables ``ExtVersion`` and ``HDF5Version`` have been renamed to
``extVersion`` and ``hdf5Version``, respectively.
- ``whichLibVersion()`` returns ``None`` on querying unavailable libraries,
and raises ``ValueError`` on 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 ``name`` and ``classname`` arguments in
``File.getNode()`` are now ``None``, 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 in ``File.py`` has 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 ``srcFilename`` and ``dstFilename`` arguments in ``copyFile()`` and
``File.copyFile()`` to ``srcfilename`` and ``dstfilename``, respectively.
Renamed ``whereSrc`` and ``whereDst`` arguments in ``File.copyChildren()``
to ``wheresrc`` and ``wheredst``, respectively. Renamed ``dstNode``
argument in ``File.copyAttrs()`` to ``dstnode``. Tose arguments should be
easier to type in interactive sessions (although 99% of the time it is not
necessary to specify them).
- Renamed ``object`` argument in ``EArray.append()`` to ``sequence``.
- The ``rows`` argument in ``Table.append()`` is now compulsory.
- The ``start`` argument in ``Table.removeRows()`` is now compulsory.
API refinements
===============
- The ``isHDF5()`` function has been deprecated in favor of ``isHDF5File()``.
- Node attribute-handling methods in ``File`` have been renamed for a better
coherence and understanding of their purpose:
* ``getAttrNode()`` is now called ``getNodeAttr()``
* ``setAttrNode()`` is now called ``setNodeAttr()``
* ``delAttrNode()`` is now called ``delNodeAttr()``
* ``copyAttrs()`` is now called ``copyNodeAttrs()``
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. Using ``table.col('colname')``
(with the new ``col()`` method) is preferred.
Bug fixes (affecting API)
=========================
- ``Table.iterrows()`` returns an empty iterator when no rows are selected,
instead of returning ``None``.
----
**Enjoy data!**
-- The PyTables Team
.. Local Variables:
.. mode: text
.. coding: utf-8
.. fill-column: 78
.. End:
|
