imip-agent

Annotated vCalendar.py

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