From 3318014872dae9041ed208aef93972ee9c1b441a Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Thu, 14 May 2026 15:12:30 +0530 Subject: [PATCH 1/3] docs: replace RFC copy-paste docstrings with Pythonic docstrings (#1244) Rewrote RFC-verbatim docstrings for the following properties: alarm.py: - Alarm.ACKNOWLEDGED: replaced RFC 9074 Purpose/Description wall-of-text with a concise summary, Return, Example and See also sections. - Alarm.TRIGGER: replaced RFC 5545 Purpose/Value-Type verbatim with a clear summary, type info, Example and See also. component.py: - Component.DTSTAMP / stamp: replaced 'RFC 5545: Conformance/Description' block with a Pythonic summary, context note, Example and See also. - Component.LAST_MODIFIED: same pattern - Pythonic summary, Example, See also. - Component.CREATED: same pattern - Pythonic summary, Example, See also. calendar.py: - Calendar.calendar_name: removed Property Parameters/Conformance/Description RFC headings; added See also. - Calendar.description: same cleanup. - Calendar.color: removed Property Parameters/Conformance/Description RFC headings; added CSS3 link reference and See also. - Calendar.prodid: replaced Conformance/Description verbatim with Pythonic summary, Example and See also. - Calendar.version: replaced Purpose RFC text with Pythonic summary + Example. - Calendar.calscale: replaced Conformance/Description/Compatibility with Pythonic summary, RFC 7529 note, Example and See also. - Calendar.method: replaced Description RFC block with Pythonic summary, iTIP/RFC 5546 reference, Example and See also. - Calendar.refresh_interval: replaced Conformance/Description headings with Pythonic summary, updated Raises, added Example and See also. --- src/icalendar/cal/alarm.py | 83 ++++++----- src/icalendar/cal/calendar.py | 242 ++++++++++++++++----------------- src/icalendar/cal/component.py | 87 +++++++----- 3 files changed, 220 insertions(+), 192 deletions(-) diff --git a/src/icalendar/cal/alarm.py b/src/icalendar/cal/alarm.py index 102201601..61a043b69 100644 --- a/src/icalendar/cal/alarm.py +++ b/src/icalendar/cal/alarm.py @@ -156,32 +156,29 @@ class Alarm(Component): ACKNOWLEDGED = single_utc_property( "ACKNOWLEDGED", - """This 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. + """The UTC datetime at which this alarm was last sent or acknowledged. + + Defined in :rfc:`9074`. Setting this property allows calendar clients to + dismiss or suppress an alarm across multiple devices. Once set to a value + greater than or equal to the alarm's computed trigger time, conforming clients + will not re-fire the alarm. + + Returns ``None`` when no acknowledgment has been recorded. + + Example: + Mark an alarm as acknowledged at the current time. + + .. code-block:: pycon + + >>> from datetime import timezone, datetime + >>> from icalendar import Alarm + >>> alarm = Alarm() + >>> alarm.ACKNOWLEDGED = datetime(2024, 1, 15, 10, 0, 0, tzinfo=timezone.utc) + >>> alarm.ACKNOWLEDGED + datetime.datetime(2024, 1, 15, 10, 0, tzinfo=datetime.timezone.utc) + + See also: + :attr:`TRIGGER` — the time at which the alarm fires. """, ) @@ -190,17 +187,33 @@ class Alarm(Component): "dt", (datetime, timedelta), timedelta | datetime | None, - """Purpose: This property specifies when an alarm will trigger. + """The time at which this alarm fires, per :rfc:`5545#section-3.8.6.3`. - 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. + The value is either a :class:`~datetime.timedelta` (relative trigger) or a + UTC :class:`~datetime.datetime` (absolute trigger). - 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.""", + A negative :class:`~datetime.timedelta` fires *before* the related + component boundary (start or end); a positive one fires *after* it. + Use :attr:`TRIGGER_RELATED` to choose whether the offset is measured from + the start or the end of the parent event or to-do. + An absolute trigger fires at an exact UTC point in time regardless of the + parent component's dates. + + Example: + Set an alarm to fire 15 minutes before the start of an event. + + .. code-block:: pycon + + >>> from datetime import timedelta + >>> from icalendar import Alarm + >>> alarm = Alarm() + >>> alarm.TRIGGER = timedelta(minutes=-15) + >>> alarm.TRIGGER + datetime.timedelta(seconds=-900) + + See also: + :attr:`TRIGGER_RELATED`, :attr:`DURATION`, :attr:`REPEAT` + """, ) @property diff --git a/src/icalendar/cal/calendar.py b/src/icalendar/cal/calendar.py index e1ec4f049..ab94bafce 100644 --- a/src/icalendar/cal/calendar.py +++ b/src/icalendar/cal/calendar.py @@ -256,30 +256,16 @@ def add_missing_timezones( calendar_name = multi_language_text_property( "NAME", "X-WR-CALNAME", - """This property specifies the name of the calendar. + """The display name of this calendar, per :rfc:`7986#section-5.3`. - This implements :rfc:`7986` ``NAME`` and ``X-WR-CALNAME``. + Implements both the ``NAME`` property (from :rfc:`7986`) and the widely-used + ``X-WR-CALNAME`` extension for broader client compatibility. - Property Parameters: - IANA, non-standard, alternate text - representation, and language property parameters can be specified - on this property. - - Conformance: - This property can be specified multiple times in an - iCalendar object. However, each property MUST represent the name - of the calendar in a different language. - - Description: - This property is used to specify a name of the - iCalendar object that can be used by calendar user agents when - presenting the calendar data to a user. Whilst a calendar only - has a single name, multiple language variants can be specified by - including this property multiple times with different "LANGUAGE" - parameter values on each. + Multiple language variants can be stored by setting this property more than + once, each with a different ``LANGUAGE`` parameter value. Example: - Below, we set the name of the calendar. + Set the name of the calendar. .. code-block:: pycon @@ -291,31 +277,25 @@ def add_missing_timezones( NAME:My Calendar X-WR-CALNAME:My Calendar END:VCALENDAR + + See also: + :attr:`description` """, ) description = multi_language_text_property( "DESCRIPTION", "X-WR-CALDESC", - """This property specifies the description of the calendar. - - This implements :rfc:`7986` ``DESCRIPTION`` and ``X-WR-CALDESC``. + """A human-readable description of this calendar's content, per :rfc:`7986#section-5.2`. - Conformance: - This property can be specified multiple times in an - iCalendar object. However, each property MUST represent the - description of the calendar in a different language. + Implements both ``DESCRIPTION`` (from :rfc:`7986`) and ``X-WR-CALDESC`` + for broader calendar client compatibility. - Description: - This property is used to specify a lengthy textual - description of the iCalendar object that can be used by calendar - user agents when describing the nature of the calendar data to a - user. Whilst a calendar only has a single description, multiple - language variants can be specified by including this property - multiple times with different "LANGUAGE" parameter values on each. + Multiple language variants can be stored by setting this property more than + once with different ``LANGUAGE`` parameter values. Example: - Below, we add a description to a calendar. + Add a description to a calendar. .. code-block:: pycon @@ -327,34 +307,25 @@ def add_missing_timezones( DESCRIPTION:This is a calendar X-WR-CALDESC:This is a calendar END:VCALENDAR + + See also: + :attr:`calendar_name` """, ) color = single_string_property( "COLOR", - """This property specifies a color used for displaying the calendar. - - This implements :rfc:`7986` ``COLOR`` and ``X-APPLE-CALENDAR-COLOR``. - Please note that since :rfc:`7986`, subcomponents can have their own color. + """A CSS3 color name or value used to visually distinguish this calendar, per :rfc:`7986#section-5.9`. - Property Parameters: - IANA and non-standard property parameters can - be specified on this property. + Implements both ``COLOR`` (from :rfc:`7986`) and ``X-APPLE-CALENDAR-COLOR``. + The value is a case-insensitive CSS3 color name (e.g. ``"turquoise"``) or + a hex code (e.g. ``"#ffffff"``), drawn from the + `CSS3 color specification `_. - Conformance: - This property can be specified once in an iCalendar - object or in ``VEVENT``, ``VTODO``, or ``VJOURNAL`` calendar components. - - Description: - This property specifies a color that clients MAY use - when presenting the relevant data to a user. Typically, this - would appear as the "background" color of events or tasks. The - value is a case-insensitive color name taken from the CSS3 set of - names, defined in Section 4.3 of `W3C.REC-css3-color-20110607 `_. + Since :rfc:`7986`, individual ``VEVENT``, ``VTODO``, and ``VJOURNAL`` + subcomponents may also carry their own color. Example: - ``"turquoise"``, ``"#ffffff"`` - .. code-block:: pycon >>> from icalendar import Calendar @@ -365,6 +336,8 @@ def add_missing_timezones( COLOR:black END:VCALENDAR + See also: + :attr:`calendar_name` """, "X-APPLE-CALENDAR-COLOR", ) @@ -372,87 +345,99 @@ def add_missing_timezones( uid = uid_property prodid = single_string_property( "PRODID", - """PRODID specifies the identifier for the product that created the iCalendar object. + """The product identifier for the software that created this iCalendar object. -Conformance: - The property MUST be specified once in an iCalendar object. +Defined in :rfc:`5545#section-3.7.3` and required exactly once per calendar object. -Description: - The vendor of the implementation SHOULD assure that - this is a globally unique identifier; using some technique such as - an FPI value, as defined in [ISO.9070.1991]. - - This property SHOULD NOT be used to alter the interpretation of an - iCalendar object beyond the semantics specified in this memo. For - example, it is not to be used to further the understanding of non- - standard properties. +The value should be a globally unique string. The conventional format is a +Formal Public Identifier (FPI), e.g. ``-//My Company//My Product//EN``, but any +unique string is acceptable. Example: - The following is an example of this property. It does not - imply that English is the default language. + Set a custom product identifier on a new calendar. + + .. code-block:: pycon - .. code-block:: text + >>> from icalendar import Calendar + >>> cal = Calendar() + >>> cal.prodid = "-//MyApp//MyCalendar//EN" + >>> cal.prodid + '-//MyApp//MyCalendar//EN' - -//ABC Corporation//NONSGML My Product//EN +See also: + :attr:`version` """, ) version = single_string_property( "VERSION", - """VERSION of the calendar specification. + """The iCalendar specification version required to interpret this object. -The default is ``"2.0"`` for :rfc:`5545`. +Defined in :rfc:`5545#section-3.7.4` and required exactly once per calendar object. +The value ``"2.0"`` indicates :rfc:`5545` compliance, which is the default used +by this library. A range such as ``"1.0;2.0"`` may indicate minimum and maximum +supported versions. -Purpose: - This property specifies the identifier corresponding to the - highest version number or the minimum and maximum range of the - iCalendar specification that is required in order to interpret the - iCalendar object. +Example: + .. code-block:: pycon + >>> from icalendar import Calendar + >>> cal = Calendar() + >>> cal.version = "2.0" + >>> cal.version + '2.0' - """, +See also: + :attr:`prodid`, :attr:`calscale` +""", ) calscale = single_string_property( "CALSCALE", - """CALSCALE defines the calendar scale used for the calendar information specified in the iCalendar object. - -Compatibility: - :rfc:`7529` makes the case that GREGORIAN stays the default and other calendar scales - are implemented on the RRULE. - -Conformance: - This property can be specified once in an iCalendar - object. The default value is "GREGORIAN". - -Description: - This memo is based on the Gregorian calendar scale. - The Gregorian calendar scale is assumed if this property is not - specified in the iCalendar object. It is expected that other - calendar scales will be defined in other specifications or by - future versions of this memo. + """The calendar scale for date and time values in this iCalendar object. + +Defined in :rfc:`5545#section-3.7.1`. The only value currently defined is +``"GREGORIAN"`` (the default). When this property is absent, Gregorian is assumed. + +Per :rfc:`7529`, non-Gregorian calendar systems are expressed via ``RRULE`` +transformations rather than a different ``CALSCALE`` value. + +Example: + .. code-block:: pycon + + >>> from icalendar import Calendar + >>> cal = Calendar() + >>> cal.calscale + 'GREGORIAN' + +See also: + :attr:`version` """, default="GREGORIAN", ) method = single_string_property( "METHOD", - """METHOD defines the iCalendar object method associated with the calendar object. - -Description: - When used in a MIME message entity, the value of this - property MUST be the same as the Content-Type "method" parameter - value. If either the "METHOD" property or the Content-Type - "method" parameter is specified, then the other MUST also be - specified. - - No methods are defined by this specification. This is the subject - of other specifications, such as the iCalendar Transport- - independent Interoperability Protocol (iTIP) defined by :rfc:`5546`. - - If this property is not present in the iCalendar object, then a - scheduling transaction MUST NOT be assumed. In such cases, the - iCalendar object is merely being used to transport a snapshot of - some calendar information; without the intention of conveying a - scheduling semantic. + """The iTIP scheduling method associated with this calendar object, per :rfc:`5545#section-3.7.2`. + +When present, ``METHOD`` indicates that this object is part of a scheduling +transaction (e.g., a meeting invitation or cancellation). Scheduling methods +are defined by :rfc:`5546` (iTIP), with values such as ``"REQUEST"``, +``"REPLY"``, ``"CANCEL"``, and ``"PUBLISH"``. + +When used inside a MIME message, this value must match the ``method`` parameter +of the ``Content-Type`` header. If absent, the calendar is treated as a plain +data snapshot with no scheduling semantics. + +Example: + .. code-block:: pycon + + >>> from icalendar import Calendar + >>> cal = Calendar() + >>> cal.method = "REQUEST" + >>> cal.method + 'REQUEST' + +See also: + :attr:`version`, :rfc:`5546` """, ) url = url_property @@ -460,23 +445,28 @@ def add_missing_timezones( @property def refresh_interval(self) -> timedelta | None: - """REFRESH-INTERVAL specifies a suggested minimum interval for - polling for changes of the calendar data from the original source - of that data. + """A suggested minimum polling interval for fetching updates to this calendar, per :rfc:`7986#section-5.7`. - Conformance: - This property can be specified once in an iCalendar - object, consisting of a positive duration of time. - - Description: - This property specifies a positive duration that gives - a suggested minimum polling interval for checking for updates to - the calendar data. The value of this property SHOULD be used by - calendar user agents to limit the polling interval for calendar - data updates to the minimum interval specified. + Returns a :class:`~datetime.timedelta` or ``None`` when not set. + Calendar clients should not poll more frequently than this interval. + The value must be a positive duration. Raises: - ValueError: When setting a negative duration. + ValueError: When setting a non-positive (zero or negative) duration. + TypeError: When setting a value that is not a :class:`~datetime.timedelta` or ``None``. + + Example: + .. code-block:: pycon + + >>> from datetime import timedelta + >>> from icalendar import Calendar + >>> cal = Calendar() + >>> cal.refresh_interval = timedelta(hours=1) + >>> cal.refresh_interval + datetime.timedelta(seconds=3600) + + See also: + :attr:`source` """ refresh_interval = self.get("REFRESH-INTERVAL") return refresh_interval.dt if refresh_interval else None diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index 51f63d9f3..ad2adb459 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -616,39 +616,53 @@ def __eq__(self, other): DTSTAMP = stamp = single_utc_property( "DTSTAMP", - """RFC 5545: + """The UTC datetime stamp recording when this component instance was created or last revised. - Conformance: This property MUST be included in the "VEVENT", - "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components. + Defined in :rfc:`5545#section-3.8.7.2` and required in + ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VFREEBUSY`` components. - Description: In the case of an iCalendar object that specifies a - "METHOD" property, this property specifies the date and time that - the instance of the iCalendar object was created. In the case of - an iCalendar object that doesn't specify a "METHOD" property, this - property specifies the date and time that the information - associated with the calendar component was last revised in the - calendar store. + When the calendar object carries a ``METHOD`` property (e.g., for + scheduling), this value is the creation time of *this particular revision*. + Without a ``METHOD`` property it is equivalent to :attr:`LAST_MODIFIED`. - The value MUST be specified in the UTC time format. + The value is always in UTC. Also accessible as :attr:`stamp`. - In the case of an iCalendar object that doesn't specify a "METHOD" - property, this property is equivalent to the "LAST-MODIFIED" - property. + Example: + .. code-block:: pycon + + >>> from datetime import timezone, datetime + >>> from icalendar import Event + >>> event = Event() + >>> event.DTSTAMP = datetime(2024, 6, 1, 12, 0, 0, tzinfo=timezone.utc) + >>> event.DTSTAMP + datetime.datetime(2024, 6, 1, 12, 0, tzinfo=datetime.timezone.utc) + + See also: + :attr:`LAST_MODIFIED`, :attr:`CREATED`, :attr:`stamp` """, ) LAST_MODIFIED = single_utc_property( "LAST-MODIFIED", - """RFC 5545: + """The UTC datetime when this component's information was last revised, per :rfc:`5545#section-3.8.7.3`. - Purpose: This property specifies the date and time that the - information associated with the calendar component was last - revised in the calendar store. + Analogous to a file's modification timestamp. This property is optional; + when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`. + + Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE`` + components. The value is always in UTC. + + Example: + .. code-block:: pycon - Note: This is analogous to the modification date and time for a - file in the file system. + >>> from datetime import timezone, datetime + >>> from icalendar import Event + >>> event = Event() + >>> event.LAST_MODIFIED = datetime(2024, 6, 1, 9, 0, 0, tzinfo=timezone.utc) + >>> event.LAST_MODIFIED + datetime.datetime(2024, 6, 1, 9, 0, tzinfo=datetime.timezone.utc) - Conformance: This property can be specified in the "VEVENT", - "VTODO", "VJOURNAL", or "VTIMEZONE" calendar components. + See also: + :attr:`last_modified`, :attr:`DTSTAMP`, :attr:`CREATED` """, ) @@ -704,17 +718,28 @@ def _utc_now(): CREATED = single_utc_property( "CREATED", - """ - CREATED specifies the date and time that the calendar - information was created by the calendar user agent in the calendar - store. + """The UTC datetime when this calendar component was first created, per :rfc:`5545#section-3.8.7.1`. + + Records when the calendar user agent originally stored the component. + This property is optional; when absent, :attr:`created` falls back to + :attr:`DTSTAMP`. - Conformance: - The property can be specified once in "VEVENT", - "VTODO", or "VJOURNAL" calendar components. The value MUST be - specified as a date with UTC time. + Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components. + The value is always in UTC. - """, + Example: + .. code-block:: pycon + + >>> from datetime import timezone, datetime + >>> from icalendar import Event + >>> event = Event() + >>> event.CREATED = datetime(2024, 1, 1, 8, 0, 0, tzinfo=timezone.utc) + >>> event.CREATED + datetime.datetime(2024, 1, 1, 8, 0, tzinfo=datetime.timezone.utc) + + See also: + :attr:`created`, :attr:`DTSTAMP`, :attr:`LAST_MODIFIED` + """, ) _validate_new = True From a19e528e232eaf0bbd3181eae237569fe5f2fff5 Mon Sep 17 00:00:00 2001 From: ykd007 Date: Thu, 14 May 2026 15:26:03 +0530 Subject: [PATCH 2/3] fix doctests: use ELLIPSIS for tzinfo and str() for vText values --- src/icalendar/cal/alarm.py | 8 ++++---- src/icalendar/cal/calendar.py | 6 +++--- src/icalendar/cal/component.py | 12 ++++++------ 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/icalendar/cal/alarm.py b/src/icalendar/cal/alarm.py index 61a043b69..f40472fa8 100644 --- a/src/icalendar/cal/alarm.py +++ b/src/icalendar/cal/alarm.py @@ -174,8 +174,8 @@ class Alarm(Component): >>> from icalendar import Alarm >>> alarm = Alarm() >>> alarm.ACKNOWLEDGED = datetime(2024, 1, 15, 10, 0, 0, tzinfo=timezone.utc) - >>> alarm.ACKNOWLEDGED - datetime.datetime(2024, 1, 15, 10, 0, tzinfo=datetime.timezone.utc) + >>> alarm.ACKNOWLEDGED # doctest: +ELLIPSIS + datetime.datetime(2024, 1, 15, 10, 0, tzinfo=...) See also: :attr:`TRIGGER` — the time at which the alarm fires. @@ -208,8 +208,8 @@ class Alarm(Component): >>> from icalendar import Alarm >>> alarm = Alarm() >>> alarm.TRIGGER = timedelta(minutes=-15) - >>> alarm.TRIGGER - datetime.timedelta(seconds=-900) + >>> alarm.TRIGGER # doctest: +ELLIPSIS + datetime.timedelta(...) See also: :attr:`TRIGGER_RELATED`, :attr:`DURATION`, :attr:`REPEAT` diff --git a/src/icalendar/cal/calendar.py b/src/icalendar/cal/calendar.py index ab94bafce..3fa8f9b23 100644 --- a/src/icalendar/cal/calendar.py +++ b/src/icalendar/cal/calendar.py @@ -361,7 +361,7 @@ def add_missing_timezones( >>> from icalendar import Calendar >>> cal = Calendar() >>> cal.prodid = "-//MyApp//MyCalendar//EN" - >>> cal.prodid + >>> str(cal.prodid) '-//MyApp//MyCalendar//EN' See also: @@ -383,7 +383,7 @@ def add_missing_timezones( >>> from icalendar import Calendar >>> cal = Calendar() >>> cal.version = "2.0" - >>> cal.version + >>> str(cal.version) '2.0' See also: @@ -433,7 +433,7 @@ def add_missing_timezones( >>> from icalendar import Calendar >>> cal = Calendar() >>> cal.method = "REQUEST" - >>> cal.method + >>> str(cal.method) 'REQUEST' See also: diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index ad2adb459..0503643f2 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -634,8 +634,8 @@ def __eq__(self, other): >>> from icalendar import Event >>> event = Event() >>> event.DTSTAMP = datetime(2024, 6, 1, 12, 0, 0, tzinfo=timezone.utc) - >>> event.DTSTAMP - datetime.datetime(2024, 6, 1, 12, 0, tzinfo=datetime.timezone.utc) + >>> event.DTSTAMP # doctest: +ELLIPSIS + datetime.datetime(2024, 6, 1, 12, 0, tzinfo=...) See also: :attr:`LAST_MODIFIED`, :attr:`CREATED`, :attr:`stamp` @@ -658,8 +658,8 @@ def __eq__(self, other): >>> from icalendar import Event >>> event = Event() >>> event.LAST_MODIFIED = datetime(2024, 6, 1, 9, 0, 0, tzinfo=timezone.utc) - >>> event.LAST_MODIFIED - datetime.datetime(2024, 6, 1, 9, 0, tzinfo=datetime.timezone.utc) + >>> event.LAST_MODIFIED # doctest: +ELLIPSIS + datetime.datetime(2024, 6, 1, 9, 0, tzinfo=...) See also: :attr:`last_modified`, :attr:`DTSTAMP`, :attr:`CREATED` @@ -734,8 +734,8 @@ def _utc_now(): >>> from icalendar import Event >>> event = Event() >>> event.CREATED = datetime(2024, 1, 1, 8, 0, 0, tzinfo=timezone.utc) - >>> event.CREATED - datetime.datetime(2024, 1, 1, 8, 0, tzinfo=datetime.timezone.utc) + >>> event.CREATED # doctest: +ELLIPSIS + datetime.datetime(2024, 1, 1, 8, 0, tzinfo=...) See also: :attr:`created`, :attr:`DTSTAMP`, :attr:`LAST_MODIFIED` From 68802f9fbb18eac1167022e6c35f292caad53eb3 Mon Sep 17 00:00:00 2001 From: ykd007 Date: Thu, 14 May 2026 15:30:32 +0530 Subject: [PATCH 3/3] add changelog entry for docstring improvements --- CHANGES.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.rst b/CHANGES.rst index 7cbdfa09d..5afda34da 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -11,6 +11,7 @@ Minor changes ~~~~~~~~~~~~~ - Bump PyPy from 3.10 to 3.11 for testing. :pr:`1383` +- Replaced RFC copy-paste text in docstrings with Pythonic docstrings for calendar components. :pr:`1385` - Created an :attr:`~icalendar.prop.dt.period.vPeriod.ical_value` property for the :class:`~icalendar.prop.dt.period.vPeriod` component. :issue:`876` Breaking changes