Lichen

Annotated deducer.py

67:e5d076d40c1a
2016-09-28 Paul Boddie Expanded the access plan generation substantially. Renamed reference_constrained to accessor_constrained in the deducer. Renamed test_for_types to test_for_type, changing the parameter requirements.
paul@44 1
#!/usr/bin/env python
paul@44 2
paul@44 3
"""
paul@44 4
Deduce types for usage observations.
paul@44 5
paul@44 6
Copyright (C) 2014, 2015, 2016 Paul Boddie <paul@boddie.org.uk>
paul@44 7
paul@44 8
This program is free software; you can redistribute it and/or modify it under
paul@44 9
the terms of the GNU General Public License as published by the Free Software
paul@44 10
Foundation; either version 3 of the License, or (at your option) any later
paul@44 11
version.
paul@44 12
paul@44 13
This program is distributed in the hope that it will be useful, but WITHOUT
paul@44 14
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
paul@44 15
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
paul@44 16
details.
paul@44 17
paul@44 18
You should have received a copy of the GNU General Public License along with
paul@44 19
this program.  If not, see <http://www.gnu.org/licenses/>.
paul@44 20
"""
paul@44 21
paul@65 22
from common import first, get_attrname_from_location, get_attrnames, \
paul@44 23
                   init_item, make_key, sorted_output, \
paul@44 24
                   CommonOutput
paul@44 25
from encoders import encode_attrnames, encode_access_location, \
paul@56 26
                     encode_constrained, encode_location, encode_usage, \
paul@67 27
                     get_kinds, test_for_kinds, test_for_type
paul@44 28
from os.path import join
paul@57 29
from referencing import combine_types, is_single_class_type, separate_types, \
paul@57 30
                        Reference
paul@44 31
paul@44 32
class Deducer(CommonOutput):
paul@44 33
paul@44 34
    "Deduce types in a program."
paul@44 35
paul@44 36
    def __init__(self, importer, output):
paul@44 37
paul@44 38
        """
paul@44 39
        Initialise an instance using the given 'importer' that will perform
paul@44 40
        deductions on the program information, writing the results to the given
paul@44 41
        'output' directory.
paul@44 42
        """
paul@44 43
paul@44 44
        self.importer = importer
paul@44 45
        self.output = output
paul@44 46
paul@44 47
        # Descendants of classes.
paul@44 48
paul@44 49
        self.descendants = {}
paul@44 50
        self.init_descendants()
paul@44 51
        self.init_special_attributes()
paul@44 52
paul@44 53
        # Map locations to usage in order to determine specific types.
paul@44 54
paul@44 55
        self.location_index = {}
paul@44 56
paul@44 57
        # Map access locations to definition locations.
paul@44 58
paul@44 59
        self.access_index = {}
paul@44 60
paul@44 61
        # Map aliases to accesses that define them.
paul@44 62
paul@44 63
        self.alias_index = {}
paul@44 64
paul@64 65
        # Map constant accesses to redefined accesses.
paul@64 66
paul@64 67
        self.const_accesses = {}
paul@67 68
        self.const_accesses_rev = {}
paul@64 69
paul@44 70
        # Map usage observations to assigned attributes.
paul@44 71
paul@44 72
        self.assigned_attrs = {}
paul@44 73
paul@44 74
        # Map usage observations to objects.
paul@44 75
paul@44 76
        self.attr_class_types = {}
paul@44 77
        self.attr_instance_types = {}
paul@44 78
        self.attr_module_types = {}
paul@44 79
paul@44 80
        # Modified attributes from usage observations.
paul@44 81
paul@44 82
        self.modified_attributes = {}
paul@44 83
paul@44 84
        # Map locations to types, constrained indicators and attributes.
paul@44 85
paul@44 86
        self.accessor_class_types = {}
paul@44 87
        self.accessor_instance_types = {}
paul@44 88
        self.accessor_module_types = {}
paul@44 89
        self.provider_class_types = {}
paul@44 90
        self.provider_instance_types = {}
paul@44 91
        self.provider_module_types = {}
paul@67 92
        self.accessor_constrained = set()
paul@44 93
        self.access_constrained = set()
paul@44 94
        self.referenced_attrs = {}
paul@44 95
        self.referenced_objects = {}
paul@44 96
paul@67 97
        # Details of access operations.
paul@67 98
paul@67 99
        self.access_plans = {}
paul@67 100
paul@44 101
        # Accumulated information about accessors and providers.
paul@44 102
paul@44 103
        self.accessor_general_class_types = {}
paul@44 104
        self.accessor_general_instance_types = {}
paul@44 105
        self.accessor_general_module_types = {}
paul@44 106
        self.accessor_all_types = {}
paul@44 107
        self.accessor_all_general_types = {}
paul@44 108
        self.provider_all_types = {}
paul@44 109
        self.accessor_guard_tests = {}
paul@44 110
paul@44 111
        # Accumulated information about accessed attributes and
paul@67 112
        # access/attribute-specific accessor tests.
paul@44 113
paul@44 114
        self.reference_class_attrs = {}
paul@44 115
        self.reference_instance_attrs = {}
paul@44 116
        self.reference_module_attrs = {}
paul@44 117
        self.reference_all_attrs = {}
paul@44 118
        self.reference_all_attrtypes = {}
paul@67 119
        self.reference_all_accessor_types = {}
paul@67 120
        self.reference_all_accessor_general_types = {}
paul@44 121
        self.reference_test_types = {}
paul@44 122
        self.reference_test_accessor_types = {}
paul@44 123
paul@44 124
        # The processing workflow itself.
paul@44 125
paul@44 126
        self.init_usage_index()
paul@44 127
        self.init_accessors()
paul@44 128
        self.init_accesses()
paul@44 129
        self.init_aliases()
paul@44 130
        self.init_attr_type_indexes()
paul@44 131
        self.modify_mutated_attributes()
paul@44 132
        self.identify_references()
paul@44 133
        self.classify_accessors()
paul@44 134
        self.classify_accesses()
paul@67 135
        self.initialise_access_plans()
paul@44 136
paul@44 137
    def to_output(self):
paul@44 138
paul@44 139
        "Write the output files using deduction information."
paul@44 140
paul@44 141
        self.check_output()
paul@44 142
paul@44 143
        self.write_mutations()
paul@44 144
        self.write_accessors()
paul@44 145
        self.write_accesses()
paul@65 146
        self.write_access_plans()
paul@44 147
paul@44 148
    def write_mutations(self):
paul@44 149
paul@44 150
        """
paul@44 151
        Write mutation-related output in the following format:
paul@44 152
paul@44 153
        qualified name " " original object type
paul@44 154
paul@44 155
        Object type can be "<class>", "<function>" or "<var>".
paul@44 156
        """
paul@44 157
paul@44 158
        f = open(join(self.output, "mutations"), "w")
paul@44 159
        try:
paul@44 160
            attrs = self.modified_attributes.items()
paul@44 161
            attrs.sort()
paul@44 162
paul@44 163
            for attr, value in attrs:
paul@44 164
                print >>f, attr, value
paul@44 165
        finally:
paul@44 166
            f.close()
paul@44 167
paul@44 168
    def write_accessors(self):
paul@44 169
paul@44 170
        """
paul@44 171
        Write reference-related output in the following format for types:
paul@44 172
paul@44 173
        location " " ( "constrained" | "deduced" ) " " attribute type " " most general type names " " number of specific types
paul@44 174
paul@44 175
        Note that multiple lines can be given for each location, one for each
paul@44 176
        attribute type.
paul@44 177
paul@44 178
        Locations have the following format:
paul@44 179
paul@44 180
        qualified name of scope "." local name ":" name version
paul@44 181
paul@44 182
        The attribute type can be "<class>", "<instance>", "<module>" or "<>",
paul@44 183
        where the latter indicates an absence of suitable references.
paul@44 184
paul@44 185
        Type names indicate the type providing the attributes, being either a
paul@44 186
        class or module qualified name.
paul@44 187
paul@44 188
        ----
paul@44 189
paul@44 190
        A summary of accessor types is formatted as follows:
paul@44 191
paul@44 192
        location " " ( "constrained" | "deduced" ) " " ( "specific" | "common" | "unguarded" ) " " most general type names " " number of specific types
paul@44 193
paul@44 194
        This summary groups all attribute types (class, instance, module) into a
paul@44 195
        single line in order to determine the complexity of identifying an
paul@44 196
        accessor.
paul@44 197
paul@44 198
        ----
paul@44 199
paul@44 200
        References that cannot be supported by any types are written to a
paul@44 201
        warnings file in the following format:
paul@44 202
paul@44 203
        location
paul@44 204
paul@44 205
        ----
paul@44 206
paul@44 207
        For each location where a guard would be asserted to guarantee the
paul@44 208
        nature of an object, the following format is employed:
paul@44 209
paul@44 210
        location " " ( "specific" | "common" ) " " object kind " " object types
paul@44 211
paul@44 212
        Object kind can be "<class>", "<instance>" or "<module>".
paul@44 213
        """
paul@44 214
paul@44 215
        f_type_summary = open(join(self.output, "type_summary"), "w")
paul@44 216
        f_types = open(join(self.output, "types"), "w")
paul@44 217
        f_warnings = open(join(self.output, "type_warnings"), "w")
paul@44 218
        f_guards = open(join(self.output, "guards"), "w")
paul@44 219
paul@44 220
        try:
paul@44 221
            locations = self.accessor_class_types.keys()
paul@44 222
            locations.sort()
paul@44 223
paul@44 224
            for location in locations:
paul@67 225
                constrained = location in self.accessor_constrained
paul@44 226
paul@44 227
                # Accessor information.
paul@44 228
paul@44 229
                class_types = self.accessor_class_types[location]
paul@44 230
                instance_types = self.accessor_instance_types[location]
paul@44 231
                module_types = self.accessor_module_types[location]
paul@44 232
paul@44 233
                general_class_types = self.accessor_general_class_types[location]
paul@44 234
                general_instance_types = self.accessor_general_instance_types[location]
paul@44 235
                general_module_types = self.accessor_general_module_types[location]
paul@44 236
paul@44 237
                all_types = self.accessor_all_types[location]
paul@44 238
                all_general_types = self.accessor_all_general_types[location]
paul@44 239
paul@44 240
                if class_types:
paul@44 241
                    print >>f_types, encode_location(location), encode_constrained(constrained), "<class>", \
paul@44 242
                        sorted_output(general_class_types), len(class_types)
paul@44 243
paul@44 244
                if instance_types:
paul@44 245
                    print >>f_types, encode_location(location), encode_constrained(constrained), "<instance>", \
paul@44 246
                        sorted_output(general_instance_types), len(instance_types)
paul@44 247
paul@44 248
                if module_types:
paul@44 249
                    print >>f_types, encode_location(location), encode_constrained(constrained), "<module>", \
paul@44 250
                        sorted_output(general_module_types), len(module_types)
paul@44 251
paul@44 252
                if not all_types:
paul@44 253
                    print >>f_types, encode_location(location), "deduced", "<>", 0
paul@55 254
                    attrnames = list(self.location_index[location])
paul@55 255
                    attrnames.sort()
paul@55 256
                    print >>f_warnings, encode_location(location), "; ".join(map(encode_usage, attrnames))
paul@44 257
paul@44 258
                guard_test = self.accessor_guard_tests.get(location)
paul@44 259
paul@44 260
                # Write specific type guard details.
paul@44 261
paul@44 262
                if guard_test and guard_test.startswith("specific"):
paul@44 263
                    print >>f_guards, encode_location(location), guard_test, \
paul@56 264
                        get_kinds(all_types)[0], \
paul@44 265
                        sorted_output(all_types)
paul@44 266
paul@44 267
                # Write common type guard details.
paul@44 268
paul@44 269
                elif guard_test and guard_test.startswith("common"):
paul@44 270
                    print >>f_guards, encode_location(location), guard_test, \
paul@56 271
                        get_kinds(all_general_types)[0], \
paul@44 272
                        sorted_output(all_general_types)
paul@44 273
paul@44 274
                print >>f_type_summary, encode_location(location), encode_constrained(constrained), \
paul@44 275
                    guard_test or "unguarded", sorted_output(all_general_types), len(all_types)
paul@44 276
paul@44 277
        finally:
paul@44 278
            f_type_summary.close()
paul@44 279
            f_types.close()
paul@44 280
            f_warnings.close()
paul@44 281
            f_guards.close()
paul@44 282
paul@44 283
    def write_accesses(self):
paul@44 284
paul@44 285
        """
paul@44 286
        Specific attribute output is produced in the following format:
paul@44 287
paul@44 288
        location " " ( "constrained" | "deduced" ) " " attribute type " " attribute references
paul@44 289
paul@44 290
        Note that multiple lines can be given for each location and attribute
paul@44 291
        name, one for each attribute type.
paul@44 292
paul@44 293
        Locations have the following format:
paul@44 294
paul@44 295
        qualified name of scope "." local name " " attribute name ":" access number
paul@44 296
paul@44 297
        The attribute type can be "<class>", "<instance>", "<module>" or "<>",
paul@44 298
        where the latter indicates an absence of suitable references.
paul@44 299
paul@44 300
        Attribute references have the following format:
paul@44 301
paul@44 302
        object type ":" qualified name
paul@44 303
paul@44 304
        Object type can be "<class>", "<function>" or "<var>".
paul@44 305
paul@44 306
        ----
paul@44 307
paul@44 308
        A summary of attributes is formatted as follows:
paul@44 309
paul@44 310
        location " " attribute name " " ( "constrained" | "deduced" ) " " test " " attribute references
paul@44 311
paul@44 312
        This summary groups all attribute types (class, instance, module) into a
paul@44 313
        single line in order to determine the complexity of each access.
paul@44 314
paul@44 315
        Tests can be "validate", "specific", "untested", "guarded-validate" or "guarded-specific".
paul@44 316
paul@44 317
        ----
paul@44 318
paul@44 319
        For each access where a test would be asserted to guarantee the
paul@44 320
        nature of an attribute, the following formats are employed:
paul@44 321
paul@44 322
        location " " attribute name " " "validate"
paul@44 323
        location " " attribute name " " "specific" " " attribute type " " object type
paul@44 324
paul@44 325
        ----
paul@44 326
paul@44 327
        References that cannot be supported by any types are written to a
paul@44 328
        warnings file in the following format:
paul@44 329
paul@44 330
        location
paul@44 331
        """
paul@44 332
paul@44 333
        f_attr_summary = open(join(self.output, "attribute_summary"), "w")
paul@44 334
        f_attrs = open(join(self.output, "attributes"), "w")
paul@44 335
        f_tests = open(join(self.output, "tests"), "w")
paul@44 336
        f_warnings = open(join(self.output, "attribute_warnings"), "w")
paul@44 337
paul@44 338
        try:
paul@44 339
            locations = self.referenced_attrs.keys()
paul@44 340
            locations.sort()
paul@44 341
paul@44 342
            for location in locations:
paul@44 343
                constrained = location in self.access_constrained
paul@44 344
paul@44 345
                # Attribute information, both name-based and anonymous.
paul@44 346
paul@44 347
                referenced_attrs = self.referenced_attrs[location]
paul@44 348
paul@44 349
                if referenced_attrs:
paul@44 350
                    attrname = get_attrname_from_location(location)
paul@44 351
paul@44 352
                    all_accessed_attrs = self.reference_all_attrs[location]
paul@44 353
paul@44 354
                    for attrtype, attrs in self.get_referenced_attrs(location):
paul@44 355
                        print >>f_attrs, encode_access_location(location), encode_constrained(constrained), attrtype, sorted_output(attrs)
paul@44 356
paul@44 357
                    test_type = self.reference_test_types.get(location)
paul@44 358
paul@44 359
                    # Write the need to test at run time.
paul@44 360
paul@44 361
                    if test_type == "validate":
paul@44 362
                        print >>f_tests, encode_access_location(location), test_type
paul@44 363
paul@44 364
                    # Write any type checks for anonymous accesses.
paul@44 365
paul@44 366
                    elif test_type and self.reference_test_accessor_types.get(location):
paul@44 367
                        print >>f_tests, encode_access_location(location), test_type, \
paul@44 368
                            sorted_output(all_accessed_attrs), \
paul@44 369
                            self.reference_test_accessor_types[location]
paul@44 370
paul@44 371
                    print >>f_attr_summary, encode_access_location(location), encode_constrained(constrained), \
paul@44 372
                        test_type or "untested", sorted_output(all_accessed_attrs)
paul@44 373
paul@44 374
                else:
paul@44 375
                    print >>f_warnings, encode_access_location(location)
paul@44 376
paul@44 377
        finally:
paul@44 378
            f_attr_summary.close()
paul@44 379
            f_attrs.close()
paul@44 380
            f_tests.close()
paul@44 381
            f_warnings.close()
paul@44 382
paul@67 383
    def write_access_plans(self):
paul@67 384
paul@67 385
        "Each attribute access is written out as a plan."
paul@67 386
paul@67 387
        f_attrs = open(join(self.output, "attribute_plans"), "w")
paul@67 388
paul@67 389
        try:
paul@67 390
            locations = self.access_plans.keys()
paul@67 391
            locations.sort()
paul@67 392
paul@67 393
            for location in locations:
paul@67 394
                base, traversed, attrnames, method, test, attr = self.access_plans[location]
paul@67 395
                print >>f_attrs, encode_access_location(location), base, \
paul@67 396
                                 ".".join(traversed) or "{}", \
paul@67 397
                                 ".".join(attrnames) or "{}", \
paul@67 398
                                 method, test, \
paul@67 399
                                 attr or "{}"
paul@67 400
paul@67 401
        finally:
paul@67 402
            f_attrs.close()
paul@67 403
paul@44 404
    def classify_accessors(self):
paul@44 405
paul@44 406
        "For each program location, classify accessors."
paul@44 407
paul@44 408
        # Where instance and module types are defined, class types are also
paul@44 409
        # defined. See: init_definition_details
paul@44 410
paul@44 411
        locations = self.accessor_class_types.keys()
paul@44 412
paul@44 413
        for location in locations:
paul@67 414
            constrained = location in self.accessor_constrained
paul@44 415
paul@44 416
            # Provider information.
paul@44 417
paul@44 418
            class_types = self.provider_class_types[location]
paul@44 419
            instance_types = self.provider_instance_types[location]
paul@44 420
            module_types = self.provider_module_types[location]
paul@44 421
paul@44 422
            # Collect specific and general type information.
paul@44 423
paul@44 424
            self.provider_all_types[location] = all_types = \
paul@57 425
                combine_types(class_types, instance_types, module_types)
paul@44 426
paul@44 427
            # Accessor information.
paul@44 428
paul@44 429
            class_types = self.accessor_class_types[location]
paul@44 430
            self.accessor_general_class_types[location] = \
paul@44 431
                general_class_types = self.get_most_general_types(class_types)
paul@44 432
paul@44 433
            instance_types = self.accessor_instance_types[location]
paul@44 434
            self.accessor_general_instance_types[location] = \
paul@44 435
                general_instance_types = self.get_most_general_types(instance_types)
paul@44 436
paul@44 437
            module_types = self.accessor_module_types[location]
paul@44 438
            self.accessor_general_module_types[location] = \
paul@44 439
                general_module_types = self.get_most_general_module_types(module_types)
paul@44 440
paul@44 441
            # Collect specific and general type information.
paul@44 442
paul@44 443
            self.accessor_all_types[location] = all_types = \
paul@57 444
                combine_types(class_types, instance_types, module_types)
paul@44 445
paul@44 446
            self.accessor_all_general_types[location] = all_general_types = \
paul@57 447
                combine_types(general_class_types, general_instance_types, general_module_types)
paul@44 448
paul@44 449
            # Record guard information.
paul@44 450
paul@44 451
            if not constrained:
paul@44 452
paul@44 453
                # Record specific type guard details.
paul@44 454
paul@44 455
                if len(all_types) == 1:
paul@67 456
                    self.accessor_guard_tests[location] = test_for_type("specific", first(all_types))
paul@57 457
                elif is_single_class_type(all_types):
paul@44 458
                    self.accessor_guard_tests[location] = "specific-object"
paul@44 459
paul@44 460
                # Record common type guard details.
paul@44 461
paul@44 462
                elif len(all_general_types) == 1:
paul@67 463
                    self.accessor_guard_tests[location] = test_for_type("common", first(all_types))
paul@57 464
                elif is_single_class_type(all_general_types):
paul@44 465
                    self.accessor_guard_tests[location] = "common-object"
paul@44 466
paul@44 467
                # Otherwise, no convenient guard can be defined.
paul@44 468
paul@44 469
    def classify_accesses(self):
paul@44 470
paul@44 471
        "For each program location, classify accesses."
paul@44 472
paul@44 473
        # Attribute accesses use potentially different locations to those of
paul@44 474
        # accessors.
paul@44 475
paul@44 476
        locations = self.referenced_attrs.keys()
paul@44 477
paul@44 478
        for location in locations:
paul@44 479
            constrained = location in self.access_constrained
paul@44 480
paul@44 481
            # Determine whether the attribute access is guarded or not.
paul@44 482
paul@44 483
            accessor_locations = self.get_accessors_for_access(location)
paul@44 484
paul@44 485
            all_provider_types = set()
paul@44 486
            all_accessor_types = set()
paul@44 487
            all_accessor_general_types = set()
paul@44 488
paul@44 489
            for accessor_location in accessor_locations:
paul@44 490
paul@44 491
                # Obtain the provider types for guard-related attribute access
paul@44 492
                # checks.
paul@44 493
paul@67 494
                all_provider_types.update(self.provider_all_types.get(accessor_location))
paul@67 495
paul@67 496
                # Obtain the accessor guard types (specific and general).
paul@67 497
paul@67 498
                all_accessor_types.update(self.accessor_all_types.get(accessor_location))
paul@67 499
                all_accessor_general_types.update(self.accessor_all_general_types.get(accessor_location))
paul@44 500
paul@44 501
            # Determine the basis on which the access has been guarded.
paul@44 502
paul@44 503
            guarded = (
paul@44 504
                len(all_accessor_types) == 1 or
paul@57 505
                is_single_class_type(all_accessor_types) or
paul@44 506
                len(all_accessor_general_types) == 1 or
paul@57 507
                is_single_class_type(all_accessor_general_types)
paul@44 508
                )
paul@44 509
paul@44 510
            if guarded:
paul@44 511
                (guard_class_types, guard_instance_types, guard_module_types,
paul@57 512
                    _function_types, _var_types) = separate_types(all_provider_types)
paul@44 513
paul@67 514
            self.reference_all_accessor_types[location] = all_accessor_types
paul@67 515
            self.reference_all_accessor_general_types[location] = all_accessor_general_types
paul@63 516
paul@44 517
            # Attribute information, both name-based and anonymous.
paul@44 518
paul@44 519
            referenced_attrs = self.referenced_attrs[location]
paul@44 520
paul@44 521
            if referenced_attrs:
paul@44 522
paul@44 523
                # Record attribute information for each name used on the
paul@44 524
                # accessor.
paul@44 525
paul@44 526
                attrname = get_attrname_from_location(location)
paul@44 527
paul@44 528
                all_accessed_attrs = set()
paul@44 529
                all_accessed_attrtypes = set()
paul@44 530
                all_providers = set()
paul@44 531
                all_general_providers = set()
paul@44 532
paul@44 533
                for attrtype, d, general in [
paul@44 534
                    ("<class>", self.reference_class_attrs, self.get_most_general_types),
paul@44 535
                    ("<instance>", self.reference_instance_attrs, self.get_most_general_types),
paul@44 536
                    ("<module>", self.reference_module_attrs, self.get_most_general_module_types)]:
paul@44 537
paul@44 538
                    attrs = [attr for _attrtype, object_type, attr in referenced_attrs if _attrtype == attrtype]
paul@44 539
                    providers = [object_type for _attrtype, object_type, attr in referenced_attrs if _attrtype == attrtype]
paul@44 540
                    general_providers = general(providers)
paul@44 541
                    d[location] = set(attrs)
paul@44 542
paul@44 543
                    if attrs:
paul@44 544
                        all_accessed_attrs.update(attrs)
paul@44 545
                        all_accessed_attrtypes.add(attrtype)
paul@44 546
                        all_providers.update(providers)
paul@44 547
                        all_general_providers.update(general_providers)
paul@44 548
paul@44 549
                # Determine which attributes would be provided by the
paul@44 550
                # accessor types upheld by a guard.
paul@44 551
paul@44 552
                if guarded:
paul@44 553
                    guard_attrs = [attr for _attrtype, object_type, attr in
paul@44 554
                        self._identify_reference_attribute(attrname, guard_class_types, guard_instance_types, guard_module_types)]
paul@44 555
                else:
paul@44 556
                    guard_attrs = None
paul@44 557
paul@44 558
                self.reference_all_attrs[location] = all_accessed_attrs
paul@44 559
                self.reference_all_attrtypes[location] = all_accessed_attrtypes
paul@44 560
paul@44 561
                # Suitably guarded accesses, where the nature of the
paul@44 562
                # accessor can be guaranteed, do not require the attribute
paul@44 563
                # involved to be validated. Otherwise, for unguarded
paul@44 564
                # accesses, access-level tests are required.
paul@44 565
paul@44 566
                if not constrained:
paul@44 567
paul@44 568
                    # Provide informational test types.
paul@44 569
paul@44 570
                    if guarded and all_accessed_attrs.issubset(guard_attrs):
paul@44 571
                        if len(all_accessor_types) == 1:
paul@67 572
                            self.reference_test_types[location] = test_for_type("guarded-specific", first(all_accessor_types))
paul@57 573
                        elif is_single_class_type(all_accessor_types):
paul@44 574
                            self.reference_test_types[location] = "guarded-specific-object"
paul@44 575
                        elif len(all_accessor_general_types) == 1:
paul@67 576
                            self.reference_test_types[location] = test_for_type("guarded-common", first(all_accessor_general_types))
paul@57 577
                        elif is_single_class_type(all_accessor_general_types):
paul@44 578
                            self.reference_test_types[location] = "guarded-common-object"
paul@44 579
paul@44 580
                    # Provide active test types.
paul@44 581
paul@44 582
                    else:
paul@44 583
                        # Record the need to test the type of anonymous and
paul@44 584
                        # unconstrained accessors.
paul@44 585
paul@44 586
                        if len(all_providers) == 1:
paul@44 587
                            provider = list(all_providers)[0]
paul@44 588
                            if provider != '__builtins__.object':
paul@56 589
                                all_accessor_kinds = set(get_kinds(all_accessor_types))
paul@44 590
                                if len(all_accessor_kinds) == 1:
paul@56 591
                                    test_type = test_for_kinds("specific", all_accessor_kinds)
paul@44 592
                                else:
paul@44 593
                                    test_type = "specific-object"
paul@44 594
                                self.reference_test_types[location] = test_type
paul@44 595
                                self.reference_test_accessor_types[location] = provider
paul@44 596
paul@44 597
                        elif len(all_general_providers) == 1:
paul@44 598
                            provider = list(all_general_providers)[0]
paul@44 599
                            if provider != '__builtins__.object':
paul@56 600
                                all_accessor_kinds = set(get_kinds(all_accessor_general_types))
paul@44 601
                                if len(all_accessor_kinds) == 1:
paul@56 602
                                    test_type = test_for_kinds("common", all_accessor_kinds)
paul@44 603
                                else:
paul@44 604
                                    test_type = "common-object"
paul@44 605
                                self.reference_test_types[location] = test_type
paul@44 606
                                self.reference_test_accessor_types[location] = provider
paul@44 607
paul@44 608
                        # Record the need to test the identity of the attribute.
paul@44 609
paul@44 610
                        else:
paul@44 611
                            self.reference_test_types[location] = "validate"
paul@44 612
paul@67 613
    def initialise_access_plans(self):
paul@67 614
paul@67 615
        "Define attribute access plans."
paul@67 616
paul@67 617
        for location in self.referenced_attrs.keys():
paul@67 618
            self.access_plans[location] = self.get_access_plan(location)
paul@67 619
paul@44 620
    def get_referenced_attrs(self, location):
paul@44 621
paul@44 622
        """
paul@44 623
        Return attributes referenced at the given access 'location' by the given
paul@44 624
        'attrname' as a list of (attribute type, attribute set) tuples.
paul@44 625
        """
paul@44 626
paul@44 627
        ca = self.reference_class_attrs[location]
paul@44 628
        ia = self.reference_instance_attrs[location]
paul@44 629
        ma = self.reference_module_attrs[location]
paul@44 630
paul@44 631
        l = []
paul@44 632
        for attrtype, attrs in (("<class>", ca), ("<instance>", ia), ("<module>", ma)):
paul@44 633
            if attrs:
paul@44 634
                l.append((attrtype, attrs))
paul@44 635
        return l
paul@44 636
paul@44 637
    # Initialisation methods.
paul@44 638
paul@44 639
    def init_descendants(self):
paul@44 640
paul@44 641
        "Identify descendants of each class."
paul@44 642
paul@44 643
        for name in self.importer.classes.keys():
paul@44 644
            self.get_descendants_for_class(name)
paul@44 645
paul@44 646
    def get_descendants_for_class(self, name):
paul@44 647
paul@44 648
        """
paul@44 649
        Use subclass information to deduce the descendants for the class of the
paul@44 650
        given 'name'.
paul@44 651
        """
paul@44 652
paul@44 653
        if not self.descendants.has_key(name):
paul@44 654
            descendants = set()
paul@44 655
paul@44 656
            for subclass in self.importer.subclasses[name]:
paul@44 657
                descendants.update(self.get_descendants_for_class(subclass))
paul@44 658
                descendants.add(subclass)
paul@44 659
paul@44 660
            self.descendants[name] = descendants
paul@44 661
paul@44 662
        return self.descendants[name]
paul@44 663
paul@44 664
    def init_special_attributes(self):
paul@44 665
paul@44 666
        "Add special attributes to the classes for inheritance-related tests."
paul@44 667
paul@44 668
        all_class_attrs = self.importer.all_class_attrs
paul@44 669
paul@44 670
        for name, descendants in self.descendants.items():
paul@44 671
            for descendant in descendants:
paul@44 672
                all_class_attrs[descendant]["#%s" % name] = name
paul@44 673
paul@44 674
        for name in all_class_attrs.keys():
paul@44 675
            all_class_attrs[name]["#%s" % name] = name
paul@44 676
paul@44 677
    def init_usage_index(self):
paul@44 678
paul@44 679
        """
paul@44 680
        Create indexes for module and function attribute usage and for anonymous
paul@44 681
        accesses.
paul@44 682
        """
paul@44 683
paul@44 684
        for module in self.importer.get_modules():
paul@44 685
            for path, assignments in module.attr_usage.items():
paul@44 686
                self.add_usage(assignments, path)
paul@44 687
paul@44 688
        for location, all_attrnames in self.importer.all_attr_accesses.items():
paul@44 689
            for attrnames in all_attrnames:
paul@44 690
                attrname = get_attrnames(attrnames)[-1]
paul@44 691
                access_location = (location, None, attrnames, 0)
paul@44 692
                self.add_usage_term(access_location, [attrname])
paul@44 693
paul@44 694
    def add_usage(self, assignments, path):
paul@44 695
paul@44 696
        """
paul@44 697
        Collect usage from the given 'assignments', adding 'path' details to
paul@44 698
        each record if specified. Add the usage to an index mapping to location
paul@44 699
        information, as well as to an index mapping locations to usages.
paul@44 700
        """
paul@44 701
paul@44 702
        for name, versions in assignments.items():
paul@44 703
            for i, usages in enumerate(versions):
paul@44 704
                location = (path, name, None, i)
paul@44 705
paul@44 706
                for attrnames in usages:
paul@44 707
                    self.add_usage_term(location, attrnames)
paul@44 708
paul@44 709
    def add_usage_term(self, location, attrnames):
paul@44 710
paul@44 711
        """
paul@44 712
        For 'location' and using 'attrnames' as a description of usage, record
paul@44 713
        in the usage index a mapping from the usage to 'location', and record in
paul@44 714
        the location index a mapping from 'location' to the usage.
paul@44 715
        """
paul@44 716
paul@44 717
        key = make_key(attrnames)
paul@44 718
paul@44 719
        init_item(self.location_index, location, set)
paul@44 720
        self.location_index[location].add(key)
paul@44 721
paul@44 722
    def init_accessors(self):
paul@44 723
paul@44 724
        "Create indexes for module and function accessor information."
paul@44 725
paul@44 726
        for module in self.importer.get_modules():
paul@44 727
            for path, all_accesses in module.attr_accessors.items():
paul@44 728
                self.add_accessors(all_accesses, path)
paul@44 729
paul@44 730
    def add_accessors(self, all_accesses, path):
paul@44 731
paul@44 732
        """
paul@44 733
        For attribute accesses described by the mapping of 'all_accesses' from
paul@44 734
        name details to accessor details, record the locations of the accessors
paul@44 735
        for each access.
paul@44 736
        """
paul@44 737
paul@44 738
        # Get details for each access combining the given name and attribute.
paul@44 739
paul@44 740
        for (name, attrnames), accesses in all_accesses.items():
paul@44 741
paul@44 742
            # Obtain the usage details using the access information.
paul@44 743
paul@44 744
            for access_number, versions in enumerate(accesses):
paul@44 745
                access_location = (path, name, attrnames, access_number)
paul@44 746
                locations = []
paul@44 747
paul@44 748
                for version in versions:
paul@44 749
                    location = (path, name, None, version)
paul@44 750
                    locations.append(location)
paul@44 751
paul@44 752
                self.access_index[access_location] = locations
paul@44 753
paul@44 754
    def get_accessors_for_access(self, access_location):
paul@44 755
paul@44 756
        "Find a definition providing accessor details, if necessary."
paul@44 757
paul@44 758
        try:
paul@44 759
            return self.access_index[access_location]
paul@44 760
        except KeyError:
paul@44 761
            return [access_location]
paul@44 762
paul@44 763
    def init_accesses(self):
paul@44 764
paul@44 765
        """
paul@44 766
        Initialise collections for accesses involving assignments.
paul@44 767
        """
paul@44 768
paul@44 769
        # For each scope, obtain access details.
paul@44 770
paul@44 771
        for path, all_accesses in self.importer.all_attr_access_modifiers.items():
paul@44 772
paul@44 773
            # For each combination of name and attribute names, obtain
paul@44 774
            # applicable modifiers.
paul@44 775
paul@44 776
            for (name, attrnames), modifiers in all_accesses.items():
paul@44 777
paul@44 778
                # For each access, determine the name versions affected by
paul@44 779
                # assignments.
paul@44 780
paul@44 781
                for access_number, assignment in enumerate(modifiers):
paul@44 782
                    if name:
paul@44 783
                        access_location = (path, name, attrnames, access_number)
paul@44 784
                    else:
paul@44 785
                        access_location = (path, None, attrnames, 0)
paul@44 786
paul@44 787
                    # Associate assignments with usage.
paul@44 788
paul@44 789
                    accessor_locations = self.get_accessors_for_access(access_location)
paul@44 790
paul@44 791
                    for location in accessor_locations:
paul@44 792
                        for usage in self.location_index[location]:
paul@44 793
                            key = make_key(usage)
paul@44 794
paul@44 795
                            if assignment:
paul@44 796
                                init_item(self.assigned_attrs, key, set)
paul@44 797
                                self.assigned_attrs[key].add((path, name, attrnames))
paul@44 798
paul@44 799
    def init_aliases(self):
paul@44 800
paul@44 801
        "Expand aliases so that alias-based accesses can be resolved."
paul@44 802
paul@44 803
        # Get aliased names with details of their accesses.
paul@44 804
paul@44 805
        for name_path, all_aliases in self.importer.all_aliased_names.items():
paul@44 806
            path, name = name_path.rsplit(".", 1)
paul@44 807
paul@44 808
            # For each version of the name, obtain the access location.
paul@44 809
paul@44 810
            for version, (original_name, attrnames, access_number) in all_aliases.items():
paul@44 811
                accessor_location = (path, name, None, version)
paul@44 812
                access_location = (path, original_name, attrnames, access_number)
paul@44 813
                init_item(self.alias_index, accessor_location, list)
paul@44 814
                self.alias_index[accessor_location].append(access_location)
paul@44 815
paul@44 816
        # Get aliases in terms of non-aliases and accesses.
paul@44 817
paul@44 818
        for accessor_location, access_locations in self.alias_index.items():
paul@44 819
            self.update_aliases(accessor_location, access_locations)
paul@44 820
paul@44 821
    def update_aliases(self, accessor_location, access_locations, visited=None):
paul@44 822
paul@44 823
        """
paul@44 824
        Update the given 'accessor_location' defining an alias, update
paul@44 825
        'access_locations' to refer to non-aliases, following name references
paul@44 826
        via the access index.
paul@44 827
paul@44 828
        If 'visited' is specified, it contains a set of accessor locations (and
paul@44 829
        thus keys to the alias index) that are currently being defined.
paul@44 830
        """
paul@44 831
paul@44 832
        if visited is None:
paul@44 833
            visited = set()
paul@44 834
paul@44 835
        updated_locations = set()
paul@44 836
paul@44 837
        for access_location in access_locations:
paul@44 838
            (path, original_name, attrnames, access_number) = access_location
paul@44 839
paul@44 840
            # Where an alias refers to a name access, obtain the original name
paul@44 841
            # version details.
paul@44 842
paul@44 843
            if attrnames is None:
paul@44 844
paul@44 845
                # For each name version, attempt to determine any accesses that
paul@44 846
                # initialise the name.
paul@44 847
paul@44 848
                for name_accessor_location in self.access_index[access_location]:
paul@44 849
paul@44 850
                    # Already-visited aliases do not contribute details.
paul@44 851
paul@44 852
                    if name_accessor_location in visited:
paul@44 853
                        continue
paul@44 854
paul@44 855
                    visited.add(name_accessor_location)
paul@44 856
paul@44 857
                    name_access_locations = self.alias_index.get(name_accessor_location)
paul@44 858
                    if name_access_locations:
paul@44 859
                        updated_locations.update(self.update_aliases(name_accessor_location, name_access_locations, visited))
paul@44 860
                    else:
paul@44 861
                        updated_locations.add(name_accessor_location)
paul@44 862
paul@44 863
            # Otherwise, record the access details.
paul@44 864
paul@44 865
            else:
paul@44 866
                updated_locations.add(access_location)
paul@44 867
paul@44 868
        self.alias_index[accessor_location] = updated_locations
paul@44 869
        return updated_locations
paul@44 870
paul@44 871
    # Attribute mutation for types.
paul@44 872
paul@44 873
    def modify_mutated_attributes(self):
paul@44 874
paul@44 875
        "Identify known, mutated attributes and change their state."
paul@44 876
paul@44 877
        # Usage-based accesses.
paul@44 878
paul@44 879
        for usage, all_attrnames in self.assigned_attrs.items():
paul@44 880
            if not usage:
paul@44 881
                continue
paul@44 882
paul@44 883
            for path, name, attrnames in all_attrnames:
paul@44 884
                class_types = self.get_class_types_for_usage(usage)
paul@44 885
                only_instance_types = set(self.get_instance_types_for_usage(usage)).difference(class_types)
paul@44 886
                module_types = self.get_module_types_for_usage(usage)
paul@44 887
paul@44 888
                # Detect self usage within methods in order to narrow the scope
paul@44 889
                # of the mutation.
paul@44 890
paul@44 891
                t = name == "self" and self.constrain_self_reference(path, class_types, only_instance_types)
paul@44 892
                if t:
paul@44 893
                    class_types, only_instance_types, module_types, constrained = t
paul@44 894
                objects = set(class_types).union(only_instance_types).union(module_types)
paul@44 895
paul@44 896
                self.mutate_attribute(objects, attrnames)
paul@44 897
paul@44 898
    def mutate_attribute(self, objects, attrnames):
paul@44 899
paul@44 900
        "Mutate static 'objects' with the given 'attrnames'."
paul@44 901
paul@44 902
        for name in objects:
paul@44 903
            attr = "%s.%s" % (name, attrnames)
paul@44 904
            value = self.importer.get_object(attr)
paul@44 905
paul@44 906
            # If the value is None, the attribute is
paul@44 907
            # inherited and need not be set explicitly on
paul@44 908
            # the class concerned.
paul@44 909
paul@44 910
            if value:
paul@44 911
                self.modified_attributes[attr] = value
paul@44 912
                self.importer.set_object(attr, value.as_var())
paul@44 913
paul@44 914
    # Simplification of types.
paul@44 915
paul@44 916
    def get_most_general_types(self, class_types):
paul@44 917
paul@44 918
        "Return the most general types for the given 'class_types'."
paul@44 919
paul@44 920
        class_types = set(class_types)
paul@44 921
        to_remove = set()
paul@44 922
paul@44 923
        for class_type in class_types:
paul@44 924
            for base in self.importer.classes[class_type]:
paul@44 925
                base = base.get_origin()
paul@44 926
                descendants = self.descendants[base]
paul@44 927
                if base in class_types and descendants.issubset(class_types):
paul@44 928
                    to_remove.update(descendants)
paul@44 929
paul@44 930
        class_types.difference_update(to_remove)
paul@44 931
        return class_types
paul@44 932
paul@44 933
    def get_most_general_module_types(self, module_types):
paul@44 934
paul@44 935
        "Return the most general type for the given 'module_types'."
paul@44 936
paul@44 937
        # Where all modules are provided, an object would provide the same
paul@44 938
        # attributes.
paul@44 939
paul@44 940
        if len(module_types) == len(self.importer.modules):
paul@44 941
            return ["__builtins__.object"]
paul@44 942
        else:
paul@44 943
            return module_types
paul@44 944
paul@44 945
    # Type deduction for usage.
paul@44 946
paul@44 947
    def get_types_for_usage(self, attrnames, objects):
paul@44 948
paul@44 949
        """
paul@44 950
        Identify the types that can support the given 'attrnames', using the
paul@44 951
        given 'objects' as the catalogue of type details.
paul@44 952
        """
paul@44 953
paul@44 954
        types = []
paul@44 955
        for name, _attrnames in objects.items():
paul@44 956
            if set(attrnames).issubset(_attrnames):
paul@44 957
                types.append(name)
paul@44 958
        return types
paul@44 959
paul@44 960
    # More efficient usage-to-type indexing and retrieval.
paul@44 961
paul@44 962
    def init_attr_type_indexes(self):
paul@44 963
paul@44 964
        "Identify the types that can support each attribute name."
paul@44 965
paul@44 966
        self._init_attr_type_index(self.attr_class_types, self.importer.all_class_attrs)
paul@44 967
        self._init_attr_type_index(self.attr_instance_types, self.importer.all_combined_attrs)
paul@44 968
        self._init_attr_type_index(self.attr_module_types, self.importer.all_module_attrs)
paul@44 969
paul@44 970
    def _init_attr_type_index(self, attr_types, attrs):
paul@44 971
paul@44 972
        """
paul@44 973
        Initialise the 'attr_types' attribute-to-types mapping using the given
paul@44 974
        'attrs' type-to-attributes mapping.
paul@44 975
        """
paul@44 976
paul@44 977
        for name, attrnames in attrs.items():
paul@44 978
            for attrname in attrnames:
paul@44 979
                init_item(attr_types, attrname, set)
paul@44 980
                attr_types[attrname].add(name)
paul@44 981
paul@44 982
    def get_class_types_for_usage(self, attrnames):
paul@44 983
paul@44 984
        "Return names of classes supporting the given 'attrnames'."
paul@44 985
paul@44 986
        return self._get_types_for_usage(attrnames, self.attr_class_types, self.importer.all_class_attrs)
paul@44 987
paul@44 988
    def get_instance_types_for_usage(self, attrnames):
paul@44 989
paul@44 990
        """
paul@44 991
        Return names of classes whose instances support the given 'attrnames'
paul@44 992
        (as either class or instance attributes).
paul@44 993
        """
paul@44 994
paul@44 995
        return self._get_types_for_usage(attrnames, self.attr_instance_types, self.importer.all_combined_attrs)
paul@44 996
paul@44 997
    def get_module_types_for_usage(self, attrnames):
paul@44 998
paul@44 999
        "Return names of modules supporting the given 'attrnames'."
paul@44 1000
paul@44 1001
        return self._get_types_for_usage(attrnames, self.attr_module_types, self.importer.all_module_attrs)
paul@44 1002
paul@44 1003
    def _get_types_for_usage(self, attrnames, attr_types, attrs):
paul@44 1004
paul@44 1005
        """
paul@44 1006
        For the given 'attrnames' representing attribute usage, return types
paul@44 1007
        recorded in the 'attr_types' attribute-to-types mapping that support
paul@44 1008
        such usage, with the given 'attrs' type-to-attributes mapping used to
paul@44 1009
        quickly assess whether a type supports all of the stated attributes.
paul@44 1010
        """
paul@44 1011
paul@44 1012
        # Where no attributes are used, any type would be acceptable.
paul@44 1013
paul@44 1014
        if not attrnames:
paul@44 1015
            return attrs.keys()
paul@44 1016
paul@44 1017
        types = []
paul@44 1018
paul@44 1019
        # Obtain types supporting the first attribute name...
paul@44 1020
paul@44 1021
        for name in attr_types.get(attrnames[0]) or []:
paul@44 1022
paul@44 1023
            # Record types that support all of the other attributes as well.
paul@44 1024
paul@44 1025
            _attrnames = attrs[name]
paul@44 1026
            if set(attrnames).issubset(_attrnames):
paul@44 1027
                types.append(name)
paul@44 1028
paul@44 1029
        return types
paul@44 1030
paul@44 1031
    # Reference identification.
paul@44 1032
paul@44 1033
    def identify_references(self):
paul@44 1034
paul@44 1035
        "Identify references using usage and name reference information."
paul@44 1036
paul@44 1037
        # Names with associated attribute usage.
paul@44 1038
paul@44 1039
        for location, usages in self.location_index.items():
paul@44 1040
paul@44 1041
            # Obtain attribute usage associated with a name, deducing the nature
paul@44 1042
            # of the name. Obtain types only for branches involving attribute
paul@44 1043
            # usage. (In the absence of usage, any type could be involved, but
paul@44 1044
            # then no accesses exist to require knowledge of the type.)
paul@44 1045
paul@44 1046
            have_usage = False
paul@44 1047
            have_no_usage_branch = False
paul@44 1048
paul@44 1049
            for usage in usages:
paul@44 1050
                if not usage:
paul@44 1051
                    have_no_usage_branch = True
paul@44 1052
                    continue
paul@44 1053
                elif not have_usage:
paul@44 1054
                    self.init_definition_details(location)
paul@44 1055
                    have_usage = True
paul@44 1056
                self.record_types_for_usage(location, usage)
paul@44 1057
paul@44 1058
            # Where some usage occurs, but where branches without usage also
paul@44 1059
            # occur, record the types for those branches anyway.
paul@44 1060
paul@44 1061
            if have_usage and have_no_usage_branch:
paul@44 1062
                self.init_definition_details(location)
paul@44 1063
                self.record_types_for_usage(location, None)
paul@44 1064
paul@44 1065
        # Specific name-based attribute accesses.
paul@44 1066
paul@44 1067
        alias_accesses = set()
paul@44 1068
paul@44 1069
        for access_location, accessor_locations in self.access_index.items():
paul@44 1070
            self.record_types_for_access(access_location, accessor_locations, alias_accesses)
paul@44 1071
paul@44 1072
        # Anonymous references with attribute chains.
paul@44 1073
paul@44 1074
        for location, accesses in self.importer.all_attr_accesses.items():
paul@44 1075
paul@44 1076
            # Get distinct attribute names.
paul@44 1077
paul@44 1078
            all_attrnames = set()
paul@44 1079
paul@44 1080
            for attrnames in accesses:
paul@44 1081
                all_attrnames.update(get_attrnames(attrnames))
paul@44 1082
paul@44 1083
            # Get attribute and accessor details for each attribute name.
paul@44 1084
paul@44 1085
            for attrname in all_attrnames:
paul@44 1086
                access_location = (location, None, attrname, 0)
paul@44 1087
                self.record_types_for_attribute(access_location, attrname)
paul@44 1088
paul@44 1089
        # References via constant/identified objects.
paul@44 1090
paul@44 1091
        for location, name_accesses in self.importer.all_const_accesses.items():
paul@44 1092
paul@44 1093
            # A mapping from the original name and attributes to resolved access
paul@44 1094
            # details.
paul@44 1095
paul@44 1096
            for original_access, access in name_accesses.items():
paul@44 1097
                original_name, original_attrnames = original_access
paul@44 1098
                objpath, ref, attrnames = access
paul@44 1099
paul@44 1100
                # Build an accessor combining the name and attribute names used.
paul@44 1101
paul@44 1102
                original_accessor = tuple([original_name] + original_attrnames.split("."))
paul@44 1103
paul@44 1104
                # Direct accesses to attributes.
paul@44 1105
paul@44 1106
                if not attrnames:
paul@44 1107
paul@44 1108
                    # Build a descriptive location based on the original
paul@44 1109
                    # details, exposing the final attribute name.
paul@44 1110
paul@44 1111
                    oa, attrname = original_accessor[:-1], original_accessor[-1]
paul@44 1112
                    oa = ".".join(oa)
paul@44 1113
paul@44 1114
                    access_location = (location, oa, attrname, 0)
paul@44 1115
                    accessor_location = (location, oa, None, 0)
paul@44 1116
                    self.access_index[access_location] = [accessor_location]
paul@44 1117
paul@44 1118
                    self.init_access_details(access_location)
paul@44 1119
                    self.init_definition_details(accessor_location)
paul@44 1120
paul@44 1121
                    # Obtain a reference for the accessor in order to properly
paul@44 1122
                    # determine its type.
paul@44 1123
paul@44 1124
                    if ref.get_kind() != "<instance>":
paul@44 1125
                        objpath = ref.get_origin()
paul@44 1126
paul@44 1127
                    objpath = objpath.rsplit(".", 1)[0]
paul@44 1128
paul@44 1129
                    # Where the object name conflicts with the module
paul@44 1130
                    # providing it, obtain the module details.
paul@44 1131
paul@44 1132
                    if objpath in self.importer.modules:
paul@44 1133
                        accessor = Reference("<module>", objpath)
paul@44 1134
                    else:
paul@44 1135
                        accessor = self.importer.get_object(objpath)
paul@44 1136
paul@44 1137
                    self.referenced_attrs[access_location] = [(accessor.get_kind(), accessor.get_origin(), ref)]
paul@44 1138
                    self.access_constrained.add(access_location)
paul@44 1139
paul@57 1140
                    class_types, instance_types, module_types = accessor.get_types()
paul@44 1141
                    self.record_reference_types(accessor_location, class_types, instance_types, module_types, True, True)
paul@64 1142
paul@64 1143
                else:
paul@44 1144
paul@64 1145
                    # Build a descriptive location based on the original
paul@64 1146
                    # details, employing the first remaining attribute name.
paul@64 1147
paul@64 1148
                    l = get_attrnames(attrnames)
paul@64 1149
                    attrname = l[0]
paul@44 1150
paul@64 1151
                    oa = original_accessor[:-len(l)]
paul@64 1152
                    oa = ".".join(oa)
paul@44 1153
paul@64 1154
                    access_location = (location, oa, attrnames, 0)
paul@64 1155
                    accessor_location = (location, oa, None, 0)
paul@64 1156
                    self.access_index[access_location] = [accessor_location]
paul@64 1157
paul@64 1158
                    self.init_access_details(access_location)
paul@64 1159
                    self.init_definition_details(accessor_location)
paul@44 1160
paul@64 1161
                    class_types, instance_types, module_types = ref.get_types()
paul@64 1162
paul@64 1163
                    self.identify_reference_attributes(access_location, attrname, class_types, instance_types, module_types, True)
paul@64 1164
                    self.record_reference_types(accessor_location, class_types, instance_types, module_types, True, True)
paul@64 1165
paul@64 1166
                original_location = (location, original_name, original_attrnames, 0)
paul@64 1167
paul@64 1168
                if original_location != access_location:
paul@64 1169
                    self.const_accesses[original_location] = access_location
paul@67 1170
                    self.const_accesses_rev[access_location] = original_location
paul@44 1171
paul@64 1172
        # Aliased name definitions. All aliases with usage will have been
paul@64 1173
        # defined, but they may be refined according to referenced accesses.
paul@44 1174
paul@64 1175
        for accessor_location in self.alias_index.keys():
paul@64 1176
            self.record_types_for_alias(accessor_location)
paul@44 1177
paul@64 1178
        # Update accesses employing aliases.
paul@64 1179
paul@64 1180
        for access_location in alias_accesses:
paul@64 1181
            self.record_types_for_access(access_location, self.access_index[access_location])
paul@44 1182
paul@44 1183
    def constrain_types(self, path, class_types, instance_types, module_types):
paul@44 1184
paul@44 1185
        """
paul@44 1186
        Using the given 'path' to an object, constrain the given 'class_types',
paul@44 1187
        'instance_types' and 'module_types'.
paul@44 1188
paul@44 1189
        Return the class, instance, module types plus whether the types are
paul@44 1190
        constrained to a specific kind of type.
paul@44 1191
        """
paul@44 1192
paul@44 1193
        ref = self.importer.identify(path)
paul@44 1194
        if ref:
paul@44 1195
paul@44 1196
            # Constrain usage suggestions using the identified object.
paul@44 1197
paul@44 1198
            if ref.has_kind("<class>"):
paul@44 1199
                return (
paul@44 1200
                    set(class_types).intersection([ref.get_origin()]), [], [], True
paul@44 1201
                    )
paul@44 1202
            elif ref.has_kind("<module>"):
paul@44 1203
                return (
paul@44 1204
                    [], [], set(module_types).intersection([ref.get_origin()]), True
paul@44 1205
                    )
paul@44 1206
paul@44 1207
        return class_types, instance_types, module_types, False
paul@44 1208
paul@44 1209
    def get_target_types(self, location, usage):
paul@44 1210
paul@44 1211
        """
paul@44 1212
        Return the class, instance and module types constrained for the name at
paul@44 1213
        the given 'location' exhibiting the given 'usage'. Whether the types
paul@44 1214
        have been constrained using contextual information is also indicated,
paul@44 1215
        plus whether the types have been constrained to a specific kind of type.
paul@44 1216
        """
paul@44 1217
paul@44 1218
        unit_path, name, attrnames, version = location
paul@44 1219
paul@44 1220
        # Detect any initialised name for the location.
paul@44 1221
paul@44 1222
        if name:
paul@44 1223
            ref = self.get_initialised_name(location)
paul@44 1224
            if ref:
paul@44 1225
                (class_types, only_instance_types, module_types,
paul@57 1226
                    _function_types, _var_types) = separate_types([ref])
paul@44 1227
                return class_types, only_instance_types, module_types, True, False
paul@44 1228
paul@44 1229
        # Retrieve the recorded types for the usage.
paul@44 1230
paul@44 1231
        class_types = self.get_class_types_for_usage(usage)
paul@44 1232
        only_instance_types = set(self.get_instance_types_for_usage(usage)).difference(class_types)
paul@44 1233
        module_types = self.get_module_types_for_usage(usage)
paul@44 1234
paul@44 1235
        # Merge usage deductions with observations to obtain reference types
paul@44 1236
        # for names involved with attribute accesses.
paul@44 1237
paul@44 1238
        if not name:
paul@44 1239
            return class_types, only_instance_types, module_types, False, False
paul@44 1240
paul@44 1241
        # Obtain references to known objects.
paul@44 1242
paul@44 1243
        path = self.get_name_path(unit_path, name)
paul@44 1244
paul@44 1245
        class_types, only_instance_types, module_types, constrained_specific = \
paul@44 1246
            self.constrain_types(path, class_types, only_instance_types, module_types)
paul@44 1247
paul@44 1248
        if constrained_specific:
paul@44 1249
            return class_types, only_instance_types, module_types, constrained_specific, constrained_specific
paul@44 1250
paul@44 1251
        # Constrain "self" references.
paul@44 1252
paul@44 1253
        if name == "self":
paul@44 1254
            t = self.constrain_self_reference(unit_path, class_types, only_instance_types)
paul@44 1255
            if t:
paul@44 1256
                class_types, only_instance_types, module_types, constrained = t
paul@44 1257
                return class_types, only_instance_types, module_types, constrained, False
paul@44 1258
paul@44 1259
        return class_types, only_instance_types, module_types, False, False
paul@44 1260
paul@44 1261
    def constrain_self_reference(self, unit_path, class_types, only_instance_types):
paul@44 1262
paul@44 1263
        """
paul@44 1264
        Where the name "self" appears in a method, attempt to constrain the
paul@44 1265
        classes involved.
paul@44 1266
paul@44 1267
        Return the class, instance, module types plus whether the types are
paul@44 1268
        constrained.
paul@44 1269
        """
paul@44 1270
paul@44 1271
        class_name = self.in_method(unit_path)
paul@44 1272
paul@44 1273
        if not class_name:
paul@44 1274
            return None
paul@44 1275
paul@44 1276
        classes = set([class_name])
paul@44 1277
        classes.update(self.get_descendants_for_class(class_name))
paul@44 1278
paul@44 1279
        # Note that only instances will be expected for these references but
paul@44 1280
        # either classes or instances may provide the attributes.
paul@44 1281
paul@44 1282
        return (
paul@44 1283
            set(class_types).intersection(classes),
paul@44 1284
            set(only_instance_types).intersection(classes),
paul@44 1285
            [], True
paul@44 1286
            )
paul@44 1287
paul@44 1288
    def in_method(self, path):
paul@44 1289
paul@44 1290
        "Return whether 'path' refers to a method."
paul@44 1291
paul@44 1292
        class_name, method_name = path.rsplit(".", 1)
paul@44 1293
        return self.importer.classes.has_key(class_name) and class_name
paul@44 1294
paul@44 1295
    def init_reference_details(self, location):
paul@44 1296
paul@44 1297
        "Initialise reference-related details for 'location'."
paul@44 1298
paul@44 1299
        self.init_definition_details(location)
paul@44 1300
        self.init_access_details(location)
paul@44 1301
paul@44 1302
    def init_definition_details(self, location):
paul@44 1303
paul@44 1304
        "Initialise name definition details for 'location'."
paul@44 1305
paul@44 1306
        self.accessor_class_types[location] = set()
paul@44 1307
        self.accessor_instance_types[location] = set()
paul@44 1308
        self.accessor_module_types[location] = set()
paul@44 1309
        self.provider_class_types[location] = set()
paul@44 1310
        self.provider_instance_types[location] = set()
paul@44 1311
        self.provider_module_types[location] = set()
paul@44 1312
paul@44 1313
    def init_access_details(self, location):
paul@44 1314
paul@44 1315
        "Initialise access details at 'location'."
paul@44 1316
paul@44 1317
        self.referenced_attrs[location] = {}
paul@44 1318
paul@44 1319
    def record_types_for_access(self, access_location, accessor_locations, alias_accesses=None):
paul@44 1320
paul@44 1321
        """
paul@44 1322
        Define types for the 'access_location' associated with the given
paul@44 1323
        'accessor_locations'.
paul@44 1324
        """
paul@44 1325
paul@44 1326
        path, name, attrnames, version = access_location
paul@44 1327
        if not attrnames:
paul@44 1328
            return
paul@44 1329
paul@44 1330
        attrname = get_attrnames(attrnames)[0]
paul@44 1331
paul@44 1332
        # Collect all suggested types for the accessors. Accesses may
paul@44 1333
        # require accessors from of a subset of the complete set of types.
paul@44 1334
paul@44 1335
        class_types = set()
paul@44 1336
        module_types = set()
paul@44 1337
        instance_types = set()
paul@44 1338
paul@44 1339
        constrained = True
paul@44 1340
paul@44 1341
        for location in accessor_locations:
paul@44 1342
paul@44 1343
            # Remember accesses employing aliases.
paul@44 1344
paul@44 1345
            if alias_accesses is not None and self.alias_index.has_key(location):
paul@44 1346
                alias_accesses.add(access_location)
paul@44 1347
paul@44 1348
            # Use the type information deduced for names from above.
paul@44 1349
paul@44 1350
            if self.accessor_class_types.has_key(location):
paul@44 1351
                class_types.update(self.accessor_class_types[location])
paul@44 1352
                module_types.update(self.accessor_module_types[location])
paul@44 1353
                instance_types.update(self.accessor_instance_types[location])
paul@44 1354
paul@44 1355
            # Where accesses are associated with assignments but where no
paul@44 1356
            # attribute usage observations have caused such an association,
paul@44 1357
            # the attribute name is considered by itself.
paul@44 1358
paul@44 1359
            else:
paul@44 1360
                self.init_definition_details(location)
paul@44 1361
                self.record_types_for_usage(location, [attrname])
paul@44 1362
paul@67 1363
            constrained = location in self.accessor_constrained and constrained
paul@44 1364
paul@44 1365
        self.init_access_details(access_location)
paul@44 1366
        self.identify_reference_attributes(access_location, attrname, class_types, instance_types, module_types, constrained)
paul@44 1367
paul@44 1368
    def record_types_for_usage(self, accessor_location, usage):
paul@44 1369
paul@44 1370
        """
paul@44 1371
        Record types for the given 'accessor_location' according to the given
paul@44 1372
        'usage' observations which may be None to indicate an absence of usage.
paul@44 1373
        """
paul@44 1374
paul@44 1375
        (class_types,
paul@44 1376
         instance_types,
paul@44 1377
         module_types,
paul@44 1378
         constrained,
paul@44 1379
         constrained_specific) = self.get_target_types(accessor_location, usage)
paul@44 1380
paul@44 1381
        self.record_reference_types(accessor_location, class_types, instance_types, module_types, constrained, constrained_specific)
paul@44 1382
paul@44 1383
    def record_types_for_attribute(self, access_location, attrname):
paul@44 1384
paul@44 1385
        """
paul@44 1386
        Record types for the 'access_location' employing only the given
paul@44 1387
        'attrname' for type deduction.
paul@44 1388
        """
paul@44 1389
paul@44 1390
        usage = [attrname]
paul@44 1391
paul@44 1392
        class_types = self.get_class_types_for_usage(usage)
paul@44 1393
        only_instance_types = set(self.get_instance_types_for_usage(usage)).difference(class_types)
paul@44 1394
        module_types = self.get_module_types_for_usage(usage)
paul@44 1395
paul@44 1396
        self.init_reference_details(access_location)
paul@44 1397
paul@44 1398
        self.identify_reference_attributes(access_location, attrname, class_types, only_instance_types, module_types, False)
paul@44 1399
        self.record_reference_types(access_location, class_types, only_instance_types, module_types, False)
paul@44 1400
paul@44 1401
    def record_types_for_alias(self, accessor_location):
paul@44 1402
paul@44 1403
        """
paul@44 1404
        Define types for the 'accessor_location' not having associated usage.
paul@44 1405
        """
paul@44 1406
paul@44 1407
        have_access = self.provider_class_types.has_key(accessor_location)
paul@44 1408
paul@44 1409
        # With an access, attempt to narrow the existing selection of provider
paul@44 1410
        # types.
paul@44 1411
paul@44 1412
        if have_access:
paul@44 1413
            provider_class_types = self.provider_class_types[accessor_location]
paul@44 1414
            provider_instance_types = self.provider_instance_types[accessor_location]
paul@44 1415
            provider_module_types = self.provider_module_types[accessor_location]
paul@44 1416
paul@44 1417
            # Find details for any corresponding access.
paul@44 1418
paul@44 1419
            all_class_types = set()
paul@44 1420
            all_instance_types = set()
paul@44 1421
            all_module_types = set()
paul@44 1422
paul@44 1423
            for access_location in self.alias_index[accessor_location]:
paul@44 1424
                location, name, attrnames, access_number = access_location
paul@44 1425
paul@44 1426
                # Alias references an attribute access.
paul@44 1427
paul@44 1428
                if attrnames:
paul@44 1429
paul@44 1430
                    # Obtain attribute references for the access.
paul@44 1431
paul@44 1432
                    attrs = [attr for _attrtype, object_type, attr in self.referenced_attrs[access_location]]
paul@44 1433
paul@44 1434
                    # Separate the different attribute types.
paul@44 1435
paul@44 1436
                    (class_types, instance_types, module_types,
paul@57 1437
                        function_types, var_types) = separate_types(attrs)
paul@44 1438
paul@44 1439
                    # Where non-accessor types are found, do not attempt to refine
paul@44 1440
                    # the defined accessor types.
paul@44 1441
paul@44 1442
                    if function_types or var_types:
paul@44 1443
                        return
paul@44 1444
paul@44 1445
                    class_types = set(provider_class_types).intersection(class_types)
paul@44 1446
                    instance_types = set(provider_instance_types).intersection(instance_types)
paul@44 1447
                    module_types = set(provider_module_types).intersection(module_types)
paul@44 1448
paul@44 1449
                # Alias references a name, not an access.
paul@44 1450
paul@44 1451
                else:
paul@44 1452
                    # Attempt to refine the types using initialised names.
paul@44 1453
paul@44 1454
                    attr = self.get_initialised_name(access_location)
paul@44 1455
                    if attr:
paul@44 1456
                        (class_types, instance_types, module_types,
paul@57 1457
                            _function_types, _var_types) = separate_types([attr])
paul@44 1458
paul@44 1459
                    # Where no further information is found, do not attempt to
paul@44 1460
                    # refine the defined accessor types.
paul@44 1461
paul@44 1462
                    else:
paul@44 1463
                        return
paul@44 1464
paul@44 1465
                all_class_types.update(class_types)
paul@44 1466
                all_instance_types.update(instance_types)
paul@44 1467
                all_module_types.update(module_types)
paul@44 1468
paul@44 1469
            # Record refined type details for the alias as an accessor.
paul@44 1470
paul@44 1471
            self.init_definition_details(accessor_location)
paul@44 1472
            self.record_reference_types(accessor_location, all_class_types, all_instance_types, all_module_types, False)
paul@44 1473
paul@44 1474
        # Without an access, attempt to identify references for the alias.
paul@44 1475
paul@44 1476
        else:
paul@44 1477
            refs = set()
paul@44 1478
paul@44 1479
            for access_location in self.alias_index[accessor_location]:
paul@64 1480
paul@64 1481
                # Obtain any redefined constant access location.
paul@64 1482
paul@64 1483
                if self.const_accesses.has_key(access_location):
paul@64 1484
                    access_location = self.const_accesses[access_location]
paul@64 1485
paul@44 1486
                location, name, attrnames, access_number = access_location
paul@44 1487
paul@44 1488
                # Alias references an attribute access.
paul@44 1489
paul@44 1490
                if attrnames:
paul@44 1491
                    attrs = [attr for attrtype, object_type, attr in self.referenced_attrs[access_location]]
paul@44 1492
                    refs.update(attrs)
paul@44 1493
paul@44 1494
                # Alias references a name, not an access.
paul@44 1495
paul@44 1496
                else:
paul@44 1497
                    attr = self.get_initialised_name(access_location)
paul@44 1498
                    attrs = attr and [attr] or []
paul@44 1499
                    if not attrs and self.provider_class_types.has_key(access_location):
paul@44 1500
                        class_types = self.provider_class_types[access_location]
paul@44 1501
                        instance_types = self.provider_instance_types[access_location]
paul@44 1502
                        module_types = self.provider_module_types[access_location]
paul@57 1503
                        attrs = combine_types(class_types, instance_types, module_types)
paul@44 1504
                    if attrs:
paul@44 1505
                        refs.update(attrs)
paul@44 1506
paul@44 1507
            # Record reference details for the alias separately from accessors.
paul@44 1508
paul@44 1509
            self.referenced_objects[accessor_location] = refs
paul@44 1510
paul@44 1511
    def get_initialised_name(self, access_location):
paul@44 1512
paul@44 1513
        """
paul@44 1514
        Return references for any initialised names at 'access_location', or
paul@44 1515
        None if no such references exist.
paul@44 1516
        """
paul@44 1517
paul@44 1518
        location, name, attrnames, version = access_location
paul@44 1519
        path = self.get_name_path(location, name)
paul@44 1520
paul@44 1521
        # Use initialiser information, if available.
paul@44 1522
paul@44 1523
        refs = self.importer.all_initialised_names.get(path)
paul@44 1524
        if refs and refs.has_key(version):
paul@44 1525
            return refs[version]
paul@44 1526
        else:
paul@44 1527
            return None
paul@44 1528
paul@44 1529
    def get_name_path(self, path, name):
paul@44 1530
paul@44 1531
        "Return a suitable qualified name from the given 'path' and 'name'."
paul@44 1532
paul@44 1533
        if "." in name:
paul@44 1534
            return name
paul@44 1535
        else:
paul@44 1536
            return "%s.%s" % (path, name)
paul@44 1537
paul@44 1538
    def record_reference_types(self, location, class_types, instance_types,
paul@44 1539
        module_types, constrained, constrained_specific=False):
paul@44 1540
paul@44 1541
        """
paul@44 1542
        Associate attribute provider types with the given 'location', consisting
paul@44 1543
        of the given 'class_types', 'instance_types' and 'module_types'.
paul@44 1544
paul@44 1545
        If 'constrained' is indicated, the constrained nature of the accessor is
paul@44 1546
        recorded for the location.
paul@44 1547
paul@44 1548
        If 'constrained_specific' is indicated using a true value, instance types
paul@44 1549
        will not be added to class types to permit access via instances at the
paul@44 1550
        given location. This is only useful where a specific accessor is known
paul@44 1551
        to be a class.
paul@44 1552
paul@44 1553
        Note that the specified types only indicate the provider types for
paul@44 1554
        attributes, whereas the recorded accessor types indicate the possible
paul@44 1555
        types of the actual objects used to access attributes.
paul@44 1556
        """
paul@44 1557
paul@44 1558
        # Update the type details for the location.
paul@44 1559
paul@44 1560
        self.provider_class_types[location].update(class_types)
paul@44 1561
        self.provider_instance_types[location].update(instance_types)
paul@44 1562
        self.provider_module_types[location].update(module_types)
paul@44 1563
paul@44 1564
        # Class types support classes and instances as accessors.
paul@44 1565
        # Instance-only and module types support only their own kinds as
paul@44 1566
        # accessors.
paul@44 1567
paul@44 1568
        # However, the nature of accessors can be further determined.
paul@44 1569
        # Any self variable may only refer to an instance.
paul@44 1570
paul@44 1571
        path, name, version, attrnames = location
paul@44 1572
        if name != "self" or not self.in_method(path):
paul@44 1573
            self.accessor_class_types[location].update(class_types)
paul@44 1574
paul@44 1575
        if not constrained_specific:
paul@44 1576
            self.accessor_instance_types[location].update(class_types)
paul@44 1577
paul@44 1578
        self.accessor_instance_types[location].update(instance_types)
paul@44 1579
paul@44 1580
        if name != "self" or not self.in_method(path):
paul@44 1581
            self.accessor_module_types[location].update(module_types)
paul@44 1582
paul@44 1583
        if constrained:
paul@67 1584
            self.accessor_constrained.add(location)
paul@44 1585
paul@44 1586
    def identify_reference_attributes(self, location, attrname, class_types, instance_types, module_types, constrained):
paul@44 1587
paul@44 1588
        """
paul@44 1589
        Identify reference attributes, associating them with the given
paul@44 1590
        'location', identifying the given 'attrname', employing the given
paul@44 1591
        'class_types', 'instance_types' and 'module_types'.
paul@44 1592
paul@44 1593
        If 'constrained' is indicated, the constrained nature of the access is
paul@44 1594
        recorded for the location.
paul@44 1595
        """
paul@44 1596
paul@44 1597
        # Record the referenced objects.
paul@44 1598
paul@44 1599
        self.referenced_attrs[location] = \
paul@44 1600
            self._identify_reference_attribute(attrname, class_types, instance_types, module_types)
paul@44 1601
paul@44 1602
        if constrained:
paul@44 1603
            self.access_constrained.add(location)
paul@44 1604
paul@44 1605
    def _identify_reference_attribute(self, attrname, class_types, instance_types, module_types):
paul@44 1606
paul@44 1607
        """
paul@44 1608
        Identify the reference attribute with the given 'attrname', employing
paul@44 1609
        the given 'class_types', 'instance_types' and 'module_types'.
paul@44 1610
        """
paul@44 1611
paul@44 1612
        attrs = set()
paul@44 1613
paul@44 1614
        # The class types expose class attributes either directly or via
paul@44 1615
        # instances.
paul@44 1616
paul@44 1617
        for object_type in class_types:
paul@44 1618
            ref = self.importer.get_class_attribute(object_type, attrname)
paul@44 1619
            if ref:
paul@44 1620
                attrs.add(("<class>", object_type, ref))
paul@44 1621
paul@44 1622
            # Add any distinct instance attributes that would be provided
paul@44 1623
            # by instances also providing indirect class attribute access.
paul@44 1624
paul@44 1625
            for ref in self.importer.get_instance_attributes(object_type, attrname):
paul@44 1626
                attrs.add(("<instance>", object_type, ref))
paul@44 1627
paul@44 1628
        # The instance-only types expose instance attributes, but although
paul@44 1629
        # classes are excluded as potential accessors (since they do not provide
paul@44 1630
        # the instance attributes), the class types may still provide some
paul@44 1631
        # attributes.
paul@44 1632
paul@44 1633
        for object_type in instance_types:
paul@44 1634
            instance_attrs = self.importer.get_instance_attributes(object_type, attrname)
paul@44 1635
paul@44 1636
            if instance_attrs:
paul@44 1637
                for ref in instance_attrs:
paul@44 1638
                    attrs.add(("<instance>", object_type, ref))
paul@44 1639
            else:
paul@44 1640
                ref = self.importer.get_class_attribute(object_type, attrname)
paul@44 1641
                if ref:
paul@44 1642
                    attrs.add(("<class>", object_type, ref))
paul@44 1643
paul@44 1644
        # Module types expose module attributes for module accessors.
paul@44 1645
paul@44 1646
        for object_type in module_types:
paul@44 1647
            ref = self.importer.get_module_attribute(object_type, attrname)
paul@44 1648
            if ref:
paul@44 1649
                attrs.add(("<module>", object_type, ref))
paul@44 1650
paul@44 1651
        return attrs
paul@44 1652
paul@67 1653
    guarded_specific_tests = (
paul@67 1654
        "guarded-specific-instance",
paul@67 1655
        "guarded-specific-type",
paul@67 1656
        "guarded-specific-object",
paul@67 1657
        )
paul@67 1658
paul@67 1659
    guarded_common_tests = (
paul@67 1660
        "guarded-common-instance",
paul@67 1661
        "guarded-common-type",
paul@67 1662
        "guarded-common-object",
paul@67 1663
        )
paul@67 1664
paul@67 1665
    specific_tests = (
paul@67 1666
        "specific-instance",
paul@67 1667
        "specific-type",
paul@67 1668
        "specific-object",
paul@67 1669
        )
paul@67 1670
paul@67 1671
    common_tests = (
paul@67 1672
        "common-instance",
paul@67 1673
        "common-type",
paul@67 1674
        "common-object",
paul@67 1675
        )
paul@67 1676
paul@67 1677
    class_tests = (
paul@67 1678
        "guarded-specific-type",
paul@67 1679
        "guarded-common-type",
paul@67 1680
        "specific-type",
paul@67 1681
        "common-type",
paul@67 1682
        )
paul@67 1683
paul@67 1684
    class_or_instance_tests = (
paul@67 1685
        "guarded-specific-object",
paul@67 1686
        "guarded-common-object",
paul@67 1687
        "specific-object",
paul@67 1688
        "common-object",
paul@67 1689
        )
paul@67 1690
paul@67 1691
    def get_access_plan(self, location):
paul@65 1692
paul@65 1693
        "Return details of the access at the given 'location'."
paul@65 1694
paul@67 1695
        const_access = self.const_accesses_rev.has_key(location)
paul@65 1696
paul@65 1697
        path, name, attrname_str, version = location
paul@65 1698
        attrnames = attrname_str.split(".")
paul@65 1699
        attrname = attrnames[0]
paul@65 1700
paul@67 1701
        # Obtain reference and accessor information, retaining also distinct
paul@67 1702
        # provider kind details.
paul@65 1703
paul@65 1704
        attrs = []
paul@65 1705
        objtypes = []
paul@67 1706
        provider_kinds = set()
paul@67 1707
paul@65 1708
        for attrtype, objtype, attr in self.referenced_attrs[location]:
paul@65 1709
            attrs.append(attr)
paul@65 1710
            objtypes.append(objtype)
paul@67 1711
            provider_kinds.add(attrtype)
paul@67 1712
paul@67 1713
        # Obtain accessor type and kind information.
paul@67 1714
paul@67 1715
        accessor_types = self.reference_all_accessor_types[location]
paul@67 1716
        accessor_general_types = self.reference_all_accessor_general_types[location]
paul@67 1717
        accessor_kinds = get_kinds(accessor_general_types)
paul@67 1718
paul@67 1719
        # Determine any guard or test requirements.
paul@67 1720
paul@67 1721
        constrained = location in self.access_constrained
paul@67 1722
paul@67 1723
        if constrained:
paul@67 1724
            test = "constrained"
paul@67 1725
        else:
paul@67 1726
            test = self.reference_test_types[location]
paul@67 1727
paul@67 1728
        # Determine the accessor and provider properties.
paul@67 1729
paul@67 1730
        class_accessor = "<class>" in accessor_kinds
paul@67 1731
        module_accessor = "<module>" in accessor_kinds
paul@67 1732
        instance_accessor = "<instance>" in accessor_kinds
paul@67 1733
        provided_by_class = "<class>" in provider_kinds
paul@67 1734
        provided_by_instance = "<instance>" in provider_kinds
paul@67 1735
paul@67 1736
        # Identify the last static attribute for context acquisition.
paul@67 1737
paul@67 1738
        base = None
paul@67 1739
        dynamic_base = None
paul@67 1740
paul@67 1741
        # Constant accesses have static accessors.
paul@65 1742
paul@65 1743
        if const_access:
paul@65 1744
            base = len(objtypes) == 1 and first(objtypes)
paul@67 1745
paul@67 1746
        # Constant accessors are static.
paul@67 1747
paul@65 1748
        else:
paul@65 1749
            ref = self.importer.identify("%s.%s" % (path, name))
paul@67 1750
            if ref:
paul@65 1751
                base = ref.get_origin()
paul@65 1752
paul@67 1753
            # Identify single type accessors. These can be relied upon to
paul@67 1754
            # provide attributes in the same positions.
paul@67 1755
paul@67 1756
            elif constrained and len(accessor_types) == 1:
paul@67 1757
                ref = first(accessor_types)
paul@67 1758
paul@67 1759
            elif constrained and len(accessor_general_types) == 1:
paul@67 1760
                ref = first(accessor_general_types)
paul@67 1761
paul@67 1762
            # Multiple type accessors may involve a single type but where both
paul@67 1763
            # the type itself (a class) or an instance of the type might be used
paul@67 1764
            # to access a class attribute.
paul@67 1765
paul@67 1766
            # Usage of previously-generated guard and test details.
paul@67 1767
paul@67 1768
            elif test in self.guarded_specific_tests:
paul@67 1769
                ref = first(accessor_types)
paul@67 1770
paul@67 1771
            elif test in self.guarded_common_tests:
paul@67 1772
                ref = first(accessor_general_types)
paul@67 1773
paul@67 1774
            elif test in self.common_tests or test in self.specific_tests:
paul@67 1775
                accessor_test_types = self.reference_test_accessor_types[location]
paul@67 1776
                ref = first(accessor_test_types)
paul@67 1777
paul@67 1778
            # Static accessors.
paul@67 1779
paul@67 1780
            if ref and test in self.class_tests:
paul@67 1781
                base = ref.get_origin()
paul@67 1782
paul@67 1783
            # Constrained accessors that are not static but whose nature is
paul@67 1784
            # determined.
paul@67 1785
paul@67 1786
            if not base and ref and constrained:
paul@67 1787
                dynamic_base = ref.get_origin()
paul@67 1788
paul@65 1789
        traversed = []
paul@65 1790
paul@65 1791
        # Traverse remaining attributes.
paul@65 1792
paul@65 1793
        while len(attrs) == 1:
paul@65 1794
            attr = first(attrs)
paul@65 1795
paul@65 1796
            traversed.append(attrname)
paul@65 1797
            del attrnames[0]
paul@65 1798
paul@65 1799
            if not attrnames:
paul@65 1800
                break
paul@65 1801
paul@67 1802
            # Update the last static attribute.
paul@67 1803
paul@65 1804
            if attr.static():
paul@65 1805
                base = attr.get_origin()
paul@65 1806
                traversed = []
paul@65 1807
paul@67 1808
            # Get the next attribute.
paul@67 1809
paul@65 1810
            attrname = attrnames[0]
paul@65 1811
            attrs = self.importer.get_attributes(attr, attrname)
paul@67 1812
paul@67 1813
        # Where many attributes are suggested, no single attribute identity can
paul@67 1814
        # be loaded.
paul@67 1815
paul@65 1816
        else:
paul@65 1817
            attr = None
paul@65 1818
paul@67 1819
        # Determine the method of access.
paul@67 1820
paul@67 1821
        # Static, identified attribute.
paul@67 1822
paul@67 1823
        if attr and attr.static():
paul@67 1824
            method = "static"; origin = attr.final()
paul@67 1825
paul@67 1826
        # Identified attribute that must be accessed via its parent.
paul@67 1827
paul@67 1828
        elif attr and attr.get_name():
paul@67 1829
            method = "direct"; origin = attr.get_name()
paul@67 1830
paul@67 1831
        # Attribute accessed at a known position via its parent.
paul@67 1832
paul@67 1833
        elif base or dynamic_base:
paul@67 1834
            method = "relative"; origin = None
paul@67 1835
paul@67 1836
        # The fallback case is always run-time testing and access.
paul@67 1837
paul@67 1838
        else:
paul@67 1839
            l = []
paul@67 1840
            if class_accessor or module_accessor or provided_by_instance:
paul@67 1841
                l.append("checkobject")
paul@67 1842
            if instance_accessor and provided_by_class:
paul@67 1843
                l.append("checkclass")
paul@67 1844
            method = "+".join(l)
paul@67 1845
            origin = None
paul@67 1846
paul@67 1847
        return base or name, traversed, attrnames, method, test, origin
paul@65 1848
paul@44 1849
# vim: tabstop=4 expandtab shiftwidth=4