i5dZddlmZddlmZmZmZddlmZddl m Z ddl m Z ddl mZmZmZmZddlmZdd lmZmZmZerdd lmZdd lmZdd lmZe e zZGd dZGddZgdZdS)aQCompute the times and states of alarms. This takes different calendar software into account and the RFC 9074 (Alarm Extension). - RFC 9074 defines an ACKNOWLEDGED property in the VALARM. - Outlook does not export VALARM information. - Google Calendar uses the DTSTAMP to acknowledge the alarms. - Thunderbird snoozes the alarms with a X-MOZ-SNOOZE-TIME attribute in the event. - Thunderbird acknowledges the alarms with a X-MOZ-LASTACK attribute in the event. - Etar deletes alarms that are acknowledged. - Nextcloud's Webinterface does not do anything with the alarms when the time passes. ) annotations)date timedeltatzinfo) TYPE_CHECKING)Event)Todo)ComponentEndMissingComponentStartMissingIncompleteAlarmInformationLocalTimezoneMissing)tzp)is_datenormalize_pytz to_datetime) Generator)datetime)AlarmceZdZdZ ddd ZeddZeddZeddZddZ eddZ dS) AlarmTimezRepresents a computed alarm occurrence with its timing and state. An AlarmTime instance combines an alarm component with its resolved trigger time and additional state information, such as acknowledgment and snoozing. Nalarmrtriggerracknowledged_untildatetime | None snoozed_untilparent Parent | NonecL||_||_||_||_||_dS)aCreate an instance of ``AlarmTime`` with any of its parameters. Parameters: alarm: The underlying alarm component. trigger: A date or datetime at which to trigger the alarm. acknowledged_until: Optional datetime in UTC until which the alarm has been acknowledged. snoozed_until: Optional datetime in UTC until which the alarm has been snoozed. parent: Optional parent component to which the alarm refers. N)_alarm_parent_trigger _last_ack _snooze_until)selfrrrrrs K/root/projects/butler/venv/lib/python3.11/site-packages/icalendar/alarms.py__init__zAlarmTime.__init__/s.&   +*returnch|jj}||jS|j|St||jS)zThe time in UTC at which this alarm was last acknowledged. If the alarm was not acknowledged (dismissed), then this is None. )r ACKNOWLEDGEDr"max)r$acks r% acknowledgedzAlarmTime.acknowledgedHs: j% ;> ! > !J3'''r'c|jS)zThe alarm component.)rr$s r%rzAlarmTime.alarmUs {r'c|jS)zThe component that contains the alarm. This is ``None`` if you didn't use :meth:`Alarms.add_component() `. )r r/s r%rzAlarmTime.parentZs |r'boolc|j}|sdS|j |j|krdS|j}|jt d||kS)aWhether this alarm is active (``True``) or acknowledged (``False``). For example, in some calendar software, this is ``True`` until the user views the alarm message and dismisses it. Alarms can be in local time without a timezone. To calculate whether the alarm has occurred, the time must include timezone information. Raises: LocalTimezoneMissing: If a timezone is required but not given. TNzdA local timezone is required to check if the alarm is still active. Use Alarms.set_local_timezone().)r-r#rrr )r$r-rs r% is_activezAlarmTime.is_activecsg(  4   )d.@<.O.O4, > !&3 %%r'rcL|j|j|jkr|jS|jS)zThe time at which the alarm triggers. If the alarm has been snoozed, this may differ from the TRIGGER property. )r#r!r/s r%rzAlarmTime.trigger|s-   )d.@4=.P.P% %}r')NNN) rrrrrrrrrr)r(r)r(r)r(r)r(r1)r(r) __name__ __module__ __qualname____doc__r&propertyr-rrr3rr'r%rr's/3)- $ +++++2 ( ( (X (XX&&&&2Xr'rceZdZdZd)d*dZd+dZd,d Zd-dZd.dZd.dZ d/dZ d0dZ d0dZ d1dZ ed2dZd3d"Zd4d$Zd2d%Zd2d&Zd2d'Zed2d(ZdS)5AlarmsaCompute the times and states of alarms. This is an example using RFC 9074. One alarm is 30 minutes before the event and acknowledged. Another alarm is 15 minutes before the event and still active. >>> from icalendar import Event, Alarms >>> event = Event.from_ical( ... '''BEGIN:VEVENT ... CREATED:20210301T151004Z ... UID:AC67C078-CED3-4BF5-9726-832C3749F627 ... DTSTAMP:20210301T151004Z ... DTSTART;TZID=America/New_York:20210302T103000 ... DTEND;TZID=America/New_York:20210302T113000 ... SUMMARY:Meeting ... BEGIN:VALARM ... UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 ... TRIGGER:-PT30M ... ACKNOWLEDGED:20210302T150004Z ... DESCRIPTION:Event reminder ... ACTION:DISPLAY ... END:VALARM ... BEGIN:VALARM ... UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 ... TRIGGER:-PT15M ... DESCRIPTION:Event reminder ... ACTION:DISPLAY ... END:VALARM ... END:VEVENT ... ''') >>> alarms = Alarms(event) >>> len(alarms.times) # all alarms including those acknowledged 2 >>> len(alarms.active) # the alarms that are not acknowledged, yet 1 >>> alarms.active[0].trigger # this alarm triggers 15 minutes before 10:30 datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York')) RFC 9074 specifies that alarms can also be triggered by proximity. This is not implemented yet. N componentAlarm | Event | Todo | Nonecg|_g|_g|_d|_d|_d|_d|_d|_d|_|| |dSdS)zStart computing alarm times.N) _absolute_alarms _start_alarms _end_alarms_start_endr r"r# _local_tzinfo add_component)r$r=s r%r&zAlarms.__init__sn-/*,(*#' !% &* *..2,0    y ) ) ) ) ) ! r'Alarm | Parentct|ttfr||||j||j|r5| |j | |j n| |j |dD]}||dS)zAdd a component. If this is an alarm, it is added. Events and Todos are added as a parent and all their alarms are added, too. VALARMN) isinstancerr set_parent set_startstartset_endendis_thunderbirdacknowledge_until X_MOZ_LASTACK snooze_untilX_MOZ_SNOOZE_TIMEDTSTAMPwalk add_alarm)r$r=rs r%rFzAlarms.add_components i% / / : OOI & & & NN9? + + + LL ' ' ''')) :&&y'>???!!)"=>>>>&&y'8999^^H-- " "E NN5 ! ! ! ! " "r'rParentcR|j|j|urtd||_dS)z{Set the parent of all the alarms. If you would like to collect alarms from a component, use add_component Nz7You can only set one parent for this alarm calculation.)r ValueError)r$rs r%rKzAlarms.set_parents2 < # F(B(BVWW W r'rrr(Nonec|j}|dSt|tr|j|dS|jdkr|j|dS|j|dS)z!Optional: Add an alarm component.NSTART)TRIGGERrJrr@appendTRIGGER_RELATEDrArBr$rrs r%rWzAlarms.add_alarms- ? F gt $ $ +  ! ( ( / / / / /  "g - -   % %e , , , , ,   # #E * * * * *r'dt date | Nonec||_dS)zSet the start of the component. If you have only absolute alarms, this is not required. If you have alarms relative to the start of a compoment, set the start here. N)rCr$rbs r%rLzAlarms.set_starts  r'c||_dS)zSet the end of the component. If you have only absolute alarms, this is not required. If you have alarms relative to the end of a compoment, set the end here. N)rDres r%rNzAlarms.set_ends  r'rtdrct|r|jdkr||zSt|}t||zS)zAdd a timedelta to a datetime.r)rsecondsrr)r$rbrgs r%_addz Alarms._addsA 2;; !zQBwRBb2g&&&r'c@|tj|nd|_dS)aThe time in UTC when all the alarms of this component were acknowledged. Only the last call counts. Since RFC 9074 (Alarm Extension) was created later, calendar implementations differ in how they acknowledge alarms. For example, Thunderbird and Google Calendar store the last time an event has been acknowledged because of an alarm. All alarms that happen before this time count as acknowledged. N)r localize_utcr"res r%rQzAlarms.acknowledge_untils#24)"---Tr'c@|tj|nd|_dS)zThis is the time in UTC when all the alarms of this component were snoozed. Only the last call counts. The alarms are supposed to turn up again at dt when they are not acknowledged but snoozed. N)rrlr#res r%rSzAlarms.snooze_untils&68^S-b111r'rtzinfo | str | Nonecft|trtj|n||_dS)auSet the local timezone. Events are sometimes in local time. In order to compute the exact time of the alarm, some alarms without timezone are considered local. Some computations work without setting this, others don't. If they need this information, expect a LocalTimezoneMissing exception somewhere down the line. N)rJstrrtimezonerE)r$rs r%set_local_timezonezAlarms.set_local_timezones26@5L5LXS\&111RXr'list[AlarmTime]c~||z|zS)aPCompute and return the times of the alarms given. If the information for calculation is incomplete, this will raise a IncompleteAlarmInformation exception. Please make sure to set all the required parameters before calculating. If you forget to set the acknowledged times, that is not problem. )_get_end_alarm_times_get_start_alarm_times_get_absolute_alarm_timesr/s r%timesz Alarms.times&s@  % % ' '))++ ,,,.. / r'firstrGenerator[datetime]c#K|V|j}|j}|r3|r3td|dzD]!}||||zVdSdSdS)z8The times when the alarm is triggered relative to start.N)REPEATDURATIONrangerj)r$ryrrepeatdurationis r%_repeatzAlarms._repeat6s >  5h 51fqj)) 5 5iix!|444444 5 5 5 5 5 5r'rct|dd/|j(t||j}t |||j|j|jS)z4Create an alarm time with the additional attributes.rN)r)getattrrErreplacerr"r#r ras r% _alarm_timezAlarms._alarm_time?s^ 7Hd + + 38J8V$W__D    r'c*fdjDS)z&Return a list of absolute alarm times.cxg|]6}|j|D]}||7Sr:)rr^r.0rrr$s r% z4Alarms._get_absolute_alarm_times..Is`   << u==     UG , ,    r')r@r/s`r%rwz Alarms._get_absolute_alarm_timesGs1    .    r'cdjjrtdfdjDS)DReturn a list of alarm times relative to the start of the component.NzXUse Alarms.set_start because at least one alarm is relative to the start of a component.cg|]O}j|j|D]}||PSr:)rrjrCr^rrs r%rz1Alarms._get_start_alarm_times..Vsp   << $+u}(M(MuUU     UG , ,    r')rCrAr r/s`r%rvzAlarms._get_start_alarm_timesOsX ; 4#5 '(     +    r'cdjjrtdfdjDS)rNzTUse Alarms.set_end because at least one alarm is relative to the end of a component.cg|]O}j|j|D]}||PSr:)rrjrDr^rrs r%rz/Alarms._get_end_alarm_times..csp   << $)U](K(KUSS     UG , ,    r')rDrBr r/s`r%ruzAlarms._get_end_alarm_times\sX 9 !1 %"     )    r'c$d|jDS)aSThe alarm times that are still active and not acknowledged. This considers snoozed alarms. Alarms can be in local time (without a timezone). To calculate if the alarm really happened, we need it to be in a timezone. If a timezone is required but not given, we throw an IncompleteAlarmInformation. c:g|]}||Sr:)r3)r alarm_times r%rz!Alarms.active..ss)RRRz:;O;O;Q;QR RRRr')rxr/s r%activez Alarms.activeisSRTZRRRRr')N)r=r>)r=rG)rrX)rrr(r[)rbrc)rbrrgr)rbrcr(r[)rrn)r(rs)ryrrrr(rz)rrrr)r5r6r7r8r&rFrKrWrLrNrjrQrSrrr9rxrrrwrvrurr:r'r%r<r<s((T * * * * *""""( + + + +'''' J J J JNNNN Y Y Y Y    X  5555                   S S SX S S Sr'r<)rr<r r r N) r8 __future__rrrrrtypingricalendar.cal.eventricalendar.cal.todor icalendar.errorr r r r icalendar.timezonericalendar.toolsrrrcollections.abcricalendar.cal.alarmrrXrr<__all__r:r'r%rs  #""""",,,,,,,,,, %%%%%%###### #"""""@@@@@@@@@@*))))))!!!!!!)))))) ]]]]]]]]@lSlSlSlSlSlSlSlS^   r'