imip-agent

Annotated vCalendar.py

135:f07cd72fbece
2014-12-16 Paul Boddie Only compare object sequences when both objects provide them.
paul@0 1
#!/usr/bin/env python
paul@0 2
paul@0 3
"""
paul@0 4
Parsing of vCalendar and iCalendar files.
paul@0 5
paul@7 6
Copyright (C) 2008, 2009, 2011, 2013, 2014 Paul Boddie <paul@boddie.org.uk>
paul@0 7
paul@0 8
This program is free software; you can redistribute it and/or modify it under
paul@0 9
the terms of the GNU General Public License as published by the Free Software
paul@0 10
Foundation; either version 3 of the License, or (at your option) any later
paul@0 11
version.
paul@0 12
paul@0 13
This program is distributed in the hope that it will be useful, but WITHOUT
paul@0 14
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
paul@0 15
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
paul@0 16
details.
paul@0 17
paul@0 18
You should have received a copy of the GNU General Public License along with
paul@0 19
this program.  If not, see <http://www.gnu.org/licenses/>.
paul@0 20
paul@0 21
--------
paul@0 22
paul@0 23
References:
paul@0 24
paul@0 25
RFC 5545: Internet Calendaring and Scheduling Core Object Specification
paul@0 26
          (iCalendar)
paul@0 27
          http://tools.ietf.org/html/rfc5545
paul@0 28
paul@0 29
RFC 2445: Internet Calendaring and Scheduling Core Object Specification
paul@0 30
          (iCalendar)
paul@0 31
          http://tools.ietf.org/html/rfc2445
paul@0 32
"""
paul@0 33
paul@0 34
import vContent
paul@0 35
import re
paul@0 36
paul@0 37
try:
paul@0 38
    set
paul@0 39
except NameError:
paul@0 40
    from sets import Set as set
paul@0 41
paul@7 42
ParseError = vContent.ParseError
paul@7 43
paul@0 44
# Format details.
paul@0 45
paul@4 46
SECTION_TYPES = set([
paul@4 47
    "VALARM", "VCALENDAR", "VEVENT", "VFREEBUSY", "VJOURNAL", "VTIMEZONE", "VTODO"
paul@4 48
    ])
paul@0 49
QUOTED_PARAMETERS = set([
paul@0 50
    "ALTREP", "DELEGATED-FROM", "DELEGATED-TO", "DIR", "MEMBER", "SENT-BY"
paul@0 51
    ])
paul@0 52
MULTIVALUED_PARAMETERS = set([
paul@0 53
    "DELEGATED-FROM", "DELEGATED-TO", "MEMBER"
paul@0 54
    ])
paul@0 55
QUOTED_TYPES = set(["URI"])
paul@0 56
paul@0 57
unquoted_separator_regexp = re.compile(r"(?<!\\)([,;])")
paul@0 58
paul@0 59
# Parser classes.
paul@0 60
paul@0 61
class vCalendarStreamParser(vContent.StreamParser):
paul@0 62
paul@0 63
    "A stream parser specifically for vCalendar/iCalendar."
paul@0 64
paul@0 65
    def next(self):
paul@0 66
paul@0 67
        """
paul@0 68
        Return the next content item in the file as a tuple of the form
paul@0 69
        (name, parameters, value).
paul@0 70
        """
paul@0 71
paul@0 72
        name, parameters, value = vContent.StreamParser.next(self)
paul@0 73
        return name, self.decode_parameters(parameters), value
paul@0 74
paul@0 75
    def decode_content(self, value):
paul@0 76
paul@0 77
        """
paul@0 78
        Decode the given 'value' (which may represent a collection of distinct
paul@0 79
        values), replacing quoted separator characters.
paul@0 80
        """
paul@0 81
paul@0 82
        sep = None
paul@0 83
        values = []
paul@0 84
paul@0 85
        for i, s in enumerate(unquoted_separator_regexp.split(value)):
paul@0 86
            if i % 2 != 0:
paul@0 87
                if not sep:
paul@0 88
                    sep = s
paul@0 89
                continue
paul@0 90
            values.append(self.decode_content_value(s))
paul@0 91
paul@0 92
        if sep == ",":
paul@0 93
            return values
paul@0 94
        elif sep == ";":
paul@0 95
            return tuple(values)
paul@0 96
        else:
paul@0 97
            return values[0]
paul@0 98
paul@0 99
    def decode_content_value(self, value):
paul@0 100
paul@0 101
        "Decode the given 'value', replacing quoted separator characters."
paul@0 102
paul@0 103
        # Replace quoted characters (see 4.3.11 in RFC 2445).
paul@0 104
paul@0 105
        value = vContent.StreamParser.decode_content(self, value)
paul@0 106
        return value.replace(r"\,", ",").replace(r"\;", ";")
paul@0 107
paul@0 108
    # Internal methods.
paul@0 109
paul@0 110
    def decode_quoted_value(self, value):
paul@0 111
paul@0 112
        "Decode the given 'value', returning a list of decoded values."
paul@0 113
paul@0 114
        if value[0] == '"' and value[-1] == '"':
paul@0 115
            return value[1:-1]
paul@0 116
        else:
paul@0 117
            return value
paul@0 118
paul@0 119
    def decode_parameters(self, parameters):
paul@0 120
paul@0 121
        """
paul@0 122
        Decode the given 'parameters' according to the vCalendar specification.
paul@0 123
        """
paul@0 124
paul@0 125
        decoded_parameters = {}
paul@0 126
paul@0 127
        for param_name, param_value in parameters.items():
paul@0 128
            if param_name in QUOTED_PARAMETERS:
paul@0 129
                param_value = self.decode_quoted_value(param_value)
paul@0 130
                separator = '","'
paul@0 131
            else:
paul@0 132
                separator = ","
paul@0 133
            if param_name in MULTIVALUED_PARAMETERS:
paul@0 134
                param_value = param_value.split(separator)
paul@0 135
            decoded_parameters[param_name] = param_value
paul@0 136
paul@0 137
        return decoded_parameters
paul@0 138
paul@0 139
class vCalendarParser(vContent.Parser):
paul@0 140
paul@0 141
    "A parser specifically for vCalendar/iCalendar."
paul@0 142
paul@0 143
    def parse(self, f, parser_cls=None):
paul@0 144
        return vContent.Parser.parse(self, f, (parser_cls or vCalendarStreamParser))
paul@0 145
paul@0 146
# Writer classes.
paul@0 147
paul@0 148
class vCalendarStreamWriter(vContent.StreamWriter):
paul@0 149
paul@0 150
    "A stream writer specifically for vCalendar."
paul@0 151
paul@0 152
    # Overridden methods.
paul@0 153
paul@4 154
    def write(self, name, parameters, value):
paul@4 155
paul@4 156
        """
paul@4 157
        Write a content line, serialising the given 'name', 'parameters' and
paul@4 158
        'value' information.
paul@4 159
        """
paul@4 160
paul@4 161
        if name in SECTION_TYPES:
paul@4 162
            self.write_content_line("BEGIN", {}, name)
paul@4 163
            for n, p, v in value:
paul@4 164
                self.write(n, p, v)
paul@4 165
            self.write_content_line("END", {}, name)
paul@4 166
        else:
paul@4 167
            vContent.StreamWriter.write(self, name, parameters, value)
paul@4 168
paul@0 169
    def encode_parameters(self, parameters):
paul@0 170
paul@0 171
        """
paul@0 172
        Encode the given 'parameters' according to the vCalendar specification.
paul@0 173
        """
paul@0 174
paul@0 175
        encoded_parameters = {}
paul@0 176
paul@0 177
        for param_name, param_value in parameters.items():
paul@0 178
            if param_name in QUOTED_PARAMETERS:
paul@0 179
                param_value = self.encode_quoted_parameter_value(param_value)
paul@0 180
                separator = '","'
paul@0 181
            else:
paul@0 182
                separator = ","
paul@0 183
            if param_name in MULTIVALUED_PARAMETERS:
paul@0 184
                param_value = separator.join(param_value)
paul@0 185
            encoded_parameters[param_name] = param_value
paul@0 186
paul@0 187
        return encoded_parameters
paul@0 188
paul@0 189
    def encode_content(self, value):
paul@0 190
paul@0 191
        """
paul@0 192
        Encode the given 'value' (which may be a list or tuple of separate
paul@0 193
        values), quoting characters and separating collections of values.
paul@0 194
        """
paul@0 195
paul@0 196
        if isinstance(value, list):
paul@0 197
            sep = ","
paul@0 198
        elif isinstance(value, tuple):
paul@0 199
            sep = ";"
paul@0 200
        else:
paul@0 201
            value = [value]
paul@0 202
            sep = ""
paul@0 203
paul@0 204
        return sep.join([self.encode_content_value(v) for v in value])
paul@0 205
paul@0 206
    def encode_content_value(self, value):
paul@0 207
paul@0 208
        "Encode the given 'value', quoting characters."
paul@0 209
paul@0 210
        # Replace quoted characters (see 4.3.11 in RFC 2445).
paul@0 211
paul@0 212
        value = vContent.StreamWriter.encode_content(self, value)
paul@0 213
        return value.replace(";", r"\;").replace(",", r"\,")
paul@0 214
paul@0 215
# Public functions.
paul@0 216
paul@0 217
def parse(stream_or_string, encoding=None, non_standard_newline=0):
paul@0 218
paul@0 219
    """
paul@0 220
    Parse the resource data found through the use of the 'stream_or_string',
paul@0 221
    which is either a stream providing Unicode data (the codecs module can be
paul@0 222
    used to open files or to wrap streams in order to provide Unicode data) or a
paul@0 223
    filename identifying a file to be parsed.
paul@0 224
paul@0 225
    The optional 'encoding' can be used to specify the character encoding used
paul@0 226
    by the file to be parsed.
paul@0 227
paul@0 228
    The optional 'non_standard_newline' can be set to a true value (unlike the
paul@0 229
    default) in order to attempt to process files with CR as the end of line
paul@0 230
    character.
paul@0 231
paul@0 232
    As a result of parsing the resource, the root node of the imported resource
paul@0 233
    is returned.
paul@0 234
    """
paul@0 235
paul@0 236
    return vContent.parse(stream_or_string, encoding, non_standard_newline, vCalendarParser)
paul@0 237
paul@0 238
def iterparse(stream_or_string, encoding=None, non_standard_newline=0):
paul@0 239
paul@0 240
    """
paul@0 241
    Parse the resource data found through the use of the 'stream_or_string',
paul@0 242
    which is either a stream providing Unicode data (the codecs module can be
paul@0 243
    used to open files or to wrap streams in order to provide Unicode data) or a
paul@0 244
    filename identifying a file to be parsed.
paul@0 245
paul@0 246
    The optional 'encoding' can be used to specify the character encoding used
paul@0 247
    by the file to be parsed.
paul@0 248
paul@0 249
    The optional 'non_standard_newline' can be set to a true value (unlike the
paul@0 250
    default) in order to attempt to process files with CR as the end of line
paul@0 251
    character.
paul@0 252
paul@0 253
    An iterator is returned which provides event tuples describing parsing
paul@0 254
    events of the form (name, parameters, value).
paul@0 255
    """
paul@0 256
paul@0 257
    return vContent.iterparse(stream_or_string, encoding, non_standard_newline, vCalendarStreamParser)
paul@0 258
paul@0 259
def iterwrite(stream_or_string=None, write=None, encoding=None, line_length=None):
paul@0 260
paul@0 261
    """
paul@0 262
    Return a writer which will either send data to the resource found through
paul@0 263
    the use of 'stream_or_string' or using the given 'write' operation.
paul@0 264
paul@0 265
    The 'stream_or_string' parameter may be either a stream accepting Unicode
paul@0 266
    data (the codecs module can be used to open files or to wrap streams in
paul@0 267
    order to accept Unicode data) or a filename identifying a file to be
paul@0 268
    written.
paul@0 269
paul@0 270
    The optional 'encoding' can be used to specify the character encoding used
paul@0 271
    by the file to be written.
paul@0 272
paul@0 273
    The optional 'line_length' can be used to specify how long lines should be
paul@0 274
    in the resulting data.
paul@0 275
    """
paul@0 276
paul@0 277
    return vContent.iterwrite(stream_or_string, write, encoding, line_length, vCalendarStreamWriter)
paul@0 278
paul@107 279
def to_dict(node):
paul@107 280
paul@107 281
    "Return the 'node' converted to a dictionary representation."
paul@107 282
paul@107 283
    return vContent.to_dict(node, SECTION_TYPES)
paul@107 284
paul@26 285
to_node = vContent.to_node
paul@26 286
paul@0 287
# vim: tabstop=4 expandtab shiftwidth=4