From ff5e0050bfba92f84f00cbb5e2ce514988beb57f Mon Sep 17 00:00:00 2001 From: Sneha Shukla <6regxsw7@mail.grokbot.com> Date: Thu, 19 Nov 2026 16:59:36 +0530 Subject: [PATCH] Rewrite the COLOR property docstring in Pythonic style The shared color_property docstring still used RFC section headings (Property Parameters, Conformance, Description). Replace them with a summary, implementation notes, cross-references to Event.color, Journal.color, and Todo.color, a doctest example, and a pointer to Calendar.color. AI disclosure: I used an AI assistant (Grok Bot) to help pick one unchecked #1244 item not already covered by an open pull request, compare the old docstring with the categories_property and Calendar.color examples, rewrite it to the project style guide, and prepare the changelog entry. Prompts summarized: list remaining RFC-style docstrings for issue #1244; avoid Alarm trigger items already in PR #2094; rewrite color_property; add news/1244.documentation.3 with the required AI disclosure. Output: this commit. --- news/1244.documentation.3 | 1 + src/icalendar/attr/__init__.py | 56 +++++++++++++++++++--------------- 2 files changed, 32 insertions(+), 25 deletions(-) create mode 100644 news/1244.documentation.3 diff --git a/news/1244.documentation.3 b/news/1244.documentation.3 new file mode 100644 index 000000000..d316d3088 --- /dev/null +++ b/news/1244.documentation.3 @@ -0,0 +1 @@ +Replaced the RFC copy-paste in the :attr:`~icalendar.attr.color_property` docstring, used by :attr:`Event.color `, :attr:`Journal.color `, and :attr:`Todo.color `, with a Pythonic docstring and usage example. I used an AI assistant (Grok Bot) to help identify an unchecked item from issue #1244 that was not already covered by an open pull request, draft the rewritten docstring, and prepare this changelog entry. @sneha-shukla-dev diff --git a/src/icalendar/attr/__init__.py b/src/icalendar/attr/__init__.py index f55042b7c..7466310cd 100644 --- a/src/icalendar/attr/__init__.py +++ b/src/icalendar/attr/__init__.py @@ -563,38 +563,44 @@ def fdel(self: Component): color_property = single_string_property( "COLOR", - """This property specifies a color used for displaying the component. + """A CSS3 color name or hex value used when displaying a component. - This implements :rfc:`7986` ``COLOR`` property. +This property implements ``COLOR`` from :rfc:`7986#section-5.9`. +Clients may use the value as the background color of an event, to-do, +or journal entry. The value is a case-insensitive CSS3 color name, for +example ``"turquoise"``, or a hex code, for example ``"#ffffff"``, taken +from the `CSS3 color specification `_. - Property Parameters: - IANA and non-standard property parameters can - be specified on this property. +This property can be specified once on a ``VEVENT``, ``VTODO``, or +``VJOURNAL`` component. You can get, set, and delete the color as a +string. - Conformance: - This property can be specified once in an iCalendar - object or in ``VEVENT``, ``VTODO``, or ``VJOURNAL`` calendar components. +This property can be used in icalendar through its Python attributes of: - 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 `_. +- :attr:`Event.color ` +- :attr:`Journal.color ` +- :attr:`Todo.color ` - Example: - ``"turquoise"``, ``"#ffffff"`` +Example: + Set a color on a to-do, print its iCalendar representation, and then + read the value back. - .. code-block:: pycon + .. code-block:: pycon - >>> from icalendar import Todo - >>> todo = Todo() - >>> todo.color = "green" - >>> print(todo.to_ical()) - BEGIN:VTODO - COLOR:green - END:VTODO - """, + >>> from icalendar import Todo + >>> todo = Todo() + >>> todo.color = "green" + >>> print(todo.to_ical().decode()) + BEGIN:VTODO + COLOR:green + END:VTODO + >>> todo.color + 'green' + +See also: + :attr:`Calendar.color ` for the + calendar-level color, including the ``X-APPLE-CALENDAR-COLOR`` alias. +""", ) sequence_property = single_int_property(