Merge pull request #810 from niccokunzmann/issue-798

Add parameters to properties

Author: niccokunzmann

CHANGES.rst

@@ -8,6 +8,8 @@ Minor changes:
 
 - Use ``ruff`` to format the source code.
 - Update project metadata to use License-Expression.
+- Use ``tzp.localize(dt, None)`` to remove the timezone from a datetime.
+- Remove the HTML documentation when building with ``tox`` to force rebuild.
 - Switch to PyData Sphinx Theme for documentation. See `Issue 803 <https://github.com/collective/icalendar/issues/804>`_.
 
 Breaking changes:
@@ -22,11 +24,14 @@ New features:
 - Add ``sequence`` attribute to ``Event``, ``Todo``, and ``Journal`` components. See `Issue 802 <https://github.com/collective/icalendar/issues/802>`_.
 - Add ``categories`` attribute to ``Calendar``, ``Event``, ``Todo``, and ``Journal`` components. See `Issue 655 <https://github.com/collective/icalendar/issues/655>`_.
 - Add compatibility to :rfc:`6868`. See `Issue 652 <https://github.com/collective/icalendar/issues/652>`_.
+- Add ``freebusy`` property to the ``Calendar`` to get this type of subcomponents easier.
+- Add parameters from :rfc:`5545` to properties ``ALTREP``, ``CN``, ``CUTYPE``, ``DELEGATED_FROM``, ``DELEGATED_TO``, ``DIR``, ``FBTYPE``, ``LANGUAGE``, ``MEMBER``, ``PARTSTAT``, ``RANGE``, ``RELATED``, ``ROLE``, ``RSVP``, ``SENT_BY``, ``TZID``, and ``RELTYPE``. See `Issue 798 <https://github.com/collective/icalendar/issues/798>`_.
 - New properties from :rfc:`7986` can occur multiple times in ``VCALENDAR``. See `PR 808`_.
 
 Bug fixes:
 
 - Move import at the end of ``icalendar.parser`` into a function to mitigate import errors, see `Issue 781 <https://github.com/collective/icalendar/issues/781>`_.
+- ``ALTREP``, ``DELEGATED-FROM``, ``DELEGATED-TO``, ``DIR``, ``MEMBER``, and ``SENT-BY`` require double quotes. These are now always added.
 - Classify ``CATEGORIES`` as multiple in ``VEVENT``. See `PR 808 <https://github.com/collective/icalendar/pull/808>`_.
 
 6.1.3 (2025-03-19)

docs/api.rst

@@ -1,13 +1,18 @@
 API Reference
 -------------
 
+icalendar.attr
+++++++++++++++
+
+.. automodule:: icalendar.attr
+   :members:
+
 icalendar.alarms
 ++++++++++++++++
 
 .. automodule:: icalendar.alarms
    :members:
 
-
 icalendar.cal
 +++++++++++++
 
@@ -26,12 +31,24 @@ icalendar.cli
 .. automodule:: icalendar.cli
    :members:
 
+icalendar.enums
++++++++++++++++
+
+.. automodule:: icalendar.enums
+   :members:
+
 icalendar.error
 +++++++++++++++
 
 .. automodule:: icalendar.error
    :members:
 
+icalendar.param
++++++++++++++++
+
+.. automodule:: icalendar.param
+   :members:
+
 icalendar.parser
 ++++++++++++++++
 

docs/conf.py

@@ -10,6 +10,7 @@
     "sphinx_copybutton",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.napoleon",
 ]
 source_suffix = ".rst"
 master_doc = "index"

src/icalendar/__init__.py

@@ -15,6 +15,7 @@
     TimezoneStandard,
     Todo,
 )
+from icalendar.enums import CUTYPE, FBTYPE, PARTSTAT, RANGE, RELATED, RELTYPE, ROLE
 from icalendar.error import (
     ComponentEndMissing,
     ComponentStartMissing,
@@ -111,5 +112,13 @@
     "ComponentStartMissing",
     "IncompleteAlarmInformation",
     "LocalTimezoneMissing",
+    "CUTYPE",
+    "FBTYPE",
+    "PARTSTAT",
+    "RANGE",
     "vSkip",
+    "RELATED",
+    "vSkip",
+    "RELTYPE",
+    "ROLE",
 ]

src/icalendar/attr.py

@@ -1,8 +1,8 @@
 """Attributes of Components and properties."""
 from __future__ import annotations
 
-from datetime import date, datetime, timedelta
 import itertools
+from datetime import date, datetime, timedelta
 from typing import TYPE_CHECKING, Optional, Union
 
 from icalendar.error import InvalidCalendar
@@ -313,9 +313,9 @@ def multi_language_text_property(main_prop:str, compatibility_prop:str, doc:str)
     This property can be defined several times with different ``LANGUAGE`` parameters.
 
     Args:
-        main_prop: The property to set and get, such as ``NAME``
-        compatibility_prop: An old property used before, such as ``X-WR-CALNAME``
-        doc: The documentation string
+        main_prop (str): The property to set and get, such as ``NAME``
+        compatibility_prop (str): An old property used before, such as ``X-WR-CALNAME``
+        doc (str): The documentation string
     """
     def fget(self: Component) -> Optional[str]:
         """Get the property"""
@@ -369,8 +369,9 @@ def fdel(self: Component):
 def single_utc_property(name: str, docs: str) -> property:
     """Create a property to access a value of datetime in UTC timezone.
 
-    name - name of the property
-    docs - documentation string
+    Args:
+        name: name of the property
+        docs: documentation string
     """
     docs = (
         f"""The {name} property. datetime in UTC

src/icalendar/cal.py

@@ -1956,6 +1956,16 @@ def todos(self) -> list[Todo]:
         """
         return self.walk("VTODO")
 
+    @property
+    def freebusy(self) -> list[FreeBusy]:
+        """All FreeBusy components in the calendar.
+
+        This is a shortcut to get all FreeBusy.
+        Modifications do not change the calendar.
+        Use :py:meth:`Component.add_component`.
+        """
+        return self.walk("VFREEBUSY")
+
     def get_used_tzids(self) -> set[str]:
         """The set of TZIDs in use.
 

src/icalendar/enums.py

@@ -0,0 +1,129 @@
+"""Enumerations for different types in the RFCs."""
+from enum import Enum as _Enum
+
+
+class Enum(_Enum):
+    """Enum class that can be pickled."""
+
+    def __reduce_ex__(self, _p):
+        """For pickling."""
+        return self.__class__, (self._name_,)
+
+
+class StrEnum(str, Enum):
+    """Enum for strings."""
+
+
+class PARTSTAT(StrEnum):
+    """Enum for PARTSTAT from :rfc:`5545`.
+
+    Attributes:
+        ``NEEDS_ACTION``,
+        ``ACCEPTED``,
+        ``DECLINED``,
+        ``TENTATIVE``,
+        ``DELEGATED``,
+        ``COMPLETED``,
+        ``IN_PROCESS``
+    """
+    NEEDS_ACTION = "NEEDS-ACTION"
+    ACCEPTED = "ACCEPTED"
+    DECLINED = "DECLINED"
+    TENTATIVE = "TENTATIVE"
+    DELEGATED = "DELEGATED"
+    COMPLETED = "COMPLETED"
+    IN_PROCESS = "IN-PROCESS"
+
+
+class FBTYPE(StrEnum):
+    """Enum for FBTYPE from :rfc:`5545`.
+
+    Attributes:
+        ``FREE``,
+        ``BUSY``,
+        ``BUSY-UNAVAILABLE``,
+        ``BUSY-TENTATIVE``
+    """
+    FREE = "FREE"
+    BUSY = "BUSY"
+    BUSY_UNAVAILABLE = "BUSY-UNAVAILABLE"
+    BUSY_TENTATIVE = "BUSY-TENTATIVE"
+
+
+class CUTYPE(StrEnum):
+    """Enum for CTYPE from :rfc:`5545`.
+
+    Attributes:
+        ``INDIVIDUAL``,
+        ``GROUP``,
+        ``RESOURCE``,
+        ``ROOM``,
+        ``UNKNOWN``
+    """
+    INDIVIDUAL = "INDIVIDUAL"
+    GROUP = "GROUP"
+    RESOURCE = "RESOURCE"
+    ROOM = "ROOM"
+    UNKNOWN = "UNKNOWN"
+
+
+class RELTYPE(StrEnum):
+    """Enum for RELTYPE from :rfc:`5545`.
+
+    Attributes:
+        ``PARENT``,
+        ``CHILD``,
+        ``SIBLING``
+    """
+    PARENT = "PARENT"
+    CHILD = "CHILD"
+    SIBLING = "SIBLING"
+
+
+class RANGE(StrEnum):
+    """Enum for RANGE from :rfc:`5545`.
+
+    Attributes:
+        ``THISANDFUTURE``,
+        ``THISANDPRIOR``
+    """
+
+    THISANDFUTURE = "THISANDFUTURE"
+    THISANDPRIOR = "THISANDPRIOR"  # deprecated
+
+
+class RELATED(StrEnum):
+    """Enum for RELATED from :rfc:`5545`.
+
+    Attributes:
+        ``START``,
+        ``END``
+    """
+    START = "START"
+    END = "END"
+
+
+class ROLE(StrEnum):
+    """Enum for ROLE from :rfc:`5545`.
+
+    Attributes:
+        ``CHAIR``,
+        ``REQ-PARTICIPANT``,
+        ``OPT-PARTICIPANT``,
+        ``NON-PARTICIPANT``
+    """
+    CHAIR = "CHAIR"
+    REQ_PARTICIPANT = "REQ-PARTICIPANT"
+    OPT_PARTICIPANT = "OPT-PARTICIPANT"
+    NON_PARTICIPANT = "NON-PARTICIPANT"
+
+
+__all__ = [
+    "PARTSTAT",
+    "FBTYPE",
+    "CUTYPE",
+    "RANGE",
+    "RELATED",
+    "ROLE",
+    "RELTYPE",
+]