This file is indexed.

/usr/lib/python2.7/dist-packages/tables/group.py is in python-tables 3.2.2-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   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
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
# -*- coding: utf-8 -*-

########################################################################
#
# License: BSD
# Created: September 4, 2002
# Author: Francesc Alted - faltet@pytables.com
#
# $Id$
#
########################################################################

"""Here is defined the Group class."""

import os
import weakref
import warnings

import tables.misc.proxydict
from tables import hdf5extension
from tables import utilsextension
from tables.registry import class_id_dict
from tables.exceptions import (
    NodeError, NoSuchNodeError, NaturalNameWarning, PerformanceWarning)
from tables.filters import Filters
from tables.registry import get_class_by_name
from tables.path import check_name_validity, join_path, isvisiblename
from tables.node import Node, NotLoggedMixin
from tables.leaf import Leaf
from tables.unimplemented import UnImplemented, Unknown

from tables.link import Link, SoftLink, ExternalLink

from tables._past import previous_api, previous_api_property

obversion = "1.0"


class _ChildrenDict(tables.misc.proxydict.ProxyDict):
    def _get_value_from_container(self, container, key):
        return container._f_get_child(key)

    _getValueFromContainer = previous_api(_get_value_from_container)


class Group(hdf5extension.Group, Node):
    """Basic PyTables grouping structure.

    Instances of this class are grouping structures containing *child*
    instances of zero or more groups or leaves, together with
    supporting metadata. Each group has exactly one *parent* group.

    Working with groups and leaves is similar in many ways to working
    with directories and files, respectively, in a Unix filesystem.
    As with Unix directories and files, objects in the object tree are
    often described by giving their full (or absolute) path names.
    This full path can be specified either as a string (like in
    '/group1/group2') or as a complete object path written in *natural
    naming* schema (like in file.root.group1.group2).

    A collateral effect of the *natural naming* schema is that the
    names of members in the Group class and its instances must be
    carefully chosen to avoid colliding with existing children node
    names.  For this reason and to avoid polluting the children
    namespace all members in a Group start with some reserved prefix,
    like _f_ (for public methods), _g_ (for private ones), _v_ (for
    instance variables) or _c_ (for class variables). Any attempt to
    create a new child node whose name starts with one of these
    prefixes will raise a ValueError exception.

    Another effect of natural naming is that children named after
    Python keywords or having names not valid as Python identifiers
    (e.g.  class, $a or 44) can not be accessed using the node.child
    syntax. You will be forced to use node._f_get_child(child) to
    access them (which is recommended for programmatic accesses).

    You will also need to use _f_get_child() to access an existing
    child node if you set a Python attribute in the Group with the
    same name as that node (you will get a NaturalNameWarning when
    doing this).

    Parameters
    ----------
    parentnode
        The parent :class:`Group` object.

        .. versionchanged:: 3.0
           Renamed from *parentNode* to *parentnode*

    name : str
        The name of this node in its parent group.
    title
        The title for this group
    new
        If this group is new or has to be read from disk
    filters : Filters
        A Filters instance


    Notes
    -----
    The following documentation includes methods that are automatically
    called when a Group instance is accessed in a special way.

    For instance, 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.create_table(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


    .. rubric:: Group attributes

    The following instance variables are provided in addition to those
    in Node (see :ref:`NodeClassDescr`):

    .. attribute:: _v_children

        Dictionary with all nodes hanging from this group.

    .. attribute:: _v_groups

        Dictionary with all groups hanging from this group.

    .. attribute:: _v_hidden

        Dictionary with all hidden nodes hanging from this group.

    .. attribute:: _v_leaves

        Dictionary with all leaves hanging from this group.

    .. attribute:: _v_links

        Dictionary with all links hanging from this group.

    .. attribute:: _v_unknown

        Dictionary with all unknown nodes hanging from this group.

    """

    # Class identifier.
    _c_classid = 'GROUP'

    _c_classId = previous_api_property('_c_classid')

    # Children containers that should be loaded only in a lazy way.
    # These are documented in the ``Group._g_add_children_names`` method.
    _c_lazy_children_attrs = (
        '__members__', '_v_children', '_v_groups', '_v_leaves',
        '_v_links', '_v_unknown', '_v_hidden')

    # `_v_nchildren` is a direct read-only shorthand
    # for the number of *visible* children in a group.
    def _g_getnchildren(self):
        return len(self._v_children)

    _v_nchildren = property(_g_getnchildren, None, None,
                            "The number of children hanging from this group.")

    # `_v_filters` is a direct read-write shorthand for the ``FILTERS``
    # attribute with the default `Filters` instance as a default value.
    def _g_getfilters(self):
        filters = getattr(self._v_attrs, 'FILTERS', None)
        if filters is None:
            filters = Filters()
        return filters

    def _g_setfilters(self, value):
        if not isinstance(value, Filters):
            raise TypeError(
                "value is not an instance of `Filters`: %r" % (value,))
        self._v_attrs.FILTERS = value

    def _g_delfilters(self):
        del self._v_attrs.FILTERS

    _v_filters = property(
        _g_getfilters, _g_setfilters, _g_delfilters,
        """Default filter properties for child nodes.

        You can (and are encouraged to) use this property to get, set and
        delete the FILTERS HDF5 attribute of the group, which stores a Filters
        instance (see :ref:`FiltersClassDescr`). When the group has no such
        attribute, a default Filters instance is used.
        """)

    _v_maxGroupWidth = previous_api_property('_v_max_group_width')

    def __init__(self, parentnode, name,
                 title="", new=False, filters=None,
                 _log=True):

        # Remember to assign these values in the root group constructor
        # if it does not use this one!

        # First, set attributes belonging to group objects.

        self._v_version = obversion
        """The object version of this group."""

        self._v_new = new
        """Is this the first time the node has been created?"""

        self._v_new_title = title
        """New title for this node."""

        self._v_new_filters = filters
        """New default filter properties for child nodes."""

        self._v_max_group_width = parentnode._v_file.params['MAX_GROUP_WIDTH']
        """Maximum number of children on each group before warning the user.

        .. versionchanged:: 3.0
           The *_v_maxGroupWidth* attribute has been renamed into
           *_v_max_group_width*.

        """

        # Finally, set up this object as a node.
        super(Group, self).__init__(parentnode, name, _log)

    def _g_post_init_hook(self):
        if self._v_new:
            if self._v_file.params['PYTABLES_SYS_ATTRS']:
                # Save some attributes for the new group on disk.
                set_attr = self._v_attrs._g__setattr
                # Set the title, class and version attributes.
                set_attr('TITLE', self._v_new_title)
                set_attr('CLASS', self._c_classid)
                set_attr('VERSION', self._v_version)

                # Set the default filter properties.
                newfilters = self._v_new_filters
                if newfilters is None:
                    # If no filters have been passed in the constructor,
                    # inherit them from the parent group, but only if they
                    # have been inherited or explicitly set.
                    newfilters = getattr(
                        self._v_parent._v_attrs, 'FILTERS', None)
                if newfilters is not None:
                    set_attr('FILTERS', newfilters)
        else:
            # If the file has PyTables format, get the VERSION attr
            if 'VERSION' in self._v_attrs._v_attrnamessys:
                self._v_version = self._v_attrs.VERSION
            else:
                self._v_version = "0.0 (unknown)"
            # We don't need to get more attributes from disk,
            # since the most important ones are defined as properties.

    _g_postInitHook = previous_api(_g_post_init_hook)

    def __del__(self):
        if (self._v_isopen and
            self._v_pathname in self._v_file._node_manager.registry and
                '_v_children' in self.__dict__):
            # The group is going to be killed.  Rebuild weak references
            # (that Python cancelled just before calling this method) so
            # that they are still usable if the object is revived later.
            selfref = weakref.ref(self)
            self._v_children.containerref = selfref
            self._v_groups.containerref = selfref
            self._v_leaves.containerref = selfref
            self._v_links.containerref = selfref
            self._v_unknown.containerref = selfref
            self._v_hidden.containerref = selfref

        super(Group, self).__del__()

    def _g_get_child_group_class(self, childname):
        """Get the class of a not-yet-loaded group child.

        `childname` must be the name of a *group* child.

        """

        childCID = self._g_get_gchild_attr(childname, 'CLASS')
        if childCID is not None and not isinstance(childCID, str):
            childCID = childCID.decode('utf-8')

        if childCID in class_id_dict:
            return class_id_dict[childCID]  # look up group class
        else:
            return Group  # default group class

    _g_getChildGroupClass = previous_api(_g_get_child_group_class)

    def _g_get_child_leaf_class(self, childname, warn=True):
        """Get the class of a not-yet-loaded leaf child.

        `childname` must be the name of a *leaf* child.  If the child
        belongs to an unknown kind of leaf, or if its kind can not be
        guessed, `UnImplemented` will be returned and a warning will be
        issued if `warn` is true.

        """

        if self._v_file.params['PYTABLES_SYS_ATTRS']:
            childCID = self._g_get_lchild_attr(childname, 'CLASS')
            if childCID is not None and not isinstance(childCID, str):
                childCID = childCID.decode('utf-8')
        else:
            childCID = None

        if childCID in class_id_dict:
            return class_id_dict[childCID]  # look up leaf class
        else:
            # Unknown or no ``CLASS`` attribute, try a guess.
            childCID2 = utilsextension.which_class(self._v_objectid, childname)
            if childCID2 == 'UNSUPPORTED':
                if warn:
                    if childCID is None:
                        warnings.warn(
                            "leaf ``%s`` is of an unsupported type; "
                            "it will become an ``UnImplemented`` node"
                            % self._g_join(childname))
                    else:
                        warnings.warn(
                            ("leaf ``%s`` has an unknown class ID ``%s``; "
                             "it will become an ``UnImplemented`` node")
                            % (self._g_join(childname), childCID))
                return UnImplemented
            assert childCID2 in class_id_dict
            return class_id_dict[childCID2]  # look up leaf class

    _g_getChildLeafClass = previous_api(_g_get_child_leaf_class)

    def _g_add_children_names(self):
        """Add children names to this group taking into account their
        visibility and kind."""

        mydict = self.__dict__

        # The names of the lazy attributes
        mydict['__members__'] = members = []
        """The names of visible children nodes for readline-style completion.
        """
        mydict['_v_children'] = children = _ChildrenDict(self)
        """The number of children hanging from this group."""
        mydict['_v_groups'] = groups = _ChildrenDict(self)
        """Dictionary with all groups hanging from this group."""
        mydict['_v_leaves'] = leaves = _ChildrenDict(self)
        """Dictionary with all leaves hanging from this group."""
        mydict['_v_links'] = links = _ChildrenDict(self)
        """Dictionary with all links hanging from this group."""
        mydict['_v_unknown'] = unknown = _ChildrenDict(self)
        """Dictionary with all unknown nodes hanging from this group."""
        mydict['_v_hidden'] = hidden = _ChildrenDict(self)
        """Dictionary with all hidden nodes hanging from this group."""

        # Get the names of *all* child groups and leaves.
        (group_names, leaf_names, link_names, unknown_names) = \
            self._g_list_group(self._v_parent)

        # Separate groups into visible groups and hidden nodes,
        # and leaves into visible leaves and hidden nodes.
        for (childnames, childdict) in ((group_names, groups),
                                        (leaf_names, leaves),
                                        (link_names, links),
                                        (unknown_names, unknown)):

            for childname in childnames:
                # See whether the name implies that the node is hidden.
                # (Assigned values are entirely irrelevant.)
                if isvisiblename(childname):
                    # Visible node.
                    members.insert(0, childname)
                    children[childname] = None
                    childdict[childname] = None
                else:
                    # Hidden node.
                    hidden[childname] = None

    _g_addChildrenNames = previous_api(_g_add_children_names)

    def _g_check_has_child(self, name):
        """Check whether 'name' is a children of 'self' and return its type."""

        # Get the HDF5 name matching the PyTables name.
        node_type = self._g_get_objinfo(name)
        if node_type == "NoSuchNode":
            raise NoSuchNodeError(
                "group ``%s`` does not have a child named ``%s``"
                % (self._v_pathname, name))
        return node_type

    _g_checkHasChild = previous_api(_g_check_has_child)

    def __iter__(self):
        """Iterate over the child nodes hanging directly from the group.

        This iterator is *not* recursive.

        Examples
        --------

        ::

            # Non-recursively list all the nodes hanging from '/detector'
            print("Nodes in '/detector' group:")
            for node in h5file.root.detector:
                print(node)

        """

        return self._f_iter_nodes()

    def __contains__(self, name):
        """Is there a child with that `name`?

        Returns a true value if the group has a child node (visible or
        hidden) with the given `name` (a string), false otherwise.

        """

        self._g_check_open()
        try:
            self._g_check_has_child(name)
        except NoSuchNodeError:
            return False
        return True

    def _f_walknodes(self, classname=None):
        """Iterate over descendant nodes.

        This method recursively walks *self* top to bottom (preorder),
        iterating over child groups in alphanumerical order, and yielding
        nodes.  If classname is supplied, only instances of the named class are
        yielded.

        If *classname* is Group, it behaves like :meth:`Group._f_walk_groups`,
        yielding only groups.  If you don't want a recursive behavior,
        use :meth:`Group._f_iter_nodes` instead.

        Examples
        --------

        ::

            # Recursively print all the arrays hanging from '/'
            print("Arrays in the object tree '/':")
            for array in h5file.root._f_walknodes('Array', recursive=True):
                print(array)

        """

        self._g_check_open()

        # For compatibility with old default arguments.
        if classname == '':
            classname = None

        if classname == "Group":
            # Recursive algorithm
            for group in self._f_walk_groups():
                yield group
        else:
            for group in self._f_walk_groups():
                for leaf in group._f_iter_nodes(classname):
                    yield leaf

    _f_walkNodes = previous_api(_f_walknodes)

    def _g_join(self, name):
        """Helper method to correctly concatenate a name child object with the
        pathname of this group."""

        if name == "/":
            # This case can happen when doing copies
            return self._v_pathname
        return join_path(self._v_pathname, name)

    def _g_width_warning(self):
        """Issue a :exc:`PerformanceWarning` on too many children."""

        warnings.warn("""\
group ``%s`` is exceeding the recommended maximum number of children (%d); \
be ready to see PyTables asking for *lots* of memory and possibly slow I/O."""
                      % (self._v_pathname, self._v_max_group_width),
                      PerformanceWarning)

    _g_widthWarning = previous_api(_g_width_warning)

    def _g_refnode(self, childnode, childname, validate=True):
        """Insert references to a `childnode` via a `childname`.

        Checks that the `childname` is valid and does not exist, then
        creates references to the given `childnode` by that `childname`.
        The validation of the name can be omitted by setting `validate`
        to a false value (this may be useful for adding already existing
        nodes to the tree).

        """

        # Check for name validity.
        if validate:
            check_name_validity(childname)
            childnode._g_check_name(childname)

        # Check if there is already a child with the same name.
        # This can be triggered because of the user
        # (via node construction or renaming/movement).
        # Links are not checked here because they are copied and referenced
        # using ``File.get_node`` so they already exist in `self`.
        if (not isinstance(childnode, Link)) and childname in self:
            raise NodeError(
                "group ``%s`` already has a child node named ``%s``"
                % (self._v_pathname, childname))

        # Show a warning if there is an object attribute with that name.
        if childname in self.__dict__:
            warnings.warn(
                "group ``%s`` already has an attribute named ``%s``; "
                "you will not be able to use natural naming "
                "to access the child node"
                % (self._v_pathname, childname), NaturalNameWarning)

        # Check group width limits.
        if (len(self._v_children) + len(self._v_hidden) >=
                self._v_max_group_width):
            self._g_width_warning()

        # Update members information.
        # Insert references to the new child.
        # (Assigned values are entirely irrelevant.)
        if isvisiblename(childname):
            # Visible node.
            self.__members__.insert(0, childname)  # enable completion
            self._v_children[childname] = None  # insert node
            if isinstance(childnode, Unknown):
                self._v_unknown[childname] = None
            elif isinstance(childnode, Link):
                self._v_links[childname] = None
            elif isinstance(childnode, Leaf):
                self._v_leaves[childname] = None
            elif isinstance(childnode, Group):
                self._v_groups[childname] = None
        else:
            # Hidden node.
            self._v_hidden[childname] = None  # insert node

    _g_refNode = previous_api(_g_refnode)

    def _g_unrefnode(self, childname):
        """Remove references to a node.

        Removes all references to the named node.

        """

        # This can *not* be triggered because of the user.
        assert childname in self, \
            ("group ``%s`` does not have a child node named ``%s``"
                % (self._v_pathname, childname))

        # Update members information, if needed
        if '_v_children' in self.__dict__:
            if childname in self._v_children:
                # Visible node.
                members = self.__members__
                member_index = members.index(childname)
                del members[member_index]  # disables completion

                del self._v_children[childname]  # remove node
                self._v_unknown.pop(childname, None)
                self._v_links.pop(childname, None)
                self._v_leaves.pop(childname, None)
                self._v_groups.pop(childname, None)
            else:
                # Hidden node.
                del self._v_hidden[childname]  # remove node

    _g_unrefNode = previous_api(_g_unrefnode)

    def _g_move(self, newparent, newname):
        # Move the node to the new location.
        oldpath = self._v_pathname
        super(Group, self)._g_move(newparent, newname)
        newpath = self._v_pathname

        # Update location information in children.  This node shouldn't
        # be affected since it has already been relocated.
        self._v_file._update_node_locations(oldpath, newpath)

    def _g_copy(self, newparent, newname, recursive, _log=True, **kwargs):
        # Compute default arguments.
        title = kwargs.get('title', self._v_title)
        filters = kwargs.get('filters', None)
        stats = kwargs.get('stats', None)

        # Fix arguments with explicit None values for backwards compatibility.
        if title is None:
            title = self._v_title
        # If no filters have been passed to the call, copy them from the
        # source group, but only if inherited or explicitly set.
        if filters is None:
            filters = getattr(self._v_attrs, 'FILTERS', None)

        # Create a copy of the object.
        new_node = Group(newparent, newname,
                         title, new=True, filters=filters, _log=_log)

        # Copy user attributes if needed.
        if kwargs.get('copyuserattrs', True):
            self._v_attrs._g_copy(new_node._v_attrs, copyclass=True)

        # Update statistics if needed.
        if stats is not None:
            stats['groups'] += 1

        if recursive:
            # Copy child nodes if a recursive copy was requested.
            # Some arguments should *not* be passed to children copy ops.
            kwargs = kwargs.copy()
            kwargs.pop('title', None)
            self._g_copy_children(new_node, **kwargs)

        return new_node

    def _g_copy_children(self, newparent, **kwargs):
        """Copy child nodes.

        Copies all nodes descending from this one into the specified
        `newparent`.  If the new parent has a child node with the same
        name as one of the nodes in this group, the copy fails with a
        `NodeError`, maybe resulting in a partial copy.  Nothing is
        logged.

        """

        # Recursive version of children copy.
        # for srcchild in self._v_children.itervalues():
        ##    srcchild._g_copy_as_child(newparent, **kwargs)

        # Non-recursive version of children copy.
        use_hardlinks = kwargs.get('use_hardlinks', False)
        if use_hardlinks:
            address_map = kwargs.setdefault('address_map', {})

        parentstack = [(self, newparent)]  # [(source, destination), ...]
        while parentstack:
            (srcparent, dstparent) = parentstack.pop()

            if use_hardlinks:
                for srcchild in srcparent._v_children.itervalues():
                    addr, rc = srcchild._get_obj_info()
                    if rc > 1 and addr in address_map:
                        where, name = address_map[addr][0]
                        localsrc = os.path.join(where, name)
                        dstparent._v_file.create_hard_link(dstparent,
                                                           srcchild.name,
                                                           localsrc)
                        address_map[addr].append(
                            (dstparent._v_pathname, srcchild.name)
                        )

                        # Update statistics if needed.
                        stats = kwargs.pop('stats', None)
                        if stats is not None:
                            stats['hardlinks'] += 1
                    else:
                        dstchild = srcchild._g_copy_as_child(dstparent,
                                                             **kwargs)
                        if isinstance(srcchild, Group):
                            parentstack.append((srcchild, dstchild))

                        if rc > 1:
                            address_map[addr] = [
                                (dstparent._v_pathname, srcchild.name)
                            ]
            else:
                for srcchild in srcparent._v_children.itervalues():
                    dstchild = srcchild._g_copy_as_child(dstparent, **kwargs)
                    if isinstance(srcchild, Group):
                        parentstack.append((srcchild, dstchild))

    _g_copyChildren = previous_api(_g_copy_children)

    def _f_get_child(self, childname):
        """Get the child called childname of this group.

        If the child exists (be it visible or not), it is returned.  Else, a
        NoSuchNodeError is raised.

        Using this method is recommended over getattr() when doing programmatic
        accesses to children if childname is unknown beforehand or when its
        name is not a valid Python identifier.

        """

        self._g_check_open()

        self._g_check_has_child(childname)

        childpath = join_path(self._v_pathname, childname)
        return self._v_file._get_node(childpath)

    _f_getChild = previous_api(_f_get_child)

    def _f_list_nodes(self, classname=None):
        """Return a *list* with children nodes.

        This is a list-returning version of :meth:`Group._f_iter_nodes()`.

        """

        return list(self._f_iter_nodes(classname))

    _f_listNodes = previous_api(_f_list_nodes)

    def _f_iter_nodes(self, classname=None):
        """Iterate over children nodes.

        Child nodes are yielded alphanumerically sorted by node name.  If the
        name of a class derived from Node (see :ref:`NodeClassDescr`) is
        supplied in the classname parameter, only instances of that class (or
        subclasses of it) will be returned.

        This is an iterator version of :meth:`Group._f_list_nodes`.

        """

        self._g_check_open()

        if not classname:
            # Returns all the children alphanumerically sorted
            names = sorted(self._v_children.iterkeys())
            for name in names:
                yield self._v_children[name]
        elif classname == 'Group':
            # Returns all the groups alphanumerically sorted
            names = sorted(self._v_groups.iterkeys())
            for name in names:
                yield self._v_groups[name]
        elif classname == 'Leaf':
            # Returns all the leaves alphanumerically sorted
            names = sorted(self._v_leaves.iterkeys())
            for name in names:
                yield self._v_leaves[name]
        elif classname == 'Link':
            # Returns all the links alphanumerically sorted
            names = sorted(self._v_links.iterkeys())
            for name in names:
                yield self._v_links[name]
        elif classname == 'IndexArray':
            raise TypeError(
                "listing ``IndexArray`` nodes is not allowed")
        else:
            class_ = get_class_by_name(classname)

            children = self._v_children
            childnames = sorted(children.iterkeys())

            for childname in childnames:
                childnode = children[childname]
                if isinstance(childnode, class_):
                    yield childnode

    _f_iterNodes = previous_api(_f_iter_nodes)

    def _f_walk_groups(self):
        """Recursively iterate over descendent groups (not leaves).

        This method starts by yielding *self*, and then it goes on to
        recursively iterate over all child groups in alphanumerical order, top
        to bottom (preorder), following the same procedure.

        """

        self._g_check_open()

        stack = [self]
        yield self
        # Iterate over the descendants
        while stack:
            objgroup = stack.pop()
            groupnames = sorted(objgroup._v_groups.iterkeys())
            # Sort the groups before delivering. This uses the groups names
            # for groups in tree (in order to sort() can classify them).
            for groupname in groupnames:
                stack.append(objgroup._v_groups[groupname])
                yield objgroup._v_groups[groupname]

    _f_walkGroups = previous_api(_f_walk_groups)

    def __delattr__(self, name):
        """Delete a Python attribute called name.

        This method deletes an *ordinary Python attribute* from the object.
        It does *not* remove children nodes from this group; for that,
        use :meth:`File.remove_node` or :meth:`Node._f_remove`.
        It does *neither* delete a PyTables node attribute; for that,
        use :meth:`File.del_node_attr`, :meth:`Node._f_delattr` or
        :attr:`Node._v_attrs``.

        If there is an attribute and a child node with the same name,
        the child node will be made accessible again via natural naming.

        """

        try:
            super(Group, self).__delattr__(name)  # nothing particular
        except AttributeError as ae:
            hint = " (use ``node._f_remove()`` if you want to remove a node)"
            raise ae.__class__(str(ae) + hint)

    def __getattr__(self, name):
        """Get a Python attribute or child node called name.

        If the object has a Python attribute called name, its value is
        returned. Else, if the node has a child node called name, it is
        returned.  Else, an AttributeError is raised.

        """

        # That is true since a `NoSuchNodeError` is an `AttributeError`.
        mydict = self.__dict__
        if name in mydict:
            return mydict[name]
        elif name in self._c_lazy_children_attrs:
            self._g_add_children_names()
            return mydict[name]
        return self._f_get_child(name)

    def __setattr__(self, name, value):
        """Set a Python attribute called name with the given value.

        This method stores an *ordinary Python attribute* in the object. It
        does *not* store new children nodes under this group; for that, use the
        File.create*() methods (see the File class
        in :ref:`FileClassDescr`). It does *neither* store a PyTables node
        attribute; for that,
        use :meth:`File.set_node_attr`, :meth`:Node._f_setattr`
        or :attr:`Node._v_attrs`.

        If there is already a child node with the same name, a
        NaturalNameWarning will be issued and the child node will not be
        accessible via natural naming nor getattr(). It will still be available
        via :meth:`File.get_node`, :meth:`Group._f_get_child` and children
        dictionaries in the group (if visible).

        """

        # Show a warning if there is an child node with that name.
        #
        # ..note::
        #
        #   Using ``if name in self:`` is not right since that would
        #   require ``_v_children`` and ``_v_hidden`` to be already set
        #   when the very first attribute assignments are made.
        #   Moreover, this warning is only concerned about clashes with
        #   names used in natural naming, i.e. those in ``__members__``.
        #
        # ..note::
        #
        #   The check ``'__members__' in myDict`` allows attribute
        #   assignment to happen before calling `Group.__init__()`, by
        #   avoiding to look into the still not assigned ``__members__``
        #   attribute.  This allows subclasses to set up some attributes
        #   and then call the constructor of the superclass.  If the
        #   check above is disabled, that results in Python entering an
        #   endless loop on exit!

        mydict = self.__dict__
        if '__members__' in mydict and name in self.__members__:
            warnings.warn(
                "group ``%s`` already has a child node named ``%s``; "
                "you will not be able to use natural naming "
                "to access the child node"
                % (self._v_pathname, name), NaturalNameWarning)

        super(Group, self).__setattr__(name, value)

    def _f_flush(self):
        """Flush this Group."""

        self._g_check_open()
        self._g_flush_group()

    def _g_close_descendents(self):
        """Close all the *loaded* descendent nodes of this group."""

        node_manager = self._v_file._node_manager
        node_manager.close_subtree(self._v_pathname)

    _g_closeDescendents = previous_api(_g_close_descendents)

    def _g_close(self):
        """Close this (open) group."""

        if self._v_isopen:
            # hdf5extension operations:
            #   Close HDF5 group.
            self._g_close_group()

        # Close myself as a node.
        super(Group, self)._f_close()

    def _f_close(self):
        """Close this group and all its descendents.

        This method has the behavior described in :meth:`Node._f_close`.
        It should be noted that this operation closes all the nodes
        descending from this group.

        You should not need to close nodes manually because they are
        automatically opened/closed when they are loaded/evicted from
        the integrated LRU cache.

        """

        # If the group is already closed, return immediately
        if not self._v_isopen:
            return

        # First, close all the descendents of this group, unless a) the
        # group is being deleted (evicted from LRU cache) or b) the node
        # is being closed during an aborted creation, in which cases
        # this is not an explicit close issued by the user.
        if not (self._v__deleting or self._v_objectid is None):
            self._g_close_descendents()

        # When all the descendents have been closed, close this group.
        # This is done at the end because some nodes may still need to
        # be loaded during the closing process; thus this node must be
        # open until the very end.
        self._g_close()

    def _g_remove(self, recursive=False, force=False):
        """Remove (recursively if needed) the Group.

        This version correctly handles both visible and hidden nodes.

        """

        if self._v_nchildren > 0:
            if not (recursive or force):
                raise NodeError("group ``%s`` has child nodes; "
                                "please set `recursive` or `force` to true "
                                "to remove it"
                                % (self._v_pathname,))

            # First close all the descendents hanging from this group,
            # so that it is not possible to use a node that no longer exists.
            self._g_close_descendents()

        # Remove the node itself from the hierarchy.
        super(Group, self)._g_remove(recursive, force)

    def _f_copy(self, newparent=None, newname=None,
                overwrite=False, recursive=False, createparents=False,
                **kwargs):
        """Copy this node and return the new one.

        This method has the behavior described in :meth:`Node._f_copy`.
        In addition, it recognizes the following keyword arguments:

        Parameters
        ----------
        title
            The new title for the destination. If omitted or None, the
            original title is used. This only applies to the topmost
            node in recursive copies.
        filters : Filters
            Specifying this parameter overrides the original filter
            properties in the source node. If specified, it must be an
            instance of the Filters class (see :ref:`FiltersClassDescr`).
            The default is to copy the filter properties from the source
            node.
        copyuserattrs
            You can prevent the user attributes from being copied by setting
            thisparameter to False. The default is to copy them.
        stats
            This argument may be used to collect statistics on the copy
            process. When used, it should be a dictionary with keys 'groups',
            'leaves', 'links' and 'bytes' having a numeric value. Their values
            willbe incremented to reflect the number of groups, leaves and
            bytes, respectively, that have been copied during the operation.

        """

        return super(Group, self)._f_copy(
            newparent, newname,
            overwrite, recursive, createparents, **kwargs)

    def _f_copy_children(self, dstgroup, overwrite=False, recursive=False,
                         createparents=False, **kwargs):
        """Copy the children of this group into another group.

        Children hanging directly from this group are copied into dstgroup,
        which can be a Group (see :ref:`GroupClassDescr`) object or its
        pathname in string form. If createparents is true, the needed groups
        for the given destination group path to exist will be created.

        The operation will fail with a NodeError if there is a child node
        in the destination group with the same name as one of the copied
        children from this one, unless overwrite is true; in this case,
        the former child node is recursively removed before copying the
        later.

        By default, nodes descending from children groups of this node
        are not copied. If the recursive argument is true, all descendant
        nodes of this node are recursively copied.

        Additional keyword arguments may be passed to customize the
        copying process. For instance, title and filters may be changed,
        user attributes may be or may not be copied, data may be sub-sampled,
        stats may be collected, etc. Arguments unknown to nodes are simply
        ignored. Check the documentation for copying operations of nodes to
        see which options they support.

        """

        self._g_check_open()

        # `dstgroup` is used instead of its path to avoid accepting
        # `Node` objects when `createparents` is true.  Also, note that
        # there is no risk of creating parent nodes and failing later
        # because of destination nodes already existing.
        dstparent = self._v_file._get_or_create_path(dstgroup, createparents)
        self._g_check_group(dstparent)  # Is it a group?

        if not overwrite:
            # Abort as early as possible when destination nodes exist
            # and overwriting is not enabled.
            for childname in self._v_children:
                if childname in dstparent:
                    raise NodeError(
                        "destination group ``%s`` already has "
                        "a node named ``%s``; "
                        "you may want to use the ``overwrite`` argument"
                        % (dstparent._v_pathname, childname))

        use_hardlinks = kwargs.get('use_hardlinks', False)
        if use_hardlinks:
            address_map = kwargs.setdefault('address_map', {})

            for child in self._v_children.itervalues():
                addr, rc = child._get_obj_info()
                if rc > 1 and addr in address_map:
                    where, name = address_map[addr][0]
                    localsrc = os.path.join(where, name)
                    dstparent._v_file.create_hard_link(dstparent, child.name,
                                                       localsrc)
                    address_map[addr].append(
                        (dstparent._v_pathname, child.name)
                    )

                    # Update statistics if needed.
                    stats = kwargs.pop('stats', None)
                    if stats is not None:
                        stats['hardlinks'] += 1
                else:
                    child._f_copy(dstparent, None, overwrite, recursive,
                                  **kwargs)
                    if rc > 1:
                        address_map[addr] = [
                            (dstparent._v_pathname, child.name)
                        ]
        else:
            for child in self._v_children.itervalues():
                child._f_copy(dstparent, None, overwrite, recursive, **kwargs)

    _f_copyChildren = previous_api(_f_copy_children)

    def __str__(self):
        """Return a short string representation of the group.

        Examples
        --------

        ::

            >>> f=tables.open_file('data/test.h5')
            >>> print(f.root.group0)
            /group0 (Group) 'First Group'

        """

        pathname = self._v_pathname
        classname = self.__class__.__name__
        title = self._v_title
        return "%s (%s) %r" % (pathname, classname, title)

    def __repr__(self):
        """Return a detailed string representation of the group.

        Examples
        --------

        ::

            >>> f = tables.open_file('data/test.h5')
            >>> f.root.group0
            /group0 (Group) 'First Group'
              children := ['tuple1' (Table), 'group1' (Group)]

        """

        rep = [
            '%r (%s)' % (childname, child.__class__.__name__)
            for (childname, child) in self._v_children.iteritems()
        ]
        childlist = '[%s]' % (', '.join(rep))

        return "%s\n  children := %s" % (str(self), childlist)


# Special definition for group root
class RootGroup(Group):

    _v_objectId = previous_api_property('_v_objectid')

    def __init__(self, ptfile, name, title, new, filters):
        mydict = self.__dict__

        # Set group attributes.
        self._v_version = obversion
        self._v_new = new
        if new:
            self._v_new_title = title
            self._v_new_filters = filters
        else:
            self._v_new_title = None
            self._v_new_filters = None

        # Set node attributes.
        self._v_file = ptfile
        self._v_isopen = True  # root is always open
        self._v_pathname = '/'
        self._v_name = '/'
        self._v_depth = 0
        self._v_max_group_width = ptfile.params['MAX_GROUP_WIDTH']
        self._v__deleting = False
        self._v_objectid = None  # later

        # Only the root node has the file as a parent.
        # Bypass __setattr__ to avoid the ``Node._v_parent`` property.
        mydict['_v_parent'] = ptfile
        ptfile._node_manager.register_node(self, '/')

        # hdf5extension operations (do before setting an AttributeSet):
        #   Update node attributes.
        self._g_new(ptfile, name, init=True)
        #   Open the node and get its object ID.
        self._v_objectid = self._g_open()

        # Set disk attributes and read children names.
        #
        # This *must* be postponed because this method needs the root node
        # to be created and bound to ``File.root``.
        # This is an exception to the rule, handled by ``File.__init()__``.
        #
        # self._g_post_init_hook()

    def _g_load_child(self, childname):
        """Load a child node from disk.

        The child node `childname` is loaded from disk and an adequate
        `Node` object is created and returned.  If there is no such
        child, a `NoSuchNodeError` is raised.

        """

        if self._v_file.root_uep != "/":
            childname = join_path(self._v_file.root_uep, childname)
        # Is the node a group or a leaf?
        node_type = self._g_check_has_child(childname)

        # Nodes that HDF5 report as H5G_UNKNOWN
        if node_type == 'Unknown':
            return Unknown(self, childname)

        # Guess the PyTables class suited to the node,
        # build a PyTables node and return it.
        if node_type == "Group":
            if self._v_file.params['PYTABLES_SYS_ATTRS']:
                ChildClass = self._g_get_child_group_class(childname)
            else:
                # Default is a Group class
                ChildClass = Group
            return ChildClass(self, childname, new=False)
        elif node_type == "Leaf":
            ChildClass = self._g_get_child_leaf_class(childname, warn=True)
            # Building a leaf may still fail because of unsupported types
            # and other causes.
            # return ChildClass(self, childname)  # uncomment for debugging
            try:
                return ChildClass(self, childname)
            except Exception as exc:  # XXX
                warnings.warn(
                    "problems loading leaf ``%s``::\n\n"
                    "  %s\n\n"
                    "The leaf will become an ``UnImplemented`` node."
                    % (self._g_join(childname), exc))
                # If not, associate an UnImplemented object to it
                return UnImplemented(self, childname)
        elif node_type == "SoftLink":
            return SoftLink(self, childname)
        elif node_type == "ExternalLink":
            return ExternalLink(self, childname)
        else:
            return UnImplemented(self, childname)

    _g_loadChild = previous_api(_g_load_child)

    def _f_rename(self, newname):
        raise NodeError("the root node can not be renamed")

    def _f_move(self, newparent=None, newname=None, createparents=False):
        raise NodeError("the root node can not be moved")

    def _f_remove(self, recursive=False):
        raise NodeError("the root node can not be removed")


class TransactionGroupG(NotLoggedMixin, Group):
    _c_classid = 'TRANSGROUP'

    _c_classId = previous_api_property('_c_classid')

    def _g_width_warning(self):
        warnings.warn("""\
the number of transactions is exceeding the recommended maximum (%d);\
be ready to see PyTables asking for *lots* of memory and possibly slow I/O"""
                      % (self._v_max_group_width,), PerformanceWarning)

    _g_widthWarning = previous_api(_g_width_warning)


class TransactionG(NotLoggedMixin, Group):
    _c_classid = 'TRANSG'

    _c_classId = previous_api_property('_c_classid')

    def _g_width_warning(self):
        warnings.warn("""\
transaction ``%s`` is exceeding the recommended maximum number of marks (%d);\
be ready to see PyTables asking for *lots* of memory and possibly slow I/O"""
                      % (self._v_pathname, self._v_max_group_width),
                      PerformanceWarning)

    _g_widthWarning = previous_api(_g_width_warning)


class MarkG(NotLoggedMixin, Group):
    # Class identifier.
    _c_classid = 'MARKG'

    _c_classId = previous_api_property('_c_classid')

    import re
    _c_shadow_name_re = re.compile(r'^a[0-9]+$')

    def _g_width_warning(self):
        warnings.warn("""\
mark ``%s`` is exceeding the recommended maximum action storage (%d nodes);\
be ready to see PyTables asking for *lots* of memory and possibly slow I/O"""
                      % (self._v_pathname, self._v_max_group_width),
                      PerformanceWarning)

    _g_widthWarning = previous_api(_g_width_warning)

    def _g_reset(self):
        """Empty action storage (nodes and attributes).

        This method empties all action storage kept in this node: nodes
        and attributes.

        """

        # Remove action storage nodes.
        for child in self._v_children.values():
            child._g_remove(True, True)

        # Remove action storage attributes.
        attrs = self._v_attrs
        shname = self._c_shadow_name_re
        for attrname in attrs._v_attrnamesuser[:]:
            if shname.match(attrname):
                attrs._g__delattr(attrname)


## Local Variables:
## mode: python
## py-indent-offset: 4
## tab-width: 4
## fill-column: 72
## End: