o .j0@sdZddlmZddlmZmZmZddlmZmZddl m Z m Z m Z m Z mZmZmZmZmZmZmZmZmZmZddlmZddlmZerRddlZdd lmZGd d d eZd gZ dS) z:rfc:`5545` VALARM component.) annotations)datedatetime timedelta) TYPE_CHECKING NamedTuple)CONCEPTS_TYPE_SETTERLINKS_TYPE_SETTERRELATED_TO_TYPE_SETTERattendees_propertycreate_single_propertydescription_propertyproperty_del_durationproperty_get_durationproperty_set_durationsingle_int_propertysingle_string_propertysingle_utc_propertysummary_property uid_property) Component) get_exampleN) vCalAddresscseZdZdZdZdZdZdZdZe ddd Z e e e ed Zed d Zed deefeeBdBdZe d2ddZejd3ddZGdddeZe ddZedejdZeZe Z!e"Z#e$        d4d5fd,d- Z%e$d6d7d0d1Z&Z'S)8Alarma A "VALARM" calendar component is a grouping of component properties that defines an alarm or reminder for an event or a to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do. Example: The following example creates an alarm which uses an audio file from an FTP server. .. code-block:: pycon >>> from icalendar import Alarm >>> alarm = Alarm.example() >>> print(alarm.to_ical().decode()) BEGIN:VALARM ACTION:AUDIO ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/sounds/bell-01.aud DURATION:PT15M REPEAT:4 TRIGGER;VALUE=DATE-TIME:19970317T133000Z END:VALARM VALARM)ACTIONTRIGGER) ATTACHr DESCRIPTIONSUMMARYrDURATIONREPEATUID PROXIMITY ACKNOWLEDGED))r r!)rATTENDEE)r%rz RELATED-TOr!rasThe number of additional times the alarm is triggered after the initial trigger. Defaults to ``0``, meaning the alarm fires once. To repeat the alarm, set both :attr:`REPEAT` and :attr:`DURATION`. The :attr:`DURATION` sets the gap between repetitions. ``REPEAT`` is the count of *additional* triggers, so a ``REPEAT`` of ``2`` produces three alarms in total (the initial trigger plus two repeats). Conforming with :rfc:`5545#section-3.8.6.2`, this property can appear once in an :class:`~icalendar.cal.alarm.Alarm` component and must be paired with :attr:`DURATION`. Example: Build an alarm that fires once and then repeats twice at five-minute intervals. .. code-block:: pycon >>> from datetime import timedelta >>> from icalendar import Alarm >>> alarm = Alarm() >>> alarm.TRIGGER = timedelta(minutes=-15) >>> alarm.DURATION = timedelta(minutes=5) >>> alarm.REPEAT = 2 >>> alarm.REPEAT 2 aThe delay between repeated triggers of a repeating alarm. Returns a :class:`datetime.timedelta` or ``None`` when the alarm has no :attr:`DURATION` set. Setting this attribute accepts a :class:`~datetime.timedelta`; deleting it removes the property from the component. :attr:`DURATION` is meaningful only for repeating alarms and must be paired with :attr:`REPEAT`. The two together produce ``REPEAT`` additional triggers, each spaced by ``DURATION`` after the initial trigger. Conforming with :rfc:`5545#section-3.8.2.5`, the ``DURATION`` property can appear once in an :class:`~icalendar.cal.alarm.Alarm` component. Example: Pair :attr:`DURATION` with :attr:`REPEAT` to produce three triggers spaced ten minutes apart. .. code-block:: pycon >>> from datetime import timedelta >>> from icalendar import Alarm >>> alarm = Alarm() >>> alarm.TRIGGER = timedelta(minutes=-30) >>> alarm.DURATION = timedelta(minutes=10) >>> alarm.REPEAT = 2 >>> alarm.DURATION datetime.timedelta(seconds=600) r$aThis is defined in RFC 9074: Purpose: This property specifies the UTC date and time at which the corresponding alarm was last sent or acknowledged. This property is used to specify when an alarm was last sent or acknowledged. This allows clients to determine when a pending alarm has been acknowledged by a calendar user so that any alerts can be dismissed across multiple devices. It also allows clients to track repeating alarms or alarms on recurring events or to-dos to ensure that the right number of missed alarms can be tracked. Clients SHOULD set this property to the current date-time value in UTC when a calendar user acknowledges a pending alarm. Certain kinds of alarms, such as email-based alerts, might not provide feedback as to when the calendar user sees them. For those kinds of alarms, the client SHOULD set this property when the alarm is triggered and the action is successfully carried out. When an alarm is triggered on a client, clients can check to see if an "ACKNOWLEDGED" property is present. If it is, and the value of that property is greater than or equal to the computed trigger time for the alarm, then the client SHOULD NOT trigger the alarm. Similarly, if an alarm has been triggered and an "alert" has been presented to a calendar user, clients can monitor the iCalendar data to determine whether an "ACKNOWLEDGED" property is added or changed in the alarm component. If the value of any "ACKNOWLEDGED" property in the alarm changes and is greater than or equal to the trigger time of the alarm, then clients SHOULD dismiss or cancel any "alert" presented to the calendar user. rdtNa2Purpose: This property specifies when an alarm will trigger. Value Type: The default value type is DURATION. The value type can be set to a DATE-TIME value type, in which case the value MUST specify a UTC-formatted DATE-TIME value. Either a positive or negative duration may be specified for the "TRIGGER" property. An alarm with a positive duration is triggered after the associated start or end of the event or to-do. An alarm with a negative duration is triggered before the associated start or end of the event or to-do.returnstrcCs$|d}|dur dS|jddS)aThe RELATED parameter of the TRIGGER property. Values are either "START" (default) or "END". A value of START will set the alarm to trigger off the start of the associated event or to-do. A value of END will set the alarm to trigger off the end of the associated event or to-do. In this example, we create an alarm that triggers two hours after the end of its parent component: >>> from icalendar import Alarm >>> from datetime import timedelta >>> alarm = Alarm() >>> alarm.TRIGGER = timedelta(hours=2) >>> alarm.TRIGGER_RELATED = "END" rNSTARTRELATED)getparams)selftriggerr/H/home/thesage/.local/lib/python3.10/site-packages/icalendar/cal/alarm.pyTRIGGER_RELATEDs zAlarm.TRIGGER_RELATEDvaluecCs(|d}|dur td||jd<dS)zSet "START" or "END".rNz>> from icalendar import Alarm >>> from datetime import timedelta >>> alarm = Alarm() >>> alarm.TRIGGER = timedelta(hours=-4) # trigger 4 hours before START >>> alarm.DURATION = timedelta(hours=1) # after 1 hour trigger again >>> alarm.REPEAT = 2 # trigger 2 more times >>> alarm.triggers.start == (timedelta(hours=-4), timedelta(hours=-3), timedelta(hours=-2)) True >>> alarm.triggers.end () >>> alarm.triggers.absolute () Nr))r4r5r6) r isinstancerappendr1r ranger!r<tuple)r-r4r5r6r.addduration_r/r/r0triggerss(     zAlarm.triggersr"z X-ALARMUID attendeeslist[vCalAddress] | Noneconceptsr description str | Nonelinksr refidslist[str] | str | None related_tor summaryuidstr | uuid.UUID | Nonec  s0tj||||d} || _|| _|| _|| _| S)aCreate a new alarm with all required properties. This creates a new Alarm in accordance with :rfc:`5545`. Parameters: attendees: The :attr:`attendees` of the alarm. concepts: The :attr:`~icalendar.Component.concepts` of the alarm. description: The :attr:`description` of the alarm. links: The :attr:`~icalendar.Component.links` of the alarm. refids: :attr:`~icalendar.Component.refids` of the alarm. related_to: :attr:`~icalendar.Component.related_to` of the alarm. summary: The :attr:`summary` of the alarm. uid: The :attr:`uid` of the alarm. Returns: :class:`Alarm` Raises: ~error.InvalidCalendar: If the content is not valid according to :rfc:`5545`. .. warning:: As time progresses, we will be stricter with the validation. )rKrNrLrH)supernewrOrIrPrF) clsrFrHrIrKrLrNrOrPalarm __class__r/r0rS3s$z Alarm.newexamplenamecCs|td|S)z-Return the alarm example with the given name.alarms) from_icalr)rTrYr/r/r0rXcsz Alarm.example)r'r()r2r()NNNNNNNN)rFrGrHrrIrJrKr rLrMrNr rOrJrPrQ)rX)rYr(r'r)(r7r8r9r:rYrequired singletons inclusivemultiplerr!propertyrrrr rr$r rrrr1setterrr<rErrrPrrOr rIr rF classmethodrSrX __classcell__r/r/rVr0r!sp   $     +/r)!r: __future__rrrrtypingrricalendar.attrrr r r r r rrrrrrrricalendar.cal.componentricalendar.cal.examplesruuidicalendar.proprr__all__r/r/r/r0s @    J