imip-agent

Annotated vCalendar.py

1173:318433c9a1c2
828:a7cd403b328b
816:03b19593fcbf
2015-10-13 Paul Boddie file changeset files shortlog Fixed encoding of None values produced by vCalendar parsing.
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@816     47 
    "VALARM", "VCALENDAR", "VEVENT", "VFREEBUSY", "VJOURNAL", "VTIMEZONE", "VTODO",
 
 paul@816     48 
    "DAYLIGHT", "STANDARD"
 
 paul@4     49 
    ])
 
 paul@0     50 
QUOTED_PARAMETERS = set([
 
 paul@0     51 
    "ALTREP", "DELEGATED-FROM", "DELEGATED-TO", "DIR", "MEMBER", "SENT-BY"
 
 paul@0     52 
    ])
 
 paul@0     53 
MULTIVALUED_PARAMETERS = set([
 
 paul@0     54 
    "DELEGATED-FROM", "DELEGATED-TO", "MEMBER"
 
 paul@0     55 
    ])
 
 paul@0     56 
QUOTED_TYPES = set(["URI"])
 
 paul@0     57 
 
 paul@0     58 
unquoted_separator_regexp = re.compile(r"(?<!\\)([,;])")
 
 paul@0     59 
 
 paul@0     60 
# Parser classes.
 
 paul@0     61 
 
 paul@0     62 
class vCalendarStreamParser(vContent.StreamParser):
 
 paul@0     63 
 
 paul@0     64 
    "A stream parser specifically for vCalendar/iCalendar."
 
 paul@0     65 
 
 paul@0     66 
    def next(self):
 
 paul@0     67 
 
 paul@0     68 
        """
 
 paul@0     69 
        Return the next content item in the file as a tuple of the form
 
 paul@0     70 
        (name, parameters, value).
 
 paul@0     71 
        """
 
 paul@0     72 
 
 paul@0     73 
        name, parameters, value = vContent.StreamParser.next(self)
 
 paul@0     74 
        return name, self.decode_parameters(parameters), value
 
 paul@0     75 
 
 paul@0     76 
    def decode_content(self, value):
 
 paul@0     77 
 
 paul@0     78 
        """
 
 paul@0     79 
        Decode the given 'value' (which may represent a collection of distinct
 
 paul@0     80 
        values), replacing quoted separator characters.
 
 paul@0     81 
        """
 
 paul@0     82 
 
 paul@0     83 
        sep = None
 
 paul@0     84 
        values = []
 
 paul@0     85 
 
 paul@0     86 
        for i, s in enumerate(unquoted_separator_regexp.split(value)):
 
 paul@0     87 
            if i % 2 != 0:
 
 paul@0     88 
                if not sep:
 
 paul@0     89 
                    sep = s
 
 paul@0     90 
                continue
 
 paul@0     91 
            values.append(self.decode_content_value(s))
 
 paul@0     92 
 
 paul@0     93 
        if sep == ",":
 
 paul@0     94 
            return values
 
 paul@0     95 
        elif sep == ";":
 
 paul@0     96 
            return tuple(values)
 
 paul@0     97 
        else:
 
 paul@0     98 
            return values[0]
 
 paul@0     99 
 
 paul@0    100 
    def decode_content_value(self, value):
 
 paul@0    101 
 
 paul@0    102 
        "Decode the given 'value', replacing quoted separator characters."
 
 paul@0    103 
 
 paul@0    104 
        # Replace quoted characters (see 4.3.11 in RFC 2445).
 
 paul@0    105 
 
 paul@0    106 
        value = vContent.StreamParser.decode_content(self, value)
 
 paul@0    107 
        return value.replace(r"\,", ",").replace(r"\;", ";")
 
 paul@0    108 
 
 paul@0    109 
    # Internal methods.
 
 paul@0    110 
 
 paul@0    111 
    def decode_quoted_value(self, value):
 
 paul@0    112 
 
 paul@0    113 
        "Decode the given 'value', returning a list of decoded values."
 
 paul@0    114 
 
 paul@0    115 
        if value[0] == '"' and value[-1] == '"':
 
 paul@0    116 
            return value[1:-1]
 
 paul@0    117 
        else:
 
 paul@0    118 
            return value
 
 paul@0    119 
 
 paul@0    120 
    def decode_parameters(self, parameters):
 
 paul@0    121 
 
 paul@0    122 
        """
 
 paul@0    123 
        Decode the given 'parameters' according to the vCalendar specification.
 
 paul@0    124 
        """
 
 paul@0    125 
 
 paul@0    126 
        decoded_parameters = {}
 
 paul@0    127 
 
 paul@0    128 
        for param_name, param_value in parameters.items():
 
 paul@0    129 
            if param_name in QUOTED_PARAMETERS:
 
 paul@0    130 
                param_value = self.decode_quoted_value(param_value)
 
 paul@0    131 
                separator = '","'
 
 paul@0    132 
            else:
 
 paul@0    133 
                separator = ","
 
 paul@0    134 
            if param_name in MULTIVALUED_PARAMETERS:
 
 paul@0    135 
                param_value = param_value.split(separator)
 
 paul@0    136 
            decoded_parameters[param_name] = param_value
 
 paul@0    137 
 
 paul@0    138 
        return decoded_parameters
 
 paul@0    139 
 
 paul@0    140 
class vCalendarParser(vContent.Parser):
 
 paul@0    141 
 
 paul@0    142 
    "A parser specifically for vCalendar/iCalendar."
 
 paul@0    143 
 
 paul@0    144 
    def parse(self, f, parser_cls=None):
 
 paul@0    145 
        return vContent.Parser.parse(self, f, (parser_cls or vCalendarStreamParser))
 
 paul@0    146 
 
 paul@713    147 
    def makeComponent(self, name, parameters, value=None):
 
 paul@713    148 
 
 paul@713    149 
        """
 
 paul@713    150 
        Make a component object from the given 'name', 'parameters' and optional
 
 paul@713    151 
        'value'.
 
 paul@713    152 
        """
 
 paul@713    153 
 
 paul@713    154 
        if name in SECTION_TYPES:
 
 paul@713    155 
            return (name, parameters, value or [])
 
 paul@713    156 
        else:
 
 paul@713    157 
            return (name, parameters, value or None)
 
 paul@713    158 
 
 paul@0    159 
# Writer classes.
 
 paul@0    160 
 
 paul@0    161 
class vCalendarStreamWriter(vContent.StreamWriter):
 
 paul@0    162 
 
 paul@0    163 
    "A stream writer specifically for vCalendar."
 
 paul@0    164 
 
 paul@0    165 
    # Overridden methods.
 
 paul@0    166 
 
 paul@4    167 
    def write(self, name, parameters, value):
 
 paul@4    168 
 
 paul@4    169 
        """
 
 paul@4    170 
        Write a content line, serialising the given 'name', 'parameters' and
 
 paul@4    171 
        'value' information.
 
 paul@4    172 
        """
 
 paul@4    173 
 
 paul@4    174 
        if name in SECTION_TYPES:
 
 paul@4    175 
            self.write_content_line("BEGIN", {}, name)
 
 paul@4    176 
            for n, p, v in value:
 
 paul@4    177 
                self.write(n, p, v)
 
 paul@4    178 
            self.write_content_line("END", {}, name)
 
 paul@4    179 
        else:
 
 paul@4    180 
            vContent.StreamWriter.write(self, name, parameters, value)
 
 paul@4    181 
 
 paul@0    182 
    def encode_parameters(self, parameters):
 
 paul@0    183 
 
 paul@0    184 
        """
 
 paul@0    185 
        Encode the given 'parameters' according to the vCalendar specification.
 
 paul@0    186 
        """
 
 paul@0    187 
 
 paul@0    188 
        encoded_parameters = {}
 
 paul@0    189 
 
 paul@0    190 
        for param_name, param_value in parameters.items():
 
 paul@0    191 
            if param_name in QUOTED_PARAMETERS:
 
 paul@0    192 
                param_value = self.encode_quoted_parameter_value(param_value)
 
 paul@0    193 
                separator = '","'
 
 paul@0    194 
            else:
 
 paul@0    195 
                separator = ","
 
 paul@0    196 
            if param_name in MULTIVALUED_PARAMETERS:
 
 paul@0    197 
                param_value = separator.join(param_value)
 
 paul@0    198 
            encoded_parameters[param_name] = param_value
 
 paul@0    199 
 
 paul@0    200 
        return encoded_parameters
 
 paul@0    201 
 
 paul@0    202 
    def encode_content(self, value):
 
 paul@0    203 
 
 paul@0    204 
        """
 
 paul@0    205 
        Encode the given 'value' (which may be a list or tuple of separate
 
 paul@0    206 
        values), quoting characters and separating collections of values.
 
 paul@0    207 
        """
 
 paul@0    208 
 
 paul@0    209 
        if isinstance(value, list):
 
 paul@0    210 
            sep = ","
 
 paul@0    211 
        elif isinstance(value, tuple):
 
 paul@0    212 
            sep = ";"
 
 paul@0    213 
        else:
 
 paul@0    214 
            value = [value]
 
 paul@0    215 
            sep = ""
 
 paul@0    216 
 
 paul@0    217 
        return sep.join([self.encode_content_value(v) for v in value])
 
 paul@0    218 
 
 paul@0    219 
    def encode_content_value(self, value):
 
 paul@0    220 
 
 paul@0    221 
        "Encode the given 'value', quoting characters."
 
 paul@0    222 
 
 paul@0    223 
        # Replace quoted characters (see 4.3.11 in RFC 2445).
 
 paul@0    224 
 
 paul@0    225 
        value = vContent.StreamWriter.encode_content(self, value)
 
 paul@0    226 
        return value.replace(";", r"\;").replace(",", r"\,")
 
 paul@0    227 
 
 paul@0    228 
# Public functions.
 
 paul@0    229 
 
 paul@0    230 
def parse(stream_or_string, encoding=None, non_standard_newline=0):
 
 paul@0    231 
 
 paul@0    232 
    """
 
 paul@0    233 
    Parse the resource data found through the use of the 'stream_or_string',
 
 paul@0    234 
    which is either a stream providing Unicode data (the codecs module can be
 
 paul@0    235 
    used to open files or to wrap streams in order to provide Unicode data) or a
 
 paul@0    236 
    filename identifying a file to be parsed.
 
 paul@0    237 
 
 paul@0    238 
    The optional 'encoding' can be used to specify the character encoding used
 
 paul@0    239 
    by the file to be parsed.
 
 paul@0    240 
 
 paul@0    241 
    The optional 'non_standard_newline' can be set to a true value (unlike the
 
 paul@0    242 
    default) in order to attempt to process files with CR as the end of line
 
 paul@0    243 
    character.
 
 paul@0    244 
 
 paul@0    245 
    As a result of parsing the resource, the root node of the imported resource
 
 paul@0    246 
    is returned.
 
 paul@0    247 
    """
 
 paul@0    248 
 
 paul@0    249 
    return vContent.parse(stream_or_string, encoding, non_standard_newline, vCalendarParser)
 
 paul@0    250 
 
 paul@0    251 
def iterparse(stream_or_string, encoding=None, non_standard_newline=0):
 
 paul@0    252 
 
 paul@0    253 
    """
 
 paul@0    254 
    Parse the resource data found through the use of the 'stream_or_string',
 
 paul@0    255 
    which is either a stream providing Unicode data (the codecs module can be
 
 paul@0    256 
    used to open files or to wrap streams in order to provide Unicode data) or a
 
 paul@0    257 
    filename identifying a file to be parsed.
 
 paul@0    258 
 
 paul@0    259 
    The optional 'encoding' can be used to specify the character encoding used
 
 paul@0    260 
    by the file to be parsed.
 
 paul@0    261 
 
 paul@0    262 
    The optional 'non_standard_newline' can be set to a true value (unlike the
 
 paul@0    263 
    default) in order to attempt to process files with CR as the end of line
 
 paul@0    264 
    character.
 
 paul@0    265 
 
 paul@0    266 
    An iterator is returned which provides event tuples describing parsing
 
 paul@0    267 
    events of the form (name, parameters, value).
 
 paul@0    268 
    """
 
 paul@0    269 
 
 paul@0    270 
    return vContent.iterparse(stream_or_string, encoding, non_standard_newline, vCalendarStreamParser)
 
 paul@0    271 
 
 paul@0    272 
def iterwrite(stream_or_string=None, write=None, encoding=None, line_length=None):
 
 paul@0    273 
 
 paul@0    274 
    """
 
 paul@0    275 
    Return a writer which will either send data to the resource found through
 
 paul@0    276 
    the use of 'stream_or_string' or using the given 'write' operation.
 
 paul@0    277 
 
 paul@0    278 
    The 'stream_or_string' parameter may be either a stream accepting Unicode
 
 paul@0    279 
    data (the codecs module can be used to open files or to wrap streams in
 
 paul@0    280 
    order to accept Unicode data) or a filename identifying a file to be
 
 paul@0    281 
    written.
 
 paul@0    282 
 
 paul@0    283 
    The optional 'encoding' can be used to specify the character encoding used
 
 paul@0    284 
    by the file to be written.
 
 paul@0    285 
 
 paul@0    286 
    The optional 'line_length' can be used to specify how long lines should be
 
 paul@0    287 
    in the resulting data.
 
 paul@0    288 
    """
 
 paul@0    289 
 
 paul@0    290 
    return vContent.iterwrite(stream_or_string, write, encoding, line_length, vCalendarStreamWriter)
 
 paul@0    291 
 
 paul@107    292 
def to_dict(node):
 
 paul@107    293 
 
 paul@107    294 
    "Return the 'node' converted to a dictionary representation."
 
 paul@107    295 
 
 paul@107    296 
    return vContent.to_dict(node, SECTION_TYPES)
 
 paul@107    297 
 
 paul@26    298 
to_node = vContent.to_node
 
 paul@26    299 
 
 paul@0    300 
# vim: tabstop=4 expandtab shiftwidth=4