Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Factory class for all the property types."""
3from __future__ import annotations
5from typing import Any, ClassVar
7from icalendar.caselessdict import CaselessDict
8from icalendar.prop.adr import vAdr
9from icalendar.prop.binary import vBinary
10from icalendar.prop.boolean import vBoolean
11from icalendar.prop.cal_address import vCalAddress
12from icalendar.prop.categories import vCategory
13from icalendar.prop.dt import (
14 vDate,
15 vDatetime,
16 vDDDLists,
17 vDDDTypes,
18 vDuration,
19 vPeriod,
20 vTime,
21 vUTCOffset,
22)
23from icalendar.prop.float import vFloat
24from icalendar.prop.geo import vGeo
25from icalendar.prop.inline import vInline
26from icalendar.prop.n import vN
27from icalendar.prop.org import vOrg
28from icalendar.prop.recur import vFrequency, vRecur, vWeekday
29from icalendar.prop.text import vText
30from icalendar.prop.uid import vUid
31from icalendar.prop.unknown import vUnknown
32from icalendar.prop.uri import vUri
33from icalendar.prop.xml_reference import vXmlReference
35from .integer import vInt
38class TypesFactory(CaselessDict):
39 """Factory for all value types defined in :rfc:`5545` and subsequent.
41 The value and parameter names don't overlap. So one factory is enough for
42 both kinds.
43 """
45 _instance: ClassVar[TypesFactory | None] = None
47 def instance() -> TypesFactory:
48 """Return a singleton instance of this class."""
49 if TypesFactory._instance is None:
50 TypesFactory._instance = TypesFactory()
51 return TypesFactory._instance
53 def __init__(self, *args: Any, **kwargs: Any) -> None:
54 """Set keys to upper for initial dict"""
55 super().__init__(*args, **kwargs)
56 self.all_types = (
57 vBinary,
58 vBoolean,
59 vCalAddress,
60 vDDDLists,
61 vDDDTypes,
62 vDate,
63 vDatetime,
64 vDuration,
65 vFloat,
66 vFrequency,
67 vGeo,
68 vInline,
69 vInt,
70 vPeriod,
71 vRecur,
72 vText,
73 vTime,
74 vUTCOffset,
75 vUri,
76 vWeekday,
77 vCategory,
78 vAdr,
79 vN,
80 vOrg,
81 vUid,
82 vXmlReference,
83 vUnknown,
84 )
85 self["binary"] = vBinary
86 self["boolean"] = vBoolean
87 self["cal-address"] = vCalAddress
88 self["date"] = vDDDTypes
89 self["date-time"] = vDDDTypes
90 self["duration"] = vDDDTypes
91 self["float"] = vFloat
92 self["integer"] = vInt
93 self["period"] = vPeriod
94 self["recur"] = vRecur
95 self["text"] = vText
96 self["time"] = vTime
97 self["uri"] = vUri
98 self["utc-offset"] = vUTCOffset
99 self["geo"] = vGeo
100 self["inline"] = vInline
101 self["date-time-list"] = vDDDLists
102 self["categories"] = vCategory
103 self["adr"] = vAdr # RFC 6350 vCard
104 self["n"] = vN # RFC 6350 vCard
105 self["org"] = vOrg # RFC 6350 vCard
106 self["unknown"] = vUnknown # RFC 7265
107 self["uid"] = vUid # RFC 9253
108 self["xml-reference"] = vXmlReference # RFC 9253
110 #################################################
111 # Property types
113 # These are the default types
114 types_map = CaselessDict(
115 {
116 ####################################
117 # Property value types
118 # Calendar Properties
119 "calscale": "text",
120 "method": "text",
121 "prodid": "text",
122 "version": "text",
123 # Descriptive Component Properties
124 "attach": "uri",
125 "categories": "categories",
126 "class": "text",
127 # vCard Properties (RFC 6350)
128 "adr": "adr",
129 "n": "n",
130 "org": "org",
131 "comment": "text",
132 "description": "text",
133 "geo": "geo",
134 "location": "text",
135 "percent-complete": "integer",
136 "priority": "integer",
137 "resources": "text",
138 "status": "text",
139 "summary": "text",
140 # RFC 9253
141 # link should be uri, xml-reference or uid
142 # uri is likely most helpful if people forget to set VALUE
143 "link": "uri",
144 "concept": "uri",
145 "refid": "text",
146 # Date and Time Component Properties
147 "completed": "date-time",
148 "dtend": "date-time",
149 "due": "date-time",
150 "dtstart": "date-time",
151 "duration": "duration",
152 "freebusy": "period",
153 "transp": "text",
154 "refresh-interval": "duration", # RFC 7986
155 # Time Zone Component Properties
156 "tzid": "text",
157 "tzname": "text",
158 "tzoffsetfrom": "utc-offset",
159 "tzoffsetto": "utc-offset",
160 "tzurl": "uri",
161 # Relationship Component Properties
162 "attendee": "cal-address",
163 "contact": "text",
164 "organizer": "cal-address",
165 "recurrence-id": "date-time",
166 "related-to": "text",
167 "url": "uri",
168 "conference": "uri", # RFC 7986
169 "image": "unknown", # RFC 7986 has no default value type
170 "source": "uri",
171 "uid": "text",
172 # Recurrence Component Properties
173 "exdate": "date-time-list",
174 "exrule": "recur",
175 "rdate": "date-time-list",
176 "rrule": "recur",
177 # Alarm Component Properties
178 "action": "text",
179 "repeat": "integer",
180 "trigger": "duration",
181 "acknowledged": "date-time",
182 "proximity": "text", # RFC 9074
183 # Change Management Component Properties
184 "created": "date-time",
185 "dtstamp": "date-time",
186 "last-modified": "date-time",
187 "sequence": "integer",
188 # Miscellaneous Component Properties
189 "request-status": "text",
190 ####################################
191 # parameter types (luckily there is no name overlap)
192 "altrep": "uri",
193 "cn": "text",
194 "cutype": "text",
195 "delegated-from": "cal-address",
196 "delegated-to": "cal-address",
197 "dir": "uri",
198 "encoding": "text",
199 "fmttype": "text",
200 "fbtype": "text",
201 "language": "text",
202 "member": "cal-address",
203 "partstat": "text",
204 "range": "text",
205 "related": "text",
206 "reltype": "text",
207 "role": "text",
208 "rsvp": "boolean",
209 "sent-by": "cal-address",
210 "value": "text",
211 # rfc 9253 parameters
212 "label": "text",
213 "linkrel": "text",
214 "gap": "duration",
215 }
216 )
218 def for_property(self, name, value_param: str | None = None) -> type:
219 """Returns the type class for a property or parameter.
221 Parameters:
222 name: Property or parameter name
223 value_param: Optional ``VALUE`` parameter, for example,
224 "DATE", "DATE-TIME", or other string.
226 Returns:
227 The appropriate value type class.
228 """
229 # Special case: RDATE and EXDATE always use vDDDLists to support list values
230 # regardless of the VALUE parameter
231 if name.upper() in ("RDATE", "EXDATE"):
232 return self["date-time-list"]
234 # Only use VALUE parameter for known properties that support multiple value
235 # types (like DTSTART, DTEND, etc. which can be DATE or DATE-TIME)
236 # For unknown/custom properties, always use the default type from types_map
237 if value_param and name in self.types_map and value_param in self:
238 return self[value_param]
240 if value_param and (value_param in self) and value_param != "IMAGE":
241 return self[value_param]
243 return self[self.types_map.get(name, "unknown")]
245 #: jCal value types defined by :rfc:`7265` that are used verbatim as the
246 #: type field. Internal type keys outside of this set (for example
247 #: ``"categories"`` or ``"date-time-list"``) are mapped to their concrete
248 #: jCal type via the value class.
249 _jcal_value_types = frozenset(
250 {
251 "binary",
252 "boolean",
253 "cal-address",
254 "date",
255 "date-time",
256 "duration",
257 "float",
258 "integer",
259 "period",
260 "recur",
261 "text",
262 "time",
263 "uri",
264 "utc-offset",
265 "unknown",
266 }
267 )
269 def default_value_type(self, name: str) -> str:
270 """Return the default jCal value type for a property.
272 The result is a lowercase :rfc:`7265` value type, for example
273 ``"date-time"`` for ``DTSTART`` or ``"duration"`` for ``TRIGGER``.
274 This is the value type a property uses when no explicit ``VALUE``
275 parameter is given, so it tells :func:`Component.from_jcal` whether a
276 ``VALUE`` parameter has to be restored from the jCal type field.
278 Parameters:
279 name: Property name.
281 Returns:
282 The default jCal value type as a lowercase string.
283 """
284 internal = self.types_map.get(name.lower(), "unknown")
285 if internal in self._jcal_value_types:
286 return internal
287 # Internal keys such as ``categories`` or ``date-time-list`` are not
288 # jCal value types themselves; ask the value class for the type it
289 # actually serialises to.
290 try:
291 return self[internal].examples()[0].VALUE.lower()
292 except (KeyError, IndexError, AttributeError):
293 return "unknown"
295 def to_ical(self, name, value):
296 """Encodes a named value from a primitive python type to an icalendar
297 encoded string.
298 """
299 type_class = self.for_property(name)
300 return type_class(value).to_ical()
302 def from_ical(self, name, value):
303 """Decodes a named property or parameter value from an icalendar
304 encoded string to a primitive python type.
305 """
306 type_class = self.for_property(name)
307 return type_class.from_ical(value)
310__all__ = ["TypesFactory"]