From 0799bdac6cd1b24a28d373e1bab36a68a5789fb5 Mon Sep 17 00:00:00 2001 From: Firdous2307 <124298708+Firdous2307@users.noreply.github.com> Date: Sun, 13 Oct 2024 22:12:07 +0100 Subject: [PATCH 1/4] feat: Add RFC 5545 documentation to calendar components and timezone subclasses --- src/icalendar/cal.py | 54 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/src/icalendar/cal.py b/src/icalendar/cal.py index 9ace5d38..1a567dd4 100644 --- a/src/icalendar/cal.py +++ b/src/icalendar/cal.py @@ -549,6 +549,12 @@ def is_datetime(dt: date) -> bool: return isinstance(dt, datetime) class Event(Component): + """ + An "VEVENT" calendar component is a grouping of component + properties that represents a scheduled amount of time on a + calendar. For example, it can be an activity; such as a one-hour + long, department meeting from 8:00 AM to 9:00 AM, tomorrow. + """ name = 'VEVENT' @@ -693,6 +699,13 @@ def end(self, end: date | datetime | None): class Todo(Component): + """ + A "VTODO" calendar component is a grouping of component + properties that represents an action-item or assignment. For + example, it can be used to represent an item of work assigned to + an individual; such as "Prepare for the upcoming conference + seminar on Internet Calendaring". + """ name = 'VTODO' @@ -767,6 +780,12 @@ def duration(self) -> timedelta: return timedelta(0) class FreeBusy(Component): + """ + A "VFREEBUSY" calendar component is a grouping of component + properties that represents either a request for free or busy time + information, a reply to a request for free or busy time + information, or a published set of busy time information. + """ name = 'VFREEBUSY' @@ -779,6 +798,11 @@ class FreeBusy(Component): class Timezone(Component): + """ + A "VTIMEZONE" calendar component is a grouping of component + properties that defines a time zone. It is used to describe the + way in which a time zone changes its offset from UTC over time. + """ name = 'VTIMEZONE' canonical_order = ('TZID',) required = ('TZID',) # it also requires one of components DAYLIGHT and STANDARD @@ -939,13 +963,31 @@ def get_transitions(self) -> Tuple[List[datetime], List[Tuple[timedelta, timedel class TimezoneStandard(Component): + """ + The "STANDARD" sub-component of "VTIMEZONE" defines the standard + time offset from UTC for a time zone. It represents a time zone's + standard time, typically used during winter months in locations + that observe Daylight Saving Time. + """ name = 'STANDARD' + """ + The "STANDARD" sub-component of "VTIMEZONE" defines the standard + time offset from UTC for a time zone. It represents a time zone's + standard time, typically used during winter months in locations + that observe Daylight Saving Time. + """ required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM') singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM',) multiple = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE') class TimezoneDaylight(Component): + """ + The "DAYLIGHT" sub-component of "VTIMEZONE" defines the daylight + saving time offset from UTC for a time zone. It represents a time + zone's daylight saving time, typically used during summer months + in locations that observe Daylight Saving Time. + """ name = 'DAYLIGHT' required = TimezoneStandard.required singletons = TimezoneStandard.singletons @@ -953,6 +995,12 @@ class TimezoneDaylight(Component): class Alarm(Component): + """ + 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. + """ name = 'VALARM' # some properties MAY/MUST/MUST NOT appear depending on ACTION value @@ -966,7 +1014,11 @@ class Alarm(Component): class Calendar(Component): - """This is the base object for an iCalendar file. + """ + The "VCALENDAR" object is a collection of calendar information. + This information can include a variety of components, such as + "VEVENT", "VTODO", "VJOURNAL", "VFREEBUSY", "VTIMEZONE", or any + other type of calendar component. """ name = 'VCALENDAR' canonical_order = ('VERSION', 'PRODID', 'CALSCALE', 'METHOD',) From f146c77e54d798a8f3de6def37b2e9a6fee5559d Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Sat, 26 Oct 2024 09:46:49 +0100 Subject: [PATCH 2/4] log changes --- CHANGES.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.rst b/CHANGES.rst index ced41fc4..46bf2874 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -8,6 +8,7 @@ Minor changes: - Format test code with Ruff. See `Issue 672 `_. - Document the Debian package. See `Issue 701 `_. +- Document component classes with description from :rfc:`5545`. Breaking changes: From 5282438b31b84d9a88b46d5d62200d4674c04f0d Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Sat, 26 Oct 2024 09:51:15 +0100 Subject: [PATCH 3/4] remove duplicate docs --- src/icalendar/cal.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/icalendar/cal.py b/src/icalendar/cal.py index 1a567dd4..caa2f9ad 100644 --- a/src/icalendar/cal.py +++ b/src/icalendar/cal.py @@ -970,12 +970,6 @@ class TimezoneStandard(Component): that observe Daylight Saving Time. """ name = 'STANDARD' - """ - The "STANDARD" sub-component of "VTIMEZONE" defines the standard - time offset from UTC for a time zone. It represents a time zone's - standard time, typically used during winter months in locations - that observe Daylight Saving Time. - """ required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM') singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM',) multiple = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE') From 3e2bca11579966c5b33fd09e632df32f18210677 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Sat, 26 Oct 2024 09:55:36 +0100 Subject: [PATCH 4/4] apply suggestions --- src/icalendar/cal.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/icalendar/cal.py b/src/icalendar/cal.py index caa2f9ad..c9b3cc14 100644 --- a/src/icalendar/cal.py +++ b/src/icalendar/cal.py @@ -550,10 +550,10 @@ def is_datetime(dt: date) -> bool: class Event(Component): """ - An "VEVENT" calendar component is a grouping of component + A "VEVENT" calendar component is a grouping of component properties that represents a scheduled amount of time on a - calendar. For example, it can be an activity; such as a one-hour - long, department meeting from 8:00 AM to 9:00 AM, tomorrow. + calendar. For example, it can be an activity, such as a one-hour + long department meeting from 8:00 AM to 9:00 AM, tomorrow. """ name = 'VEVENT' @@ -701,9 +701,9 @@ def end(self, end: date | datetime | None): class Todo(Component): """ A "VTODO" calendar component is a grouping of component - properties that represents an action-item or assignment. For + properties that represents an action item or assignment. For example, it can be used to represent an item of work assigned to - an individual; such as "Prepare for the upcoming conference + an individual, such as "Prepare for the upcoming conference seminar on Internet Calendaring". """