vContent

Annotated vContent.py

66:b28a84c6c886
2015-09-28 Paul Boddie Added more informative serialisation errors.
paul@0 1
#!/usr/bin/env python
paul@0 2
paul@0 3
"""
paul@0 4
Parsing of vCard, vCalendar and iCalendar files.
paul@0 5
paul@39 6
Copyright (C) 2005, 2006, 2007, 2008, 2009, 2011, 2013,
paul@57 7
              2014, 2015 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@14 10
the terms of the GNU General Public License as published by the Free Software
paul@14 11
Foundation; either version 3 of the License, or (at your option) any later
paul@14 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@14 16
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
paul@0 17
details.
paul@0 18
paul@14 19
You should have received a copy of the GNU General Public License along with
paul@14 20
this program.  If not, see <http://www.gnu.org/licenses/>.
paul@0 21
paul@0 22
--------
paul@0 23
paul@0 24
References:
paul@0 25
paul@16 26
RFC 5545: Internet Calendaring and Scheduling Core Object Specification
paul@16 27
          (iCalendar)
paul@18 28
          http://tools.ietf.org/html/rfc5545
paul@16 29
paul@0 30
RFC 2445: Internet Calendaring and Scheduling Core Object Specification
paul@0 31
          (iCalendar)
paul@18 32
          http://tools.ietf.org/html/rfc2445
paul@0 33
paul@0 34
RFC 2425: A MIME Content-Type for Directory Information
paul@18 35
          http://tools.ietf.org/html/rfc2425
paul@0 36
paul@0 37
RFC 2426: vCard MIME Directory Profile
paul@18 38
          http://tools.ietf.org/html/rfc2426
paul@0 39
"""
paul@0 40
paul@4 41
try:
paul@4 42
    set
paul@4 43
except NameError:
paul@4 44
    from sets import Set as set
paul@4 45
paul@0 46
# Encoding-related imports.
paul@0 47
paul@0 48
import base64, quopri
paul@9 49
import codecs
paul@0 50
paul@4 51
# Tokenisation help.
paul@4 52
paul@4 53
import re
paul@4 54
paul@9 55
# Configuration.
paul@9 56
paul@9 57
default_encoding = "utf-8"
paul@9 58
paul@39 59
class ParseError(Exception):
paul@39 60
paul@39 61
    "General parsing errors."
paul@39 62
paul@39 63
    pass
paul@39 64
paul@66 65
class WriteError(Exception):
paul@66 66
paul@66 67
    "General writing errors."
paul@66 68
paul@66 69
    pass
paul@66 70
paul@7 71
# Reader and parser classes.
paul@0 72
paul@0 73
class Reader:
paul@0 74
paul@0 75
    "A simple class wrapping a file, providing simple pushback capabilities."
paul@0 76
paul@0 77
    def __init__(self, f, non_standard_newline=0):
paul@0 78
paul@0 79
        """
paul@0 80
        Initialise the object with the file 'f'. If 'non_standard_newline' is
paul@0 81
        set to a true value (unlike the default), lines ending with CR will be
paul@0 82
        treated as complete lines.
paul@0 83
        """
paul@0 84
paul@0 85
        self.f = f
paul@0 86
        self.non_standard_newline = non_standard_newline
paul@0 87
        self.lines = []
paul@8 88
        self.line_number = 1 # about to read line 1
paul@0 89
paul@9 90
    def close(self):
paul@9 91
paul@9 92
        "Close the reader."
paul@9 93
paul@9 94
        self.f.close()
paul@9 95
paul@0 96
    def pushback(self, line):
paul@0 97
paul@0 98
        """
paul@0 99
        Push the given 'line' back so that the next line read is actually the
paul@0 100
        given 'line' and not the next line from the underlying file.
paul@0 101
        """
paul@0 102
paul@0 103
        self.lines.append(line)
paul@0 104
        self.line_number -= 1
paul@0 105
paul@0 106
    def readline(self):
paul@0 107
paul@0 108
        """
paul@0 109
        If no pushed-back lines exist, read a line directly from the file.
paul@0 110
        Otherwise, read from the list of pushed-back lines.
paul@0 111
        """
paul@0 112
paul@0 113
        self.line_number += 1
paul@0 114
        if self.lines:
paul@0 115
            return self.lines.pop()
paul@0 116
        else:
paul@11 117
            # Sanity check for broken lines (\r instead of \r\n or \n).
paul@0 118
            line = self.f.readline()
paul@0 119
            while line.endswith("\r") and not self.non_standard_newline:
paul@31 120
                s = self.f.readline()
paul@31 121
                if not s:
paul@31 122
                    break
paul@31 123
                line += s
paul@0 124
            if line.endswith("\r") and self.non_standard_newline:
paul@0 125
                return line + "\n"
paul@0 126
            else:
paul@0 127
                return line
paul@0 128
paul@8 129
    def read_content_line(self):
paul@0 130
paul@0 131
        """
paul@8 132
        Read an entire content line, itself potentially consisting of many
paul@11 133
        physical lines of text, returning a string.
paul@0 134
        """
paul@0 135
paul@9 136
        # Skip blank lines.
paul@9 137
paul@8 138
        line = self.readline()
paul@9 139
        while line:
paul@9 140
            line_stripped = line.rstrip("\r\n")
paul@9 141
            if not line_stripped:
paul@9 142
                line = self.readline()
paul@9 143
            else:
paul@9 144
                break
paul@9 145
        else:
paul@9 146
            return ""
paul@0 147
paul@8 148
        # Strip all appropriate whitespace from the right end of each line.
paul@8 149
        # For subsequent lines, remove the first whitespace character.
paul@8 150
        # See section 4.1 of the iCalendar specification.
paul@8 151
paul@9 152
        lines = [line_stripped]
paul@0 153
paul@0 154
        line = self.readline()
paul@8 155
        while line.startswith(" ") or line.startswith("\t"):
paul@8 156
            lines.append(line[1:].rstrip("\r\n"))
paul@8 157
            line = self.readline()
paul@8 158
paul@8 159
        # Since one line too many will have been read, push the line back into
paul@8 160
        # the file.
paul@8 161
paul@8 162
        if line:
paul@8 163
            self.pushback(line)
paul@8 164
paul@8 165
        return "".join(lines)
paul@8 166
paul@8 167
    def get_content_line(self):
paul@8 168
paul@8 169
        "Return a content line object for the current line."
paul@8 170
paul@8 171
        return ContentLine(self.read_content_line())
paul@8 172
paul@8 173
class ContentLine:
paul@8 174
paul@8 175
    "A content line which can be searched."
paul@8 176
paul@8 177
    SEPARATORS = re.compile('[;:"]')
paul@8 178
    SEPARATORS_PLUS_EQUALS = re.compile('[=;:"]')
paul@8 179
paul@8 180
    def __init__(self, text):
paul@8 181
        self.text = text
paul@8 182
        self.start = 0
paul@8 183
paul@30 184
    def __repr__(self):
paul@30 185
        return "ContentLine(%r)" % self.text
paul@30 186
paul@8 187
    def get_remaining(self):
paul@8 188
paul@8 189
        "Get the remaining text from the content line."
paul@8 190
paul@8 191
        return self.text[self.start:]
paul@8 192
paul@8 193
    def search(self, targets):
paul@8 194
paul@8 195
        """
paul@8 196
        Find one of the 'targets' in the text, returning the string from the
paul@8 197
        current position up to the target found, along with the target string,
paul@8 198
        using a tuple of the form (string, target). If no target was found,
paul@8 199
        return the entire string together with a target of None.
paul@11 200
paul@11 201
        The 'targets' parameter must be a regular expression object or an object
paul@11 202
        compatible with the API of such objects.
paul@8 203
        """
paul@8 204
paul@8 205
        text = self.text
paul@8 206
        start = pos = self.start
paul@8 207
        length = len(text)
paul@0 208
paul@4 209
        # Remember the first target.
paul@4 210
paul@4 211
        first = None
paul@4 212
        first_pos = None
paul@4 213
        in_quoted_region = 0
paul@0 214
paul@8 215
        # Process the text, looking for the targets.
paul@4 216
paul@8 217
        while pos < length:
paul@8 218
            match = targets.search(text, pos)
paul@4 219
paul@8 220
            # Where nothing matches, end the search.
paul@0 221
paul@4 222
            if match is None:
paul@8 223
                pos = length
paul@0 224
paul@4 225
            # Where a double quote matches, toggle the region state.
paul@0 226
paul@4 227
            elif match.group() == '"':
paul@4 228
                in_quoted_region = not in_quoted_region
paul@8 229
                pos = match.end()
paul@4 230
paul@4 231
            # Where something else matches outside a region, stop searching.
paul@0 232
paul@4 233
            elif not in_quoted_region:
paul@4 234
                first = match.group()
paul@4 235
                first_pos = match.start()
paul@4 236
                break
paul@0 237
paul@4 238
            # Otherwise, keep looking for the end of the region.
paul@4 239
paul@4 240
            else:
paul@8 241
                pos = match.end()
paul@4 242
paul@4 243
        # Where no more input can provide the targets, return a special result.
paul@0 244
paul@4 245
        else:
paul@8 246
            self.start = length
paul@8 247
            return text[start:], None
paul@0 248
paul@8 249
        self.start = match.end()
paul@8 250
        return text[start:first_pos], first
paul@0 251
paul@0 252
class StreamParser:
paul@0 253
paul@0 254
    "A stream parser for content in vCard/vCalendar/iCalendar-like formats."
paul@0 255
paul@0 256
    def __init__(self, f):
paul@0 257
paul@0 258
        "Initialise the parser for the given file 'f'."
paul@0 259
paul@0 260
        self.f = f
paul@0 261
paul@9 262
    def close(self):
paul@9 263
paul@9 264
        "Close the reader."
paul@9 265
paul@9 266
        self.f.close()
paul@9 267
paul@0 268
    def __iter__(self):
paul@0 269
paul@0 270
        "Return self as the iterator."
paul@0 271
paul@0 272
        return self
paul@0 273
paul@0 274
    def next(self):
paul@0 275
paul@0 276
        """
paul@0 277
        Return the next content item in the file as a tuple of the form
paul@0 278
        (name, parameters, values).
paul@0 279
        """
paul@0 280
paul@0 281
        return self.parse_content_line()
paul@0 282
paul@7 283
    def decode_content(self, value):
paul@7 284
paul@7 285
        "Decode the given 'value', replacing quoted characters."
paul@7 286
paul@7 287
        return value.replace("\r", "").replace("\\N", "\n").replace("\\n", "\n")
paul@7 288
paul@5 289
    # Internal methods.
paul@5 290
paul@0 291
    def parse_content_line(self):
paul@0 292
paul@0 293
        """
paul@7 294
        Return the name, parameters and value information for the current
paul@7 295
        content line in the file being parsed.
paul@0 296
        """
paul@0 297
paul@0 298
        f = self.f
paul@8 299
        line_number = f.line_number
paul@8 300
        line = f.get_content_line()
paul@0 301
paul@8 302
        # Read the property name.
paul@0 303
paul@8 304
        name, sep = line.search(line.SEPARATORS)
paul@0 305
        name = name.strip()
paul@0 306
paul@0 307
        if not name and sep is None:
paul@0 308
            raise StopIteration
paul@0 309
paul@8 310
        # Read the parameters.
paul@8 311
paul@8 312
        parameters = {}
paul@8 313
paul@0 314
        while sep == ";":
paul@0 315
paul@0 316
            # Find the actual modifier.
paul@0 317
paul@8 318
            parameter_name, sep = line.search(line.SEPARATORS_PLUS_EQUALS)
paul@0 319
            parameter_name = parameter_name.strip()
paul@0 320
paul@0 321
            if sep == "=":
paul@8 322
                parameter_value, sep = line.search(line.SEPARATORS)
paul@0 323
                parameter_value = parameter_value.strip()
paul@0 324
            else:
paul@0 325
                parameter_value = None
paul@0 326
paul@0 327
            # Append a key, value tuple to the parameters list.
paul@0 328
paul@0 329
            parameters[parameter_name] = parameter_value
paul@0 330
paul@0 331
        # Get the value content.
paul@0 332
paul@0 333
        if sep != ":":
paul@30 334
            raise ValueError, (line_number, line)
paul@0 335
paul@8 336
        # Obtain and decode the value.
paul@0 337
paul@8 338
        value = self.decode(name, parameters, line.get_remaining())
paul@0 339
paul@0 340
        return name, parameters, value
paul@0 341
paul@7 342
    def decode(self, name, parameters, value):
paul@1 343
paul@7 344
        "Decode using 'name' and 'parameters' the given 'value'."
paul@0 345
paul@1 346
        encoding = parameters.get("ENCODING")
paul@1 347
        charset = parameters.get("CHARSET")
paul@0 348
paul@7 349
        value = self.decode_content(value)
paul@0 350
paul@0 351
        if encoding == "QUOTED-PRINTABLE":
paul@1 352
            return unicode(quopri.decodestring(value), charset or "iso-8859-1")
paul@0 353
        elif encoding == "BASE64":
paul@0 354
            return base64.decodestring(value)
paul@0 355
        else:
paul@1 356
            return value
paul@0 357
paul@2 358
class ParserBase:
paul@0 359
paul@2 360
    "An abstract parser for content in vCard/vCalendar/iCalendar-like formats."
paul@0 361
paul@0 362
    def __init__(self):
paul@0 363
paul@0 364
        "Initialise the parser."
paul@0 365
paul@2 366
        self.names = []
paul@0 367
paul@5 368
    def parse(self, f, parser_cls=None):
paul@0 369
paul@0 370
        "Parse the contents of the file 'f'."
paul@0 371
paul@5 372
        parser = (parser_cls or StreamParser)(f)
paul@0 373
paul@0 374
        for name, parameters, value in parser:
paul@0 375
paul@0 376
            if name == "BEGIN":
paul@2 377
                self.names.append(value)
paul@3 378
                self.startComponent(value, parameters)
paul@0 379
paul@0 380
            elif name == "END":
paul@2 381
                start_name = self.names.pop()
paul@2 382
                if start_name != value:
paul@0 383
                    raise ParseError, "Mismatch in BEGIN and END declarations (%r and %r) at line %d." % (
paul@2 384
                        start_name, value, f.line_number)
paul@2 385
paul@3 386
                self.endComponent(value)
paul@0 387
paul@0 388
            else:
paul@3 389
                self.handleProperty(name, parameters, value)
paul@2 390
paul@2 391
class Parser(ParserBase):
paul@2 392
paul@2 393
    "A SAX-like parser for vCard/vCalendar/iCalendar-like formats."
paul@2 394
paul@2 395
    def __init__(self):
paul@2 396
        ParserBase.__init__(self)
paul@3 397
        self.components = []
paul@2 398
paul@3 399
    def startComponent(self, name, parameters):
paul@2 400
paul@2 401
        """
paul@3 402
        Add the component with the given 'name' and 'parameters', recording an
paul@3 403
        empty list of children as part of the component's content.
paul@2 404
        """
paul@2 405
paul@12 406
        component = self.handleProperty(name, parameters)
paul@3 407
        self.components.append(component)
paul@3 408
        return component
paul@2 409
paul@3 410
    def endComponent(self, name):
paul@2 411
paul@2 412
        """
paul@3 413
        End the component with the given 'name' by removing it from the active
paul@12 414
        component stack. If only one component exists on the stack, retain it
paul@12 415
        for later inspection.
paul@2 416
        """
paul@2 417
paul@3 418
        if len(self.components) > 1:
paul@3 419
            return self.components.pop()
paul@12 420
paul@12 421
        # Or return the only element.
paul@12 422
paul@3 423
        elif self.components:
paul@12 424
            return self.components[0]
paul@2 425
paul@12 426
    def handleProperty(self, name, parameters, value=None):
paul@0 427
paul@2 428
        """
paul@12 429
        Record the property with the given 'name', 'parameters' and optional
paul@12 430
        'value' as part of the current component's children.
paul@2 431
        """
paul@2 432
paul@2 433
        component = self.makeComponent(name, parameters, value)
paul@2 434
        self.attachComponent(component)
paul@2 435
        return component
paul@2 436
paul@2 437
    # Component object construction/manipulation methods.
paul@2 438
paul@2 439
    def attachComponent(self, component):
paul@2 440
paul@2 441
        "Attach the given 'component' to its parent."
paul@2 442
paul@3 443
        if self.components:
paul@3 444
            component_name, component_parameters, component_children = self.components[-1]
paul@3 445
            component_children.append(component)
paul@2 446
paul@12 447
    def makeComponent(self, name, parameters, value=None):
paul@2 448
paul@2 449
        """
paul@12 450
        Make a component object from the given 'name', 'parameters' and optional
paul@12 451
        'value'.
paul@2 452
        """
paul@2 453
paul@12 454
        return (name, parameters, value or [])
paul@2 455
paul@2 456
    # Public methods.
paul@2 457
paul@5 458
    def parse(self, f, parser_cls=None):
paul@2 459
paul@2 460
        "Parse the contents of the file 'f'."
paul@2 461
paul@5 462
        ParserBase.parse(self, f, parser_cls)
paul@56 463
        try:
paul@56 464
            return self.components[0]
paul@56 465
        except IndexError:
paul@56 466
            raise ParseError, "No vContent component found in file."
paul@0 467
paul@7 468
# Writer classes.
paul@7 469
paul@8 470
class Writer:
paul@8 471
paul@8 472
    "A simple class wrapping a file, providing simple output capabilities."
paul@8 473
paul@8 474
    default_line_length = 76
paul@8 475
paul@21 476
    def __init__(self, write, line_length=None):
paul@8 477
paul@8 478
        """
paul@21 479
        Initialise the object with the given 'write' operation. If 'line_length'
paul@21 480
        is set, the length of written lines will conform to the specified value
paul@21 481
        instead of the default value. 
paul@8 482
        """
paul@8 483
paul@21 484
        self._write = write
paul@8 485
        self.line_length = line_length or self.default_line_length
paul@8 486
        self.char_offset = 0
paul@8 487
paul@8 488
    def write(self, text):
paul@8 489
paul@8 490
        "Write the 'text' to the file."
paul@8 491
paul@21 492
        write = self._write
paul@8 493
        line_length = self.line_length
paul@8 494
paul@8 495
        i = 0
paul@8 496
        remaining = len(text)
paul@8 497
paul@8 498
        while remaining:
paul@8 499
            space = line_length - self.char_offset
paul@8 500
            if remaining > space:
paul@21 501
                write(text[i:i + space])
paul@21 502
                write("\r\n ")
paul@8 503
                self.char_offset = 1
paul@8 504
                i += space
paul@8 505
                remaining -= space
paul@8 506
            else:
paul@21 507
                write(text[i:])
paul@8 508
                self.char_offset += remaining
paul@8 509
                i += remaining
paul@8 510
                remaining = 0
paul@8 511
paul@8 512
    def end_line(self):
paul@8 513
paul@8 514
        "End the current content line."
paul@8 515
paul@8 516
        if self.char_offset > 0:
paul@8 517
            self.char_offset = 0
paul@21 518
            self._write("\r\n")
paul@8 519
paul@7 520
class StreamWriter:
paul@7 521
paul@7 522
    "A stream writer for content in vCard/vCalendar/iCalendar-like formats."
paul@7 523
paul@8 524
    def __init__(self, f):
paul@7 525
paul@21 526
        "Initialise the stream writer with the given 'f' stream object."
paul@7 527
paul@7 528
        self.f = f
paul@7 529
paul@37 530
    def append(self, record):
paul@37 531
        self.write(*record)
paul@37 532
paul@11 533
    def write(self, name, parameters, value):
paul@7 534
paul@7 535
        """
paul@11 536
        Write a content line, serialising the given 'name', 'parameters' and
paul@11 537
        'value' information.
paul@11 538
        """
paul@11 539
paul@11 540
        self.write_content_line(name, self.encode_parameters(parameters), self.encode_value(name, parameters, value))
paul@11 541
paul@11 542
    # Internal methods.
paul@11 543
paul@11 544
    def write_content_line(self, name, encoded_parameters, encoded_value):
paul@11 545
paul@11 546
        """
paul@11 547
        Write a content line for the given 'name', 'encoded_parameters' and
paul@11 548
        'encoded_value' information.
paul@7 549
        """
paul@7 550
paul@7 551
        f = self.f
paul@7 552
paul@7 553
        f.write(name)
paul@11 554
        for param_name, param_value in encoded_parameters.items():
paul@8 555
            f.write(";")
paul@11 556
            f.write(param_name)
paul@8 557
            f.write("=")
paul@11 558
            f.write(param_value)
paul@7 559
        f.write(":")
paul@11 560
        f.write(encoded_value)
paul@8 561
        f.end_line()
paul@7 562
paul@11 563
    def encode_quoted_parameter_value(self, value):
paul@7 564
paul@11 565
        "Encode the given 'value'."
paul@7 566
paul@11 567
        return '"%s"' % value
paul@7 568
paul@11 569
    def encode_value(self, name, parameters, value):
paul@7 570
paul@11 571
        """
paul@11 572
        Encode using 'name' and 'parameters' the given 'value' so that the
paul@11 573
        resulting encoded form employs any specified character encodings.
paul@11 574
        """
paul@7 575
paul@7 576
        encoding = parameters.get("ENCODING")
paul@7 577
        charset = parameters.get("CHARSET")
paul@7 578
paul@66 579
        try:
paul@66 580
            if encoding == "QUOTED-PRINTABLE":
paul@66 581
                value = quopri.encodestring(value.encode(charset or "iso-8859-1"))
paul@66 582
            elif encoding == "BASE64":
paul@66 583
                value = base64.encodestring(value)
paul@7 584
paul@66 585
            return self.encode_content(value)
paul@66 586
        except TypeError:
paul@66 587
            raise WriteError, "Property %r value with parameters %r cannot be encoded: %r" % (name, parameters, value)
paul@7 588
paul@11 589
    # Overrideable methods.
paul@11 590
paul@11 591
    def encode_parameters(self, parameters):
paul@11 592
paul@11 593
        """
paul@11 594
        Encode the given 'parameters' according to the vCalendar specification.
paul@11 595
        """
paul@11 596
paul@11 597
        encoded_parameters = {}
paul@11 598
paul@11 599
        for param_name, param_value in parameters.items():
paul@11 600
paul@11 601
            # Basic format support merely involves quoting values which seem to
paul@11 602
            # need it. Other more specific formats may define exactly which
paul@11 603
            # parameters should be quoted.
paul@11 604
paul@11 605
            if ContentLine.SEPARATORS.search(param_value):
paul@11 606
                param_value = self.encode_quoted_parameter_value(param_value)
paul@11 607
paul@11 608
            encoded_parameters[param_name] = param_value
paul@11 609
paul@11 610
        return encoded_parameters
paul@11 611
paul@11 612
    def encode_content(self, value):
paul@11 613
paul@11 614
        "Encode the given 'value', quoting characters."
paul@11 615
paul@11 616
        return value.replace("\n", "\\n")
paul@11 617
paul@9 618
# Utility functions.
paul@9 619
paul@9 620
def is_input_stream(stream_or_string):
paul@9 621
    return hasattr(stream_or_string, "read")
paul@9 622
paul@11 623
def get_input_stream(stream_or_string, encoding=None):
paul@9 624
    if is_input_stream(stream_or_string):
paul@57 625
        if isinstance(stream_or_string, codecs.StreamReader):
paul@57 626
            return stream_or_string
paul@57 627
        else:
paul@57 628
            return codecs.getreader(encoding or default_encoding)(stream_or_string)
paul@9 629
    else:
paul@11 630
        return codecs.open(stream_or_string, encoding=(encoding or default_encoding))
paul@9 631
paul@11 632
def get_output_stream(stream_or_string, encoding=None):
paul@9 633
    if hasattr(stream_or_string, "write"):
paul@57 634
        if isinstance(stream_or_string, codecs.StreamWriter):
paul@57 635
            return stream_or_string
paul@57 636
        else:
paul@57 637
            return codecs.getwriter(encoding or default_encoding)(stream_or_string)
paul@9 638
    else:
paul@11 639
        return codecs.open(stream_or_string, "w", encoding=(encoding or default_encoding))
paul@9 640
paul@55 641
def items_to_dict(items, sections=None):
paul@40 642
paul@40 643
    """
paul@40 644
    Return the given 'items' as a dictionary mapping names to tuples of the form
paul@55 645
    (value, attributes). Where 'sections' is provided, only items whose names
paul@55 646
    occur in the given 'sections' collection will be treated as groups or
paul@55 647
    sections of definitions.
paul@40 648
    """
paul@40 649
paul@40 650
    d = {}
paul@40 651
    for name, attr, value in items:
paul@40 652
        if not d.has_key(name):
paul@40 653
            d[name] = []
paul@55 654
        if isinstance(value, list) and (not sections or name in sections):
paul@55 655
            d[name].append((items_to_dict(value, sections), attr))
paul@40 656
        else:
paul@40 657
            d[name].append((value, attr))
paul@40 658
    return d
paul@40 659
paul@40 660
def dict_to_items(d):
paul@40 661
paul@40 662
    """
paul@40 663
    Return 'd' converted to a list of items suitable for serialisation using
paul@40 664
    iterwrite.
paul@40 665
    """
paul@40 666
paul@40 667
    items = []
paul@40 668
    for name, value in d.items():
paul@40 669
        if isinstance(value, list):
paul@40 670
            for v, a in value:
paul@40 671
                if isinstance(v, dict):
paul@40 672
                    items.append((name, a, dict_to_items(v)))
paul@40 673
                else:
paul@40 674
                    items.append((name, a, v))
paul@40 675
        else:
paul@40 676
            v, a = value
paul@40 677
            items.append((name, a, dict_to_items(v)))
paul@40 678
    return items
paul@40 679
paul@0 680
# Public functions.
paul@0 681
paul@11 682
def parse(stream_or_string, encoding=None, non_standard_newline=0, parser_cls=None):
paul@0 683
paul@0 684
    """
paul@9 685
    Parse the resource data found through the use of the 'stream_or_string',
paul@9 686
    which is either a stream providing Unicode data (the codecs module can be
paul@9 687
    used to open files or to wrap streams in order to provide Unicode data) or a
paul@9 688
    filename identifying a file to be parsed.
paul@0 689
paul@11 690
    The optional 'encoding' can be used to specify the character encoding used
paul@11 691
    by the file to be parsed.
paul@11 692
paul@0 693
    The optional 'non_standard_newline' can be set to a true value (unlike the
paul@0 694
    default) in order to attempt to process files with CR as the end of line
paul@0 695
    character.
paul@0 696
paul@0 697
    As a result of parsing the resource, the root node of the imported resource
paul@0 698
    is returned.
paul@0 699
    """
paul@0 700
paul@11 701
    stream = get_input_stream(stream_or_string, encoding)
paul@9 702
    reader = Reader(stream, non_standard_newline)
paul@9 703
paul@9 704
    # Parse using the reader.
paul@0 705
paul@9 706
    try:
paul@9 707
        parser = (parser_cls or Parser)()
paul@9 708
        return parser.parse(reader)
paul@9 709
paul@9 710
    # Close any opened streams.
paul@9 711
paul@9 712
    finally:
paul@9 713
        if not is_input_stream(stream_or_string):
paul@9 714
            reader.close()
paul@9 715
paul@11 716
def iterparse(stream_or_string, encoding=None, non_standard_newline=0, parser_cls=None):
paul@5 717
paul@5 718
    """
paul@9 719
    Parse the resource data found through the use of the 'stream_or_string',
paul@9 720
    which is either a stream providing Unicode data (the codecs module can be
paul@9 721
    used to open files or to wrap streams in order to provide Unicode data) or a
paul@9 722
    filename identifying a file to be parsed.
paul@5 723
paul@11 724
    The optional 'encoding' can be used to specify the character encoding used
paul@11 725
    by the file to be parsed.
paul@11 726
paul@5 727
    The optional 'non_standard_newline' can be set to a true value (unlike the
paul@5 728
    default) in order to attempt to process files with CR as the end of line
paul@5 729
    character.
paul@5 730
paul@5 731
    An iterator is returned which provides event tuples describing parsing
paul@5 732
    events of the form (name, parameters, value).
paul@5 733
    """
paul@5 734
paul@11 735
    stream = get_input_stream(stream_or_string, encoding)
paul@9 736
    reader = Reader(stream, non_standard_newline)
paul@5 737
    parser = (parser_cls or StreamParser)(reader)
paul@9 738
    return parser
paul@5 739
paul@21 740
def iterwrite(stream_or_string=None, write=None, encoding=None, line_length=None, writer_cls=None):
paul@11 741
paul@11 742
    """
paul@21 743
    Return a writer which will either send data to the resource found through
paul@21 744
    the use of 'stream_or_string' or using the given 'write' operation.
paul@21 745
paul@21 746
    The 'stream_or_string' parameter may be either a stream accepting Unicode
paul@21 747
    data (the codecs module can be used to open files or to wrap streams in
paul@21 748
    order to accept Unicode data) or a filename identifying a file to be
paul@21 749
    written.
paul@11 750
paul@11 751
    The optional 'encoding' can be used to specify the character encoding used
paul@11 752
    by the file to be written.
paul@11 753
paul@11 754
    The optional 'line_length' can be used to specify how long lines should be
paul@11 755
    in the resulting data.
paul@11 756
    """
paul@11 757
paul@21 758
    if stream_or_string:
paul@21 759
        stream = get_output_stream(stream_or_string, encoding)
paul@21 760
        _writer = Writer(stream.write, line_length)
paul@21 761
    elif write:
paul@21 762
        _writer = Writer(write, line_length)
paul@21 763
    else:
paul@21 764
        raise IOError, "No stream, filename or write operation specified."
paul@21 765
paul@21 766
    return (writer_cls or StreamWriter)(_writer)
paul@8 767
paul@55 768
def to_dict(node, sections=None):
paul@40 769
paul@40 770
    "Return the 'node' converted to a dictionary representation."
paul@40 771
paul@40 772
    name, attr, items = node
paul@55 773
    return {name : (isinstance(items, list) and items_to_dict(items, sections) or items, attr)}
paul@40 774
paul@40 775
def to_node(d):
paul@40 776
paul@40 777
    "Return 'd' converted to a items-based representation."
paul@40 778
paul@40 779
    return dict_to_items(d)[0]
paul@40 780
paul@0 781
# vim: tabstop=4 expandtab shiftwidth=4