Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/icalendar/enums.py: 93%
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"""Enumerations for different types in the RFCs."""
3from __future__ import annotations
5from enum import Enum as _Enum
6from typing import TYPE_CHECKING, TypeVar, overload
8if TYPE_CHECKING:
9 from icalendar.compatibility import Self
11T = TypeVar("T")
14class Enum(_Enum):
15 """Enum class that can be pickled."""
17 def __reduce_ex__(self, _p):
18 """For pickling."""
19 return self.__class__, (self._value_,)
22class StrEnum(str, Enum):
23 """Enum for strings."""
25 _value_: str
27 def __str__(self) -> str:
28 """Convert to a string.
30 This is needed when we set the value directly in components.
31 """
32 return self.value
34 @overload
35 @classmethod
36 def get(cls, value: str) -> Self | None: ...
38 @overload
39 @classmethod
40 def get(cls, value: str, default: T) -> Self | T: ...
42 @classmethod
43 def get(cls, value: str, default: T | None = None) -> Self | T | None:
44 """Return the member with the given value, or a default.
46 Unlike calling the enum directly, as in ``PARTSTAT("no-value")``, it does
47 not raise a :class:`ValueError` for an unknown value. The lookup is
48 case-insensitive.
50 Parameters:
51 value: Required. Value to look up.
52 default: Optional value to return in case ``value`` is not found.
54 Returns:
55 The member with that value, or ``default`` if there is none.
57 Example:
58 This example shows how to use this method.
60 .. code-block:: pycon
62 >>> from icalendar import PARTSTAT
63 >>> PARTSTAT.get("ACCEPTED")
64 <PARTSTAT.ACCEPTED: 'ACCEPTED'>
65 >>> PARTSTAT.get("accepted")
66 <PARTSTAT.ACCEPTED: 'ACCEPTED'>
67 >>> print(PARTSTAT.get("invalid-value"))
68 None
69 >>> print(PARTSTAT.get("invalid-value", "No value given"))
70 No value given
71 >>> print(PARTSTAT.get("ACCEPTED", "No value given"))
72 ACCEPTED
74 """
75 try:
76 return cls(value.upper())
77 except ValueError:
78 return default
81class PARTSTAT(StrEnum):
82 """Enum for PARTSTAT from :rfc:`5545`.
84 Values:
85 ``NEEDS_ACTION``,
86 ``ACCEPTED``,
87 ``DECLINED``,
88 ``TENTATIVE``,
89 ``DELEGATED``,
90 ``COMPLETED``,
91 ``IN_PROCESS``
93 Purpose:
94 To specify the participation status for the calendar user
95 specified by the property.
97 Description:
98 This parameter can be specified on properties with a
99 CAL-ADDRESS value type. The parameter identifies the
100 participation status for the calendar user specified by the
101 property value. The parameter values differ depending on whether
102 they are associated with a group-scheduled "VEVENT", "VTODO", or
103 "VJOURNAL". The values MUST match one of the values allowed for
104 the given calendar component. If not specified on a property that
105 allows this parameter, the default value is NEEDS-ACTION.
106 Applications MUST treat x-name and iana-token values they don't
107 recognize the same way as they would the NEEDS-ACTION value.
108 """
110 NEEDS_ACTION = "NEEDS-ACTION"
111 ACCEPTED = "ACCEPTED"
112 DECLINED = "DECLINED"
113 TENTATIVE = "TENTATIVE"
114 DELEGATED = "DELEGATED"
115 COMPLETED = "COMPLETED"
116 IN_PROCESS = "IN-PROCESS"
119class STATUS(StrEnum):
120 """Enum for STATUS from :rfc:`5545`.
122 Values for :class:`icalendar.cal.event.Event`:
123 ``CONFIRMED``,
124 ``TENTATIVE``,
125 ``CANCELLED``
127 Values for :class:`icalendar.cal.todo.Todo`:
128 ``NEEDS_ACTION``,
129 ``COMPLETED``,
130 ``IN_PROCESS``,
131 ``CANCELLED``
133 Values for :class:`icalendar.cal.journal.Journal`:
134 ``DRAFT``,
135 ``FINAL``,
136 ``CANCELLED``
138 Description:
139 In a group-scheduled calendar component, the property
140 is used by the "Organizer" to provide a confirmation of the event
141 to the "Attendees". For example in a "VEVENT" calendar component,
142 the "Organizer" can indicate that a meeting is tentative,
143 confirmed, or cancelled. In a "VTODO" calendar component, the
144 "Organizer" can indicate that an action item needs action, is
145 completed, is in process or being worked on, or has been
146 cancelled. In a "VJOURNAL" calendar component, the "Organizer"
147 can indicate that a journal entry is draft, final, or has been
148 cancelled or removed.
149 """
151 # Event
152 TENTATIVE = "TENTATIVE"
153 CONFIRMED = "CONFIRMED"
154 CANCELLED = "CANCELLED"
156 # VTodo
157 NEEDS_ACTION = "NEEDS-ACTION"
158 COMPLETED = "COMPLETED"
159 IN_PROCESS = "IN-PROCESS"
160 # CANCELLED
162 # Journal
163 DRAFT = "DRAFT"
164 FINAL = "FINAL"
165 # CANCELLED
168class FBTYPE(StrEnum):
169 """Enum for FBTYPE from :rfc:`5545`.
171 Values:
172 ``FREE``,
173 ``BUSY``,
174 ``BUSY_UNAVAILABLE``,
175 ``BUSY_TENTATIVE``
177 See also :class:`~icalendar.enums.BUSYTYPE`.
179 Purpose:
180 To specify the free or busy time type.
182 Description:
183 This parameter specifies the free or busy time type.
184 The value FREE indicates that the time interval is free for
185 scheduling. The value BUSY indicates that the time interval is
186 busy because one or more events have been scheduled for that
187 interval. The value BUSY-UNAVAILABLE indicates that the time
188 interval is busy and that the interval can not be scheduled. The
189 value BUSY-TENTATIVE indicates that the time interval is busy
190 because one or more events have been tentatively scheduled for
191 that interval. If not specified on a property that allows this
192 parameter, the default is BUSY. Applications MUST treat x-name
193 and iana-token values they don't recognize the same way as they
194 would the BUSY value.
195 """
197 FREE = "FREE"
198 BUSY = "BUSY"
199 BUSY_UNAVAILABLE = "BUSY-UNAVAILABLE"
200 BUSY_TENTATIVE = "BUSY-TENTATIVE"
203class CUTYPE(StrEnum):
204 """Enum for CTYPE from :rfc:`5545`.
206 Values:
207 ``INDIVIDUAL``,
208 ``GROUP``,
209 ``RESOURCE``,
210 ``ROOM``,
211 ``UNKNOWN``
213 Purpose:
214 To identify the type of calendar user specified by the property.
216 Description:
217 This parameter can be specified on properties with a
218 CAL-ADDRESS value type. The parameter identifies the type of
219 calendar user specified by the property. If not specified on a
220 property that allows this parameter, the default is INDIVIDUAL.
221 Applications MUST treat x-name and iana-token values they don't
222 recognize the same way as they would the UNKNOWN value.
223 """
225 INDIVIDUAL = "INDIVIDUAL"
226 GROUP = "GROUP"
227 RESOURCE = "RESOURCE"
228 ROOM = "ROOM"
229 UNKNOWN = "UNKNOWN"
232class RELTYPE(StrEnum):
233 """Enum for RELTYPE from :rfc:`5545`.
235 Values:
236 ``PARENT``,
237 ``CHILD``,
238 ``SIBLING``,
239 ``FINISHTOSTART``,
240 ``FINISHTOFINISH``,
241 ``STARTTOFINISH``,
242 ``STARTTOSTART``,
243 ``FIRST``,
244 ``NEXT``,
245 ``DEPENDS-ON``,
246 ``REFID``,
247 ``CONCEPT``
249 Purpose:
250 To specify the type of hierarchical relationship associated
251 with the calendar component specified by the property.
253 Description:
254 This parameter can be specified on a property that
255 references another related calendar. The parameter specifies the
256 hierarchical relationship type of the calendar component
257 referenced by the property. The parameter value can be PARENT, to
258 indicate that the referenced calendar component is a superior of
259 calendar component; CHILD to indicate that the referenced calendar
260 component is a subordinate of the calendar component; or SIBLING
261 to indicate that the referenced calendar component is a peer of
262 the calendar component. If this parameter is not specified on an
263 allowable property, the default relationship type is PARENT.
264 Applications MUST treat x-name and iana-token values they don't
265 recognize the same way as they would the PARENT value.
267 New Temporal RELTYPE Parameter Values (:rfc:`9253`):
268 RELTYPE=FINISHTOSTART
269 Task-B cannot start until Task-A finishes.
270 For example, when painting is complete, carpet laying can begin.
271 RELTYPE=FINISHTOFINISH
272 Task-B can only be completed after Task-A is finished.
273 The related tasks may run in parallel before completion.
274 RELTYPE=STARTTOFINISH
275 The start of Task-A (which occurs after Task-B) controls the
276 finish of Task-B. For example, ticket sales (Task-B) end
277 after the game starts (Task-A).
278 RELTYPE=STARTTOSTART
279 The start of Task-A triggers the start of Task-B,
280 that is, Task-B can start anytime after Task-A starts.
282 Additional New RELTYPE Parameter Values (:rfc:`9253`):
283 RELTYPE=FIRST
284 This indicates that the referenced calendar component is
285 the first in a series the referencing calendar component
286 is part of.
287 RELTYPE=NEXT
288 This indicates that the referenced calendar component
289 is the next in a series the referencing calendar component
290 is part of.
291 RELTYPE=DEPENDS-ON
292 This indicates that the current calendar component
293 depends on the referenced calendar component in some manner.
294 For example, a task may be blocked waiting on the other,
295 referenced, task.
296 RELTYPE=REFID
297 This establishes a reference from the current component to
298 components with a REFID property that matches the value given
299 in the associated RELATED-TO property.
300 RELTYPE=CONCEPT
301 This establishes a reference from the current component to
302 components with a CONCEPT property that matches the value
303 given in the associated RELATED-TO property.
305 Note that the relationship types of PARENT, CHILD, and SIBLING
306 establish a hierarchical relationship. The new types of FIRST
307 and NEXT are an ordering relationship.
309 Examples:
310 The following is an example from :rfc:`5545`:
312 .. code-block:: ics
314 RELATED-TO;RELTYPE=SIBLING:19960401-080045-4000F192713@
315 example.com
317 Usage inside of RELATED-TO according to :rfc:`9253`:
319 .. code-block:: ics
321 RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH:
322 https://example.com/caldav/user/jb/cal/
323 19960401-080045-4000F192713.ics
324 """
326 PARENT = "PARENT"
327 CHILD = "CHILD"
328 SIBLING = "SIBLING"
329 FINISHTOSTART = "FINISHTOSTART"
330 FINISHTOFINISH = "FINISHTOFINISH"
331 STARTTOFINISH = "STARTTOFINISH"
332 STARTTOSTART = "STARTTOSTART"
333 FIRST = "FIRST"
334 NEXT = "NEXT"
335 DEPENDS_ON = "DEPENDS-ON"
336 REFID = "REFID"
337 CONCEPT = "CONCEPT"
340class RANGE(StrEnum):
341 """Enum for RANGE from :rfc:`5545`.
343 Values:
344 ``THISANDFUTURE``,
345 ``THISANDPRIOR`` (deprecated)
347 Purpose:
348 To specify the effective range of recurrence instances from
349 the instance specified by the recurrence identifier specified by
350 the property.
352 Description:
353 This parameter can be specified on a property that
354 specifies a recurrence identifier. The parameter specifies the
355 effective range of recurrence instances that is specified by the
356 property. The effective range is from the recurrence identifier
357 specified by the property. If this parameter is not specified on
358 an allowed property, then the default range is the single instance
359 specified by the recurrence identifier value of the property. The
360 parameter value can only be "THISANDFUTURE" to indicate a range
361 defined by the recurrence identifier and all subsequent instances.
362 The value "THISANDPRIOR" is deprecated by this revision of
363 iCalendar and MUST NOT be generated by applications.
364 """
366 THISANDFUTURE = "THISANDFUTURE"
367 THISANDPRIOR = "THISANDPRIOR" # deprecated
370class RELATED(StrEnum):
371 """Enum for RELATED from :rfc:`5545`.
373 Values:
374 ``START``,
375 ``END``
377 Purpose:
378 To specify the relationship of the alarm trigger with
379 respect to the start or end of the calendar component.
381 Description:
382 This parameter can be specified on properties that
383 specify an alarm trigger with a "DURATION" value type. The
384 parameter specifies whether the alarm will trigger relative to the
385 start or end of the calendar component. The parameter value START
386 will set the alarm to trigger off the start of the calendar
387 component; the parameter value END will set the alarm to trigger
388 off the end of the calendar component. If the parameter is not
389 specified on an allowable property, then the default is START.
390 """
392 START = "START"
393 END = "END"
396class ROLE(StrEnum):
397 """Enum for ROLE from :rfc:`5545`.
399 Values:
400 ``CHAIR``,
401 ``REQ_PARTICIPANT``,
402 ``OPT_PARTICIPANT``,
403 ``NON_PARTICIPANT``
405 Purpose:
406 To specify the participation role for the calendar user
407 specified by the property.
409 Description:
410 This parameter can be specified on properties with a
411 CAL-ADDRESS value type. The parameter specifies the participation
412 role for the calendar user specified by the property in the group
413 schedule calendar component. If not specified on a property that
414 allows this parameter, the default value is REQ-PARTICIPANT.
415 Applications MUST treat x-name and iana-token values they don't
416 recognize the same way as they would the REQ-PARTICIPANT value.
418 """
420 CHAIR = "CHAIR"
421 REQ_PARTICIPANT = "REQ-PARTICIPANT"
422 OPT_PARTICIPANT = "OPT-PARTICIPANT"
423 NON_PARTICIPANT = "NON-PARTICIPANT"
426class VALUE(StrEnum):
427 """VALUE datatypes as defined in :rfc:`5545`.
429 Attributes: ``BINARY``, ``BOOLEAN``, ``CAL_ADDRESS``, ``DATE``, ``DATE_TIME``,
430 ``DURATION``, ``FLOAT``, ``INTEGER``, ``PERIOD``, ``RECUR``, ``TEXT``, ``TIME``,
431 ``URI``, ``UTC_OFFSET``
433 Description:
434 This parameter specifies the value type and format of
435 the property value. The property values MUST be of a single value
436 type. For example, a "RDATE" property cannot have a combination
437 of DATE-TIME and TIME value types.
439 If the property's value is the default value type, then this
440 parameter need not be specified. However, if the property's
441 default value type is overridden by some other allowable value
442 type, then this parameter MUST be specified.
444 Applications MUST preserve the value data for x-name and iana-
445 token values that they don't recognize without attempting to
446 interpret or parse the value data.
448 """
450 BINARY = "BINARY"
451 BOOLEAN = "BOOLEAN"
452 CAL_ADDRESS = "CAL-ADDRESS"
453 DATE = "DATE"
454 DATE_TIME = "DATE-TIME"
455 DURATION = "DURATION"
456 FLOAT = "FLOAT"
457 INTEGER = "INTEGER"
458 PERIOD = "PERIOD"
459 RECUR = "RECUR"
460 TEXT = "TEXT"
461 TIME = "TIME"
462 URI = "URI"
463 UTC_OFFSET = "UTC-OFFSET"
466class BUSYTYPE(StrEnum):
467 """Enum for BUSYTYPE from :rfc:`7953`.
469 Values:
470 ``BUSY``,
471 ``BUSY_UNAVAILABLE``,
472 ``BUSY_TENTATIVE``
474 Description:
475 This property is used to specify the default busy time
476 type. The values correspond to those used by the
477 :class:`~icalendar.enums.FBTYPE`
478 parameter used on a "FREEBUSY" property, with the exception that
479 the "FREE" value is not used in this property. If not specified
480 on a component that allows this property, the default is "BUSY-
481 UNAVAILABLE".
483 Example:
484 The following is an example of this property:
486 .. code-block:: ics
488 BUSYTYPE:BUSY
489 """
491 BUSY = "BUSY"
492 BUSY_UNAVAILABLE = "BUSY-UNAVAILABLE"
493 BUSY_TENTATIVE = "BUSY-TENTATIVE"
496class CLASS(StrEnum):
497 """Enum for CLASS from :rfc:`5545`.
499 Values:
500 ``PUBLIC``,
501 ``PRIVATE``,
502 ``CONFIDENTIAL``
504 Description:
505 An access classification is only one component of the
506 general security system within a calendar application. It
507 provides a method of capturing the scope of the access the
508 calendar owner intends for information within an individual
509 calendar entry. The access classification of an individual
510 iCalendar component is useful when measured along with the other
511 security components of a calendar system (e.g., calendar user
512 authentication, authorization, access rights, access role, etc.).
513 Hence, the semantics of the individual access classifications
514 cannot be completely defined by this memo alone. Additionally,
515 due to the "blind" nature of most exchange processes using this
516 memo, these access classifications cannot serve as an enforcement
517 statement for a system receiving an iCalendar object. Rather,
518 they provide a method for capturing the intention of the calendar
519 owner for the access to the calendar component. If not specified
520 in a component that allows this property, the default value is
521 PUBLIC. Applications MUST treat x-name and iana-token values they
522 don't recognize the same way as they would the PRIVATE value.
523 """
525 PUBLIC = "PUBLIC"
526 PRIVATE = "PRIVATE"
527 CONFIDENTIAL = "CONFIDENTIAL"
530class TRANSP(StrEnum):
531 """Enum for TRANSP from :rfc:`5545`.
533 Values:
534 ``OPAQUE``,
535 ``TRANSPARENT``
537 Description:
538 Time Transparency is the characteristic of an event
539 that determines whether it appears to consume time on a calendar.
540 Events that consume actual time for the individual or resource
541 associated with the calendar SHOULD be recorded as OPAQUE,
542 allowing them to be detected by free/busy time searches. Other
543 events, which do not take up the individual's (or resource's) time
544 SHOULD be recorded as TRANSPARENT, making them invisible to free/
545 busy time searches.
546 """
548 OPAQUE = "OPAQUE"
549 TRANSPARENT = "TRANSPARENT"
552__all__ = [
553 "BUSYTYPE",
554 "CLASS",
555 "CUTYPE",
556 "FBTYPE",
557 "PARTSTAT",
558 "RANGE",
559 "RELATED",
560 "RELTYPE",
561 "ROLE",
562 "STATUS",
563 "TRANSP",
564 "VALUE",
565]