imip-agent

Annotated vCalendar.py

713:6b3b9902fe53
471:f5fd49a85dc5
107:3a1b5b29938c
2015-03-31 Paul Boddie file changeset files shortlog Change the cursor over day and timepoint headings and over empty slots.
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