Lichen

Annotated common.py

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