Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions news/1244.documentation.3
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Replaced the RFC copy-paste in the :attr:`~icalendar.attr.color_property` docstring, used by :attr:`Event.color <icalendar.cal.event.Event.color>`, :attr:`Journal.color <icalendar.cal.journal.Journal.color>`, and :attr:`Todo.color <icalendar.cal.todo.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
56 changes: 31 additions & 25 deletions src/icalendar/attr/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://www.w3.org/TR/css-color-3/>`_.

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 <https://www.w3.org/TR/css-color-3/>`_.
- :attr:`Event.color <icalendar.cal.event.Event.color>`
- :attr:`Journal.color <icalendar.cal.journal.Journal.color>`
- :attr:`Todo.color <icalendar.cal.todo.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 <icalendar.cal.calendar.Calendar.color>` for the
calendar-level color, including the ``X-APPLE-CALENDAR-COLOR`` alias.
""",
)

sequence_property = single_int_property(
Expand Down