Lichen

Annotated common.py

225:dfbc750d3fce
2016-11-23 Paul Boddie Produce a proper error when too many arguments are given for an invocation.
paul@0 1
#!/usr/bin/env python
paul@0 2
paul@0 3
"""
paul@0 4
Common functions.
paul@0 5
paul@0 6
Copyright (C) 2007, 2008, 2009, 2010, 2011, 2012, 2013,
paul@0 7
              2014, 2015, 2016 Paul Boddie <paul@boddie.org.uk>
paul@0 8
paul@0 9
This program is free software; you can redistribute it and/or modify it under
paul@0 10
the terms of the GNU General Public License as published by the Free Software
paul@0 11
Foundation; either version 3 of the License, or (at your option) any later
paul@0 12
version.
paul@0 13
paul@0 14
This program is distributed in the hope that it will be useful, but WITHOUT
paul@0 15
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
paul@0 16
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
paul@0 17
details.
paul@0 18
paul@0 19
You should have received a copy of the GNU General Public License along with
paul@0 20
this program.  If not, see <http://www.gnu.org/licenses/>.
paul@0 21
"""
paul@0 22
paul@0 23
from errors import *
paul@0 24
from os import listdir, makedirs, remove
paul@0 25
from os.path import exists, isdir, join, split
paul@11 26
from results import ConstantValueRef, LiteralSequenceRef, NameRef
paul@0 27
import compiler
paul@0 28
paul@0 29
class CommonOutput:
paul@0 30
paul@0 31
    "Common output functionality."
paul@0 32
paul@0 33
    def check_output(self):
paul@0 34
paul@0 35
        "Check the existing output and remove it if irrelevant."
paul@0 36
paul@0 37
        if not exists(self.output):
paul@0 38
            makedirs(self.output)
paul@0 39
paul@0 40
        details = self.importer.get_cache_details()
paul@0 41
        recorded_details = self.get_output_details()
paul@0 42
paul@0 43
        if recorded_details != details:
paul@0 44
            self.remove_output()
paul@0 45
paul@0 46
        writefile(self.get_output_details_filename(), details)
paul@0 47
paul@0 48
    def get_output_details_filename(self):
paul@0 49
paul@0 50
        "Return the output details filename."
paul@0 51
paul@0 52
        return join(self.output, "$details")
paul@0 53
paul@0 54
    def get_output_details(self):
paul@0 55
paul@0 56
        "Return details of the existing output."
paul@0 57
paul@0 58
        details_filename = self.get_output_details_filename()
paul@0 59
paul@0 60
        if not exists(details_filename):
paul@0 61
            return None
paul@0 62
        else:
paul@0 63
            return readfile(details_filename)
paul@0 64
paul@0 65
    def remove_output(self, dirname=None):
paul@0 66
paul@0 67
        "Remove the output."
paul@0 68
paul@0 69
        dirname = dirname or self.output
paul@0 70
paul@0 71
        for filename in listdir(dirname):
paul@0 72
            path = join(dirname, filename)
paul@0 73
            if isdir(path):
paul@0 74
                self.remove_output(path)
paul@0 75
            else:
paul@0 76
                remove(path)
paul@0 77
paul@0 78
class CommonModule:
paul@0 79
paul@0 80
    "A common module representation."
paul@0 81
paul@0 82
    def __init__(self, name, importer):
paul@0 83
paul@0 84
        """
paul@0 85
        Initialise this module with the given 'name' and an 'importer' which is
paul@0 86
        used to provide access to other modules when required.
paul@0 87
        """
paul@0 88
paul@0 89
        self.name = name
paul@0 90
        self.importer = importer
paul@0 91
        self.filename = None
paul@0 92
paul@0 93
        # Inspection-related attributes.
paul@0 94
paul@0 95
        self.astnode = None
paul@0 96
        self.iterators = {}
paul@0 97
        self.temp = {}
paul@0 98
        self.lambdas = {}
paul@0 99
paul@0 100
        # Constants, literals and values.
paul@0 101
paul@0 102
        self.constants = {}
paul@0 103
        self.constant_values = {}
paul@0 104
        self.literals = {}
paul@0 105
        self.literal_types = {}
paul@0 106
paul@0 107
        # Nested namespaces.
paul@0 108
paul@0 109
        self.namespace_path = []
paul@0 110
        self.in_function = False
paul@0 111
paul@124 112
        # Retain the assignment value expression and track invocations.
paul@124 113
paul@124 114
        self.in_assignment = None
paul@124 115
        self.in_invocation = False
paul@124 116
paul@124 117
        # Attribute chain state management.
paul@0 118
paul@0 119
        self.attrs = []
paul@124 120
        self.chain_assignment = []
paul@124 121
        self.chain_invocation = []
paul@0 122
paul@0 123
    def __repr__(self):
paul@0 124
        return "CommonModule(%r, %r)" % (self.name, self.importer)
paul@0 125
paul@0 126
    def parse_file(self, filename):
paul@0 127
paul@0 128
        "Parse the file with the given 'filename', initialising attributes."
paul@0 129
paul@0 130
        self.filename = filename
paul@0 131
        self.astnode = compiler.parseFile(filename)
paul@0 132
paul@0 133
    # Module-relative naming.
paul@0 134
paul@0 135
    def get_global_path(self, name):
paul@0 136
        return "%s.%s" % (self.name, name)
paul@0 137
paul@0 138
    def get_namespace_path(self):
paul@0 139
        return ".".join([self.name] + self.namespace_path)
paul@0 140
paul@0 141
    def get_object_path(self, name):
paul@0 142
        return ".".join([self.name] + self.namespace_path + [name])
paul@0 143
paul@0 144
    def get_parent_path(self):
paul@0 145
        return ".".join([self.name] + self.namespace_path[:-1])
paul@0 146
paul@0 147
    # Namespace management.
paul@0 148
paul@0 149
    def enter_namespace(self, name):
paul@0 150
paul@0 151
        "Enter the namespace having the given 'name'."
paul@0 152
paul@0 153
        self.namespace_path.append(name)
paul@0 154
paul@0 155
    def exit_namespace(self):
paul@0 156
paul@0 157
        "Exit the current namespace."
paul@0 158
paul@0 159
        self.namespace_path.pop()
paul@0 160
paul@0 161
    # Constant reference naming.
paul@0 162
paul@0 163
    def get_constant_name(self, value):
paul@0 164
paul@0 165
        "Add a new constant to the current namespace for 'value'."
paul@0 166
paul@0 167
        path = self.get_namespace_path()
paul@0 168
        init_item(self.constants, path, dict)
paul@0 169
        return "$c%d" % add_counter_item(self.constants[path], value)
paul@0 170
paul@0 171
    # Literal reference naming.
paul@0 172
paul@0 173
    def get_literal_name(self):
paul@0 174
paul@0 175
        "Add a new literal to the current namespace."
paul@0 176
paul@0 177
        path = self.get_namespace_path()
paul@0 178
        init_item(self.literals, path, lambda: 0)
paul@0 179
        return "$C%d" % self.literals[path]
paul@0 180
paul@0 181
    def next_literal(self):
paul@0 182
        self.literals[self.get_namespace_path()] += 1
paul@0 183
paul@0 184
    # Temporary iterator naming.
paul@0 185
paul@0 186
    def get_iterator_path(self):
paul@0 187
        return self.in_function and self.get_namespace_path() or self.name
paul@0 188
paul@0 189
    def get_iterator_name(self):
paul@0 190
        path = self.get_iterator_path()
paul@0 191
        init_item(self.iterators, path, lambda: 0)
paul@0 192
        return "$i%d" % self.iterators[path]
paul@0 193
paul@0 194
    def next_iterator(self):
paul@0 195
        self.iterators[self.get_iterator_path()] += 1
paul@0 196
paul@0 197
    # Temporary variable naming.
paul@0 198
paul@0 199
    def get_temporary_name(self):
paul@0 200
        path = self.get_namespace_path()
paul@0 201
        init_item(self.temp, path, lambda: 0)
paul@0 202
        return "$t%d" % self.temp[path]
paul@0 203
paul@0 204
    def next_temporary(self):
paul@0 205
        self.temp[self.get_namespace_path()] += 1
paul@0 206
paul@0 207
    # Arbitrary function naming.
paul@0 208
paul@0 209
    def get_lambda_name(self):
paul@0 210
        path = self.get_namespace_path()
paul@0 211
        init_item(self.lambdas, path, lambda: 0)
paul@0 212
        name = "$l%d" % self.lambdas[path]
paul@0 213
        self.lambdas[path] += 1
paul@0 214
        return name
paul@0 215
paul@0 216
    def reset_lambdas(self):
paul@0 217
        self.lambdas = {}
paul@0 218
paul@0 219
    # Constant and literal recording.
paul@0 220
paul@0 221
    def get_constant_reference(self, ref, value):
paul@0 222
paul@0 223
        "Return a constant reference for the given 'ref' type and 'value'."
paul@0 224
paul@0 225
        constant_name = self.get_constant_name(value)
paul@0 226
paul@0 227
        # Return a reference for the constant.
paul@0 228
paul@0 229
        objpath = self.get_object_path(constant_name)
paul@0 230
        name_ref = ConstantValueRef(constant_name, ref.instance_of(), value)
paul@0 231
paul@0 232
        # Record the value and type for the constant.
paul@0 233
paul@0 234
        self.constant_values[objpath] = name_ref.value, name_ref.get_origin()
paul@0 235
        return name_ref
paul@0 236
paul@0 237
    def get_literal_reference(self, name, ref, items, cls):
paul@0 238
paul@11 239
        """
paul@11 240
        Return a literal reference for the given type 'name', literal 'ref',
paul@11 241
        node 'items' and employing the given 'cls' as the class of the returned
paul@11 242
        reference object.
paul@11 243
        """
paul@11 244
paul@0 245
        # Construct an invocation using the items as arguments.
paul@0 246
paul@0 247
        typename = "$L%s" % name
paul@0 248
paul@0 249
        invocation = compiler.ast.CallFunc(
paul@0 250
            compiler.ast.Name(typename),
paul@0 251
            items
paul@0 252
            )
paul@0 253
paul@0 254
        # Get a name for the actual literal.
paul@0 255
paul@0 256
        instname = self.get_literal_name()
paul@0 257
        self.next_literal()
paul@0 258
paul@0 259
        # Record the type for the literal.
paul@0 260
paul@0 261
        objpath = self.get_object_path(instname)
paul@0 262
        self.literal_types[objpath] = ref.get_origin()
paul@0 263
paul@0 264
        # Return a wrapper for the invocation exposing the items.
paul@0 265
paul@0 266
        return cls(
paul@0 267
            instname,
paul@0 268
            ref.instance_of(),
paul@0 269
            self.process_structure_node(invocation),
paul@0 270
            invocation.args
paul@0 271
            )
paul@0 272
paul@0 273
    # Node handling.
paul@0 274
paul@0 275
    def process_structure(self, node):
paul@0 276
paul@0 277
        """
paul@0 278
        Within the given 'node', process the program structure.
paul@0 279
paul@0 280
        During inspection, this will process global declarations, adjusting the
paul@0 281
        module namespace, and import statements, building a module dependency
paul@0 282
        hierarchy.
paul@0 283
paul@0 284
        During translation, this will consult deduced program information and
paul@0 285
        output translated code.
paul@0 286
        """
paul@0 287
paul@0 288
        l = []
paul@0 289
        for n in node.getChildNodes():
paul@0 290
            l.append(self.process_structure_node(n))
paul@0 291
        return l
paul@0 292
paul@0 293
    def process_augassign_node(self, n):
paul@0 294
paul@0 295
        "Process the given augmented assignment node 'n'."
paul@0 296
paul@0 297
        op = operator_functions[n.op]
paul@0 298
paul@0 299
        if isinstance(n.node, compiler.ast.Getattr):
paul@0 300
            target = compiler.ast.AssAttr(n.node.expr, n.node.attrname, "OP_ASSIGN")
paul@0 301
        elif isinstance(n.node, compiler.ast.Name):
paul@0 302
            target = compiler.ast.AssName(n.node.name, "OP_ASSIGN")
paul@0 303
        else:
paul@0 304
            target = n.node
paul@0 305
paul@0 306
        assignment = compiler.ast.Assign(
paul@0 307
            [target],
paul@0 308
            compiler.ast.CallFunc(
paul@0 309
                compiler.ast.Name("$op%s" % op),
paul@0 310
                [n.node, n.expr]))
paul@0 311
paul@0 312
        return self.process_structure_node(assignment)
paul@0 313
paul@196 314
    def process_assignment_for_function(self, original_name, source):
paul@0 315
paul@0 316
        """
paul@0 317
        Return an assignment operation making 'original_name' refer to the given
paul@196 318
        'source'.
paul@0 319
        """
paul@0 320
paul@0 321
        assignment = compiler.ast.Assign(
paul@0 322
            [compiler.ast.AssName(original_name, "OP_ASSIGN")],
paul@196 323
            source
paul@0 324
            )
paul@0 325
paul@0 326
        return self.process_structure_node(assignment)
paul@0 327
paul@0 328
    def process_assignment_node_items(self, n, expr):
paul@0 329
paul@0 330
        """
paul@0 331
        Process the given assignment node 'n' whose children are to be assigned
paul@0 332
        items of 'expr'.
paul@0 333
        """
paul@0 334
paul@0 335
        name_ref = self.process_structure_node(expr)
paul@0 336
paul@0 337
        # Either unpack the items and present them directly to each assignment
paul@0 338
        # node.
paul@0 339
paul@0 340
        if isinstance(name_ref, LiteralSequenceRef):
paul@0 341
            self.process_literal_sequence_items(n, name_ref)
paul@0 342
paul@0 343
        # Or have the assignment nodes access each item via the sequence API.
paul@0 344
paul@0 345
        else:
paul@0 346
            self.process_assignment_node_items_by_position(n, expr, name_ref)
paul@0 347
paul@0 348
    def process_assignment_node_items_by_position(self, n, expr, name_ref):
paul@0 349
paul@0 350
        """
paul@0 351
        Process the given sequence assignment node 'n', converting the node to
paul@0 352
        the separate assignment of each target using positional access on a
paul@0 353
        temporary variable representing the sequence. Use 'expr' as the assigned
paul@0 354
        value and 'name_ref' as the reference providing any existing temporary
paul@0 355
        variable.
paul@0 356
        """
paul@0 357
paul@0 358
        assignments = []
paul@0 359
paul@0 360
        if isinstance(name_ref, NameRef):
paul@0 361
            temp = name_ref.name
paul@0 362
        else:
paul@0 363
            temp = self.get_temporary_name()
paul@0 364
            self.next_temporary()
paul@0 365
paul@0 366
            assignments.append(
paul@0 367
                compiler.ast.Assign([compiler.ast.AssName(temp, "OP_ASSIGN")], expr)
paul@0 368
                )
paul@0 369
paul@0 370
        for i, node in enumerate(n.nodes):
paul@0 371
            assignments.append(
paul@0 372
                compiler.ast.Assign([node], compiler.ast.Subscript(
paul@0 373
                    compiler.ast.Name(temp), "OP_APPLY", [compiler.ast.Const(i)]))
paul@0 374
                )
paul@0 375
paul@0 376
        return self.process_structure_node(compiler.ast.Stmt(assignments))
paul@0 377
paul@0 378
    def process_literal_sequence_items(self, n, name_ref):
paul@0 379
paul@0 380
        """
paul@0 381
        Process the given assignment node 'n', obtaining from the given
paul@0 382
        'name_ref' the items to be assigned to the assignment targets.
paul@0 383
        """
paul@0 384
paul@0 385
        if len(n.nodes) == len(name_ref.items):
paul@0 386
            for node, item in zip(n.nodes, name_ref.items):
paul@0 387
                self.process_assignment_node(node, item)
paul@0 388
        else:
paul@0 389
            raise InspectError("In %s, item assignment needing %d items is given %d items." % (
paul@0 390
                self.get_namespace_path(), len(n.nodes), len(name_ref.items)))
paul@0 391
paul@0 392
    def process_compare_node(self, n):
paul@0 393
paul@0 394
        """
paul@0 395
        Process the given comparison node 'n', converting an operator sequence
paul@0 396
        from...
paul@0 397
paul@0 398
        <expr1> <op1> <expr2> <op2> <expr3>
paul@0 399
paul@0 400
        ...to...
paul@0 401
paul@0 402
        <op1>(<expr1>, <expr2>) and <op2>(<expr2>, <expr3>)
paul@0 403
        """
paul@0 404
paul@0 405
        invocations = []
paul@0 406
        last = n.expr
paul@0 407
paul@0 408
        for op, op_node in n.ops:
paul@0 409
            op = operator_functions.get(op)
paul@0 410
paul@0 411
            invocations.append(compiler.ast.CallFunc(
paul@0 412
                compiler.ast.Name("$op%s" % op),
paul@0 413
                [last, op_node]))
paul@0 414
paul@0 415
            last = op_node
paul@0 416
paul@0 417
        if len(invocations) > 1:
paul@0 418
            result = compiler.ast.And(invocations)
paul@0 419
        else:
paul@0 420
            result = invocations[0]
paul@0 421
paul@0 422
        return self.process_structure_node(result)
paul@0 423
paul@0 424
    def process_dict_node(self, node):
paul@0 425
paul@0 426
        """
paul@0 427
        Process the given dictionary 'node', returning a list of (key, value)
paul@0 428
        tuples.
paul@0 429
        """
paul@0 430
paul@0 431
        l = []
paul@0 432
        for key, value in node.items:
paul@0 433
            l.append((
paul@0 434
                self.process_structure_node(key),
paul@0 435
                self.process_structure_node(value)))
paul@0 436
        return l
paul@0 437
paul@0 438
    def process_for_node(self, n):
paul@0 439
paul@0 440
        """
paul@0 441
        Generate attribute accesses for {n.list}.__iter__ and the next method on
paul@0 442
        the iterator, producing a replacement node for the original.
paul@0 443
        """
paul@0 444
paul@0 445
        node = compiler.ast.Stmt([
paul@0 446
paul@0 447
            # <iterator> = {n.list}.__iter__
paul@0 448
paul@0 449
            compiler.ast.Assign(
paul@0 450
                [compiler.ast.AssName(self.get_iterator_name(), "OP_ASSIGN")],
paul@0 451
                compiler.ast.CallFunc(
paul@0 452
                    compiler.ast.Getattr(n.list, "__iter__"),
paul@0 453
                    []
paul@0 454
                    )),
paul@0 455
paul@0 456
            # try:
paul@0 457
            #     while True:
paul@0 458
            #         <var>... = <iterator>.next()
paul@0 459
            #         ...
paul@0 460
            # except StopIteration:
paul@0 461
            #     pass
paul@0 462
paul@0 463
            compiler.ast.TryExcept(
paul@0 464
                compiler.ast.While(
paul@0 465
                    compiler.ast.Name("True"),
paul@0 466
                    compiler.ast.Stmt([
paul@0 467
                        compiler.ast.Assign(
paul@0 468
                            [n.assign],
paul@0 469
                            compiler.ast.CallFunc(
paul@0 470
                                compiler.ast.Getattr(compiler.ast.Name(self.get_iterator_name()), "next"),
paul@0 471
                                []
paul@0 472
                                )),
paul@0 473
                        n.body]),
paul@0 474
                    None),
paul@0 475
                [(compiler.ast.Name("StopIteration"), None, compiler.ast.Stmt([compiler.ast.Pass()]))],
paul@0 476
                None)
paul@0 477
            ])
paul@0 478
paul@0 479
        self.next_iterator()
paul@0 480
        self.process_structure_node(node)
paul@0 481
paul@0 482
    def process_literal_sequence_node(self, n, name, ref, cls):
paul@0 483
paul@0 484
        """
paul@0 485
        Process the given literal sequence node 'n' as a function invocation,
paul@0 486
        with 'name' indicating the type of the sequence, and 'ref' being a
paul@0 487
        reference to the type. The 'cls' is used to instantiate a suitable name
paul@0 488
        reference.
paul@0 489
        """
paul@0 490
paul@0 491
        if name == "dict":
paul@0 492
            items = []
paul@0 493
            for key, value in n.items:
paul@0 494
                items.append(compiler.ast.Tuple([key, value]))
paul@0 495
        else: # name in ("list", "tuple"):
paul@0 496
            items = n.nodes
paul@0 497
paul@0 498
        return self.get_literal_reference(name, ref, items, cls)
paul@0 499
paul@0 500
    def process_operator_node(self, n):
paul@0 501
paul@0 502
        """
paul@0 503
        Process the given operator node 'n' as an operator function invocation.
paul@0 504
        """
paul@0 505
paul@0 506
        op = operator_functions[n.__class__.__name__]
paul@0 507
        invocation = compiler.ast.CallFunc(
paul@0 508
            compiler.ast.Name("$op%s" % op),
paul@0 509
            list(n.getChildNodes())
paul@0 510
            )
paul@0 511
        return self.process_structure_node(invocation)
paul@0 512
paul@173 513
    def process_print_node(self, n):
paul@173 514
paul@173 515
        """
paul@173 516
        Process the given print node 'n' as an invocation on a stream of the
paul@173 517
        form...
paul@173 518
paul@173 519
        $print(dest, args, nl)
paul@173 520
paul@173 521
        The special function name will be translated elsewhere.
paul@173 522
        """
paul@173 523
paul@173 524
        nl = isinstance(n, compiler.ast.Printnl)
paul@173 525
        invocation = compiler.ast.CallFunc(
paul@173 526
            compiler.ast.Name("$print"),
paul@173 527
            [n.dest or compiler.ast.Name("None"),
paul@173 528
             compiler.ast.List(list(n.nodes)),
paul@173 529
             nl and compiler.ast.Name("True") or compiler.ast.Name("false")]
paul@173 530
            )
paul@173 531
        return self.process_structure_node(invocation)
paul@173 532
paul@0 533
    def process_slice_node(self, n, expr=None):
paul@0 534
paul@0 535
        """
paul@0 536
        Process the given slice node 'n' as an operator function invocation.
paul@0 537
        """
paul@0 538
paul@0 539
        op = n.flags == "OP_ASSIGN" and "setslice" or "getslice"
paul@0 540
        invocation = compiler.ast.CallFunc(
paul@0 541
            compiler.ast.Name("$op%s" % op),
paul@0 542
            [n.expr, n.lower or compiler.ast.Name("None"), n.upper or compiler.ast.Name("None")] +
paul@0 543
                (expr and [expr] or [])
paul@0 544
            )
paul@0 545
        return self.process_structure_node(invocation)
paul@0 546
paul@0 547
    def process_sliceobj_node(self, n):
paul@0 548
paul@0 549
        """
paul@0 550
        Process the given slice object node 'n' as a slice constructor.
paul@0 551
        """
paul@0 552
paul@0 553
        op = "slice"
paul@0 554
        invocation = compiler.ast.CallFunc(
paul@0 555
            compiler.ast.Name("$op%s" % op),
paul@0 556
            n.nodes
paul@0 557
            )
paul@0 558
        return self.process_structure_node(invocation)
paul@0 559
paul@0 560
    def process_subscript_node(self, n, expr=None):
paul@0 561
paul@0 562
        """
paul@0 563
        Process the given subscript node 'n' as an operator function invocation.
paul@0 564
        """
paul@0 565
paul@0 566
        op = n.flags == "OP_ASSIGN" and "setitem" or "getitem"
paul@0 567
        invocation = compiler.ast.CallFunc(
paul@0 568
            compiler.ast.Name("$op%s" % op),
paul@0 569
            [n.expr] + list(n.subs) + (expr and [expr] or [])
paul@0 570
            )
paul@0 571
        return self.process_structure_node(invocation)
paul@0 572
paul@0 573
    def process_attribute_chain(self, n):
paul@0 574
paul@0 575
        """
paul@0 576
        Process the given attribute access node 'n'. Return a reference
paul@0 577
        describing the expression.
paul@0 578
        """
paul@0 579
paul@0 580
        # AssAttr/Getattr are nested with the outermost access being the last
paul@0 581
        # access in any chain.
paul@0 582
paul@0 583
        self.attrs.insert(0, n.attrname)
paul@0 584
        attrs = self.attrs
paul@0 585
paul@0 586
        # Break attribute chains where non-access nodes are found.
paul@0 587
paul@0 588
        if not self.have_access_expression(n):
paul@110 589
            self.reset_attribute_chain()
paul@0 590
paul@0 591
        # Descend into the expression, extending backwards any existing chain,
paul@0 592
        # or building another for the expression.
paul@0 593
paul@0 594
        name_ref = self.process_structure_node(n.expr)
paul@0 595
paul@0 596
        # Restore chain information applying to this node.
paul@0 597
paul@110 598
        if not self.have_access_expression(n):
paul@110 599
            self.restore_attribute_chain(attrs)
paul@0 600
paul@0 601
        # Return immediately if the expression was another access and thus a
paul@0 602
        # continuation backwards along the chain. The above processing will
paul@0 603
        # have followed the chain all the way to its conclusion.
paul@0 604
paul@0 605
        if self.have_access_expression(n):
paul@0 606
            del self.attrs[0]
paul@0 607
paul@0 608
        return name_ref
paul@0 609
paul@124 610
    # Attribute chain handling.
paul@124 611
paul@110 612
    def reset_attribute_chain(self):
paul@110 613
paul@110 614
        "Reset the attribute chain for a subexpression of an attribute access."
paul@110 615
paul@110 616
        self.attrs = []
paul@124 617
        self.chain_assignment.append(self.in_assignment)
paul@124 618
        self.chain_invocation.append(self.in_invocation)
paul@124 619
        self.in_assignment = None
paul@124 620
        self.in_invocation = False
paul@110 621
paul@110 622
    def restore_attribute_chain(self, attrs):
paul@110 623
paul@110 624
        "Restore the attribute chain for an attribute access."
paul@110 625
paul@110 626
        self.attrs = attrs
paul@124 627
        self.in_assignment = self.chain_assignment.pop()
paul@124 628
        self.in_invocation = self.chain_invocation.pop()
paul@110 629
paul@0 630
    def have_access_expression(self, node):
paul@0 631
paul@0 632
        "Return whether the expression associated with 'node' is Getattr."
paul@0 633
paul@0 634
        return isinstance(node.expr, compiler.ast.Getattr)
paul@0 635
paul@0 636
    def get_name_for_tracking(self, name, path=None):
paul@0 637
paul@0 638
        """
paul@0 639
        Return the name to be used for attribute usage observations involving
paul@0 640
        the given 'name' in the current namespace. If 'path' is indicated and
paul@0 641
        the name is being used outside a function, return the path value;
paul@0 642
        otherwise, return a path computed using the current namespace and the
paul@0 643
        given name.
paul@0 644
paul@0 645
        The intention of this method is to provide a suitably-qualified name
paul@0 646
        that can be tracked across namespaces. Where globals are being
paul@0 647
        referenced in class namespaces, they should be referenced using their
paul@0 648
        path within the module, not using a path within each class.
paul@0 649
paul@0 650
        It may not be possible to identify a global within a function at the
paul@0 651
        time of inspection (since a global may appear later in a file).
paul@0 652
        Consequently, globals are identified by their local name rather than
paul@0 653
        their module-qualified path.
paul@0 654
        """
paul@0 655
paul@0 656
        # For functions, use the appropriate local names.
paul@0 657
paul@0 658
        if self.in_function:
paul@0 659
            return name
paul@0 660
paul@0 661
        # For static namespaces, use the given qualified name.
paul@0 662
paul@0 663
        elif path:
paul@0 664
            return path
paul@0 665
paul@152 666
        # Otherwise, establish a name in the current namespace.
paul@0 667
paul@0 668
        else:
paul@0 669
            return self.get_object_path(name)
paul@0 670
paul@0 671
    def get_path_for_access(self):
paul@0 672
paul@0 673
        "Outside functions, register accesses at the module level."
paul@0 674
paul@0 675
        if not self.in_function:
paul@0 676
            return self.name
paul@0 677
        else:
paul@0 678
            return self.get_namespace_path()
paul@0 679
paul@0 680
    def get_module_name(self, node):
paul@0 681
paul@0 682
        """
paul@0 683
        Using the given From 'node' in this module, calculate any relative import
paul@0 684
        information, returning a tuple containing a module to import along with any
paul@0 685
        names to import based on the node's name information.
paul@0 686
paul@0 687
        Where the returned module is given as None, whole module imports should
paul@0 688
        be performed for the returned modules using the returned names.
paul@0 689
        """
paul@0 690
paul@0 691
        # Absolute import.
paul@0 692
paul@0 693
        if node.level == 0:
paul@0 694
            return node.modname, node.names
paul@0 695
paul@0 696
        # Relative to an ancestor of this module.
paul@0 697
paul@0 698
        else:
paul@0 699
            path = self.name.split(".")
paul@0 700
            level = node.level
paul@0 701
paul@0 702
            # Relative imports treat package roots as submodules.
paul@0 703
paul@0 704
            if split(self.filename)[-1] == "__init__.py":
paul@0 705
                level -= 1
paul@0 706
paul@0 707
            if level > len(path):
paul@0 708
                raise InspectError("Relative import %r involves too many levels up from module %r" % (
paul@0 709
                    ("%s%s" % ("." * node.level, node.modname or "")), self.name))
paul@0 710
paul@0 711
            basename = ".".join(path[:len(path)-level])
paul@0 712
paul@0 713
        # Name imports from a module.
paul@0 714
paul@0 715
        if node.modname:
paul@0 716
            return "%s.%s" % (basename, node.modname), node.names
paul@0 717
paul@0 718
        # Relative whole module imports.
paul@0 719
paul@0 720
        else:
paul@0 721
            return basename, node.names
paul@0 722
paul@0 723
def get_argnames(args):
paul@0 724
paul@0 725
    """
paul@0 726
    Return a list of all names provided by 'args'. Since tuples may be
paul@0 727
    employed, the arguments are traversed depth-first.
paul@0 728
    """
paul@0 729
paul@0 730
    l = []
paul@0 731
    for arg in args:
paul@0 732
        if isinstance(arg, tuple):
paul@0 733
            l += get_argnames(arg)
paul@0 734
        else:
paul@0 735
            l.append(arg)
paul@0 736
    return l
paul@0 737
paul@0 738
# Dictionary utilities.
paul@0 739
paul@0 740
def init_item(d, key, fn):
paul@0 741
paul@0 742
    """
paul@0 743
    Add to 'd' an entry for 'key' using the callable 'fn' to make an initial
paul@0 744
    value where no entry already exists.
paul@0 745
    """
paul@0 746
paul@0 747
    if not d.has_key(key):
paul@0 748
        d[key] = fn()
paul@0 749
    return d[key]
paul@0 750
paul@0 751
def dict_for_keys(d, keys):
paul@0 752
paul@0 753
    "Return a new dictionary containing entries from 'd' for the given 'keys'."
paul@0 754
paul@0 755
    nd = {}
paul@0 756
    for key in keys:
paul@0 757
        if d.has_key(key):
paul@0 758
            nd[key] = d[key]
paul@0 759
    return nd
paul@0 760
paul@0 761
def make_key(s):
paul@0 762
paul@0 763
    "Make sequence 's' into a tuple-based key, first sorting its contents."
paul@0 764
paul@0 765
    l = list(s)
paul@0 766
    l.sort()
paul@0 767
    return tuple(l)
paul@0 768
paul@0 769
def add_counter_item(d, key):
paul@0 770
paul@0 771
    """
paul@0 772
    Make a mapping in 'd' for 'key' to the number of keys added before it, thus
paul@0 773
    maintaining a mapping of keys to their order of insertion.
paul@0 774
    """
paul@0 775
paul@0 776
    if not d.has_key(key):
paul@0 777
        d[key] = len(d.keys())
paul@0 778
    return d[key] 
paul@0 779
paul@0 780
def remove_items(d1, d2):
paul@0 781
paul@0 782
    "Remove from 'd1' all items from 'd2'."
paul@0 783
paul@0 784
    for key in d2.keys():
paul@0 785
        if d1.has_key(key):
paul@0 786
            del d1[key]
paul@0 787
paul@0 788
# Set utilities.
paul@0 789
paul@0 790
def first(s):
paul@0 791
    return list(s)[0]
paul@0 792
paul@0 793
def same(s1, s2):
paul@0 794
    return set(s1) == set(s2)
paul@0 795
paul@0 796
# General input/output.
paul@0 797
paul@0 798
def readfile(filename):
paul@0 799
paul@0 800
    "Return the contents of 'filename'."
paul@0 801
paul@0 802
    f = open(filename)
paul@0 803
    try:
paul@0 804
        return f.read()
paul@0 805
    finally:
paul@0 806
        f.close()
paul@0 807
paul@0 808
def writefile(filename, s):
paul@0 809
paul@0 810
    "Write to 'filename' the string 's'."
paul@0 811
paul@0 812
    f = open(filename, "w")
paul@0 813
    try:
paul@0 814
        f.write(s)
paul@0 815
    finally:
paul@0 816
        f.close()
paul@0 817
paul@0 818
# General encoding.
paul@0 819
paul@0 820
def sorted_output(x):
paul@0 821
paul@0 822
    "Sort sequence 'x' and return a string with commas separating the values."
paul@0 823
paul@0 824
    x = map(str, x)
paul@0 825
    x.sort()
paul@0 826
    return ", ".join(x)
paul@0 827
paul@0 828
# Attribute chain decoding.
paul@0 829
paul@0 830
def get_attrnames(attrnames):
paul@11 831
paul@11 832
    """
paul@11 833
    Split the qualified attribute chain 'attrnames' into its components,
paul@11 834
    handling special attributes starting with "#" that indicate type
paul@11 835
    conformance.
paul@11 836
    """
paul@11 837
paul@0 838
    if attrnames.startswith("#"):
paul@0 839
        return [attrnames]
paul@0 840
    else:
paul@0 841
        return attrnames.split(".")
paul@0 842
paul@0 843
def get_attrname_from_location(location):
paul@11 844
paul@11 845
    """
paul@11 846
    Extract the first attribute from the attribute names employed in a
paul@11 847
    'location'.
paul@11 848
    """
paul@11 849
paul@0 850
    path, name, attrnames, access = location
paul@91 851
    if not attrnames:
paul@91 852
        return attrnames
paul@0 853
    return get_attrnames(attrnames)[0]
paul@0 854
paul@85 855
def get_name_path(path, name):
paul@85 856
paul@85 857
    "Return a suitable qualified name from the given 'path' and 'name'."
paul@85 858
paul@85 859
    if "." in name:
paul@85 860
        return name
paul@85 861
    else:
paul@85 862
        return "%s.%s" % (path, name)
paul@85 863
paul@90 864
# Usage-related functions.
paul@89 865
paul@89 866
def get_types_for_usage(attrnames, objects):
paul@89 867
paul@89 868
    """
paul@89 869
    Identify the types that can support the given 'attrnames', using the
paul@89 870
    given 'objects' as the catalogue of type details.
paul@89 871
    """
paul@89 872
paul@89 873
    types = []
paul@89 874
    for name, _attrnames in objects.items():
paul@89 875
        if set(attrnames).issubset(_attrnames):
paul@89 876
            types.append(name)
paul@89 877
    return types
paul@89 878
paul@90 879
def get_invoked_attributes(usage):
paul@90 880
paul@90 881
    "Obtain invoked attribute from the given 'usage'."
paul@90 882
paul@90 883
    invoked = []
paul@90 884
    if usage:
paul@107 885
        for attrname, invocation, assignment in usage:
paul@90 886
            if invocation:
paul@90 887
                invoked.append(attrname)
paul@90 888
    return invoked
paul@90 889
paul@107 890
def get_assigned_attributes(usage):
paul@107 891
paul@107 892
    "Obtain assigned attribute from the given 'usage'."
paul@107 893
paul@107 894
    assigned = []
paul@107 895
    if usage:
paul@107 896
        for attrname, invocation, assignment in usage:
paul@107 897
            if assignment:
paul@107 898
                assigned.append(attrname)
paul@107 899
    return assigned
paul@107 900
paul@0 901
# Useful data.
paul@0 902
paul@11 903
predefined_constants = "False", "None", "NotImplemented", "True"
paul@0 904
paul@0 905
operator_functions = {
paul@0 906
paul@0 907
    # Fundamental operations.
paul@0 908
paul@0 909
    "is" : "is_",
paul@0 910
    "is not" : "is_not",
paul@0 911
paul@0 912
    # Binary operations.
paul@0 913
paul@0 914
    "in" : "in_",
paul@0 915
    "not in" : "not_in",
paul@0 916
    "Add" : "add",
paul@0 917
    "Bitand" : "and_",
paul@0 918
    "Bitor" : "or_",
paul@0 919
    "Bitxor" : "xor",
paul@0 920
    "Div" : "div",
paul@0 921
    "FloorDiv" : "floordiv",
paul@0 922
    "LeftShift" : "lshift",
paul@0 923
    "Mod" : "mod",
paul@0 924
    "Mul" : "mul",
paul@0 925
    "Power" : "pow",
paul@0 926
    "RightShift" : "rshift",
paul@0 927
    "Sub" : "sub",
paul@0 928
paul@0 929
    # Unary operations.
paul@0 930
paul@0 931
    "Invert" : "invert",
paul@0 932
    "UnaryAdd" : "pos",
paul@0 933
    "UnarySub" : "neg",
paul@0 934
paul@0 935
    # Augmented assignment.
paul@0 936
paul@0 937
    "+=" : "iadd",
paul@0 938
    "-=" : "isub",
paul@0 939
    "*=" : "imul",
paul@0 940
    "/=" : "idiv",
paul@0 941
    "//=" : "ifloordiv",
paul@0 942
    "%=" : "imod",
paul@0 943
    "**=" : "ipow",
paul@0 944
    "<<=" : "ilshift",
paul@0 945
    ">>=" : "irshift",
paul@0 946
    "&=" : "iand",
paul@0 947
    "^=" : "ixor",
paul@0 948
    "|=" : "ior",
paul@0 949
paul@0 950
    # Comparisons.
paul@0 951
paul@0 952
    "==" : "eq",
paul@0 953
    "!=" : "ne",
paul@0 954
    "<" : "lt",
paul@0 955
    "<=" : "le",
paul@0 956
    ">=" : "ge",
paul@0 957
    ">" : "gt",
paul@0 958
    }
paul@0 959
paul@0 960
# vim: tabstop=4 expandtab shiftwidth=4