Merge branch 'main' into issue-662-todo

CHANGES.rst

@@ -7,14 +7,17 @@ Changelog
 Minor changes:
 
 - Added ``end``, ``start``, ``duration``, ``DTSTART``, ``DUE``, and ``DURATION`` attributes to ``Todo`` components. See `Issue 662`_.
+- Format test code with Ruff. See `Issue 672 <https://github.com/collective/icalendar/issues/672>`_.
+- Document the Debian package. See `Issue 701 <https://github.com/collective/icalendar/issues/701>`_.
 
 Breaking changes:
 
 - ...
 
 New features:
 
-- ...
+- Add ``VALARM`` properties for :rfc:`9074`. See `Issue 657 <https://github.com/collective/icalendar/issues/657>`_
+- Test compatibility with Python 3.13
 
 Bug fixes:
 
@@ -27,7 +30,6 @@ New features:
 
 - Added ``end``, ``start``, ``duration``, ``DTSTART``, ``DUE``, and ``DURATION`` attributes to ``Event`` components. See `Issue 662`_.
 - Added ``end``, ``start``, ``duration`` and, ``DTSTART`` attributes to ``Journal`` components. See `Issue 662`_.
-- Test compatibility with Python 3.13
 
 Bug fixes:
 
@@ -455,7 +457,6 @@ Bug fixes:
 
 - Use ``vText`` as default type, when convert recurrence definition to ical string. [kam193]
 
-
 4.0.5 (2020-03-21)
 ------------------
 

README.rst

@@ -2,15 +2,15 @@
 Internet Calendaring and Scheduling (iCalendar) for Python
 ==========================================================
 
-The `icalendar`_ package is a `RFC 5545`_ compatible parser/generator for iCalendar
+The `icalendar`_ package is a :rfc:`5545` compatible parser/generator for iCalendar
 files.
 
 ----
 
 :Homepage: https://icalendar.readthedocs.io
 :Code: https://github.com/collective/icalendar
 :Mailing list: https://github.com/collective/icalendar/issues
-:Dependencies: `python-dateutil`_ and `pytz`_.
+:Dependencies: `python-dateutil`_ and `tzdata`_.
 :License: `BSD`_
 
 ----
@@ -41,9 +41,8 @@ files.
 
 
 .. _`icalendar`: https://pypi.org/project/icalendar/
-.. _`RFC 5545`: https://www.ietf.org/rfc/rfc5545.txt
 .. _`python-dateutil`: https://github.com/dateutil/dateutil/
-.. _`pytz`: https://pypi.org/project/pytz/
+.. _`tzdata`: https://pypi.org/project/tzdata/
 .. _`BSD`: https://github.com/collective/icalendar/issues/2
 
 Quick start guide
@@ -96,7 +95,7 @@ Create Events, TODOs, Journals, Alarms, ...
 -------------------------------------------
 
 ``icalendar`` supports the creation and parsing of all kinds of objects
-in the iCalendar (RFC 5545) standard.
+in the iCalendar (:rfc:`5545`) standard.
 
 .. code:: python
 
@@ -176,8 +175,9 @@ Related projects
 ================
 
 * `icalevents <https://github.com/irgangla/icalevents>`_. It is built on top of icalendar and allows you to query iCal files and get the events happening on specific dates. It manages recurrent events as well.
-* `recurring-ical-events <https://pypi.org/project/recurring-ical-events/>`_. Library to query an ``ICalendar`` object for events happening at a certain date or within a certain time.
-* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library to make ``ICalendar`` objects and files using the non-standard ``X-WR-TIMEZONE`` compliant with the standard (RFC 5545).
+* `recurring-ical-events <https://pypi.org/project/recurring-ical-events/>`_. Library to query an ``icalendar.Calendar`` object for events and other components happening at a certain date or within a certain time.
+* `x-wr-timezone <https://pypi.org/project/x-wr-timezone/>`_. Library and command line tool to make ``icalendar.Calendar`` objects and files from Google Calendar (using the non-standard ``X-WR-TIMEZONE`` property) compliant with the standard (:rfc:`5545`).
+* `ics-query <http://pypi.org/project/ics-query>`_. Command line tool to query iCalendar files for occurrences of events and other components.
 
 Further Reading
 ===============

docs/install.rst

@@ -1,6 +1,11 @@
 Installing iCalendar
 ====================
 
+You can install ``icalendar`` in several ways.
+
+Python Package with ``pip``
+---------------------------
+
 To install the icalendar package, use:
 
 .. code-block:: shell
@@ -14,6 +19,16 @@ package, like this:
 
     >>> import icalendar
 
+Debian or Ubuntu
+----------------
+
+You can install the `python-icalendar package <https://tracker.debian.org/pkg/python-icalendar>`_
+for Debian or its derivatives.
+
+.. code-block:: shell
+
+    sudo apt-get install python3-icalendar
+
 Development Setup
 -----------------
 

docs/maintenance.rst

@@ -148,3 +148,16 @@ This section contains useful links for maintainers and collaborators:
 
 - `Future of icalendar, looking for maintainer #360 <https://github.com/collective/icalendar/discussions/360>`__
 - `Comment on the Plone tests running with icalendar <https://github.com/collective/icalendar/pull/447#issuecomment-1277643634>`__
+
+Updating Python Versions
+------------------------
+
+When adding support for a new Python version or removing support for an old one, the following files need to be updated:
+
+1. ``.github/workflows/tests.yml``: Add or remove the Python version from the test matrix.
+2. ``tox.ini``: Update the ``envlist`` to include or remove the Python version.
+3. ``pyproject.toml``: Update the ``requires-python`` line and the ``classifiers`` list.
+4. ``README.rst``: Update the compatibility information.
+5. ``docs/maintenance.rst``: Update this list if any new files need to be modified.
+
+Remember to test the changes thoroughly and update any documentation that mentions supported Python versions.

docs/usage.rst

@@ -12,18 +12,18 @@ Compatibility
 
 This package is compatible with the following standards:
 
-- :rfc:`5545`
-- :rfc:`7529`
-
-We do not claim compatibility to:
-
-- :rfc:`2445` - which is obsoleted by :rfc:`5545`
-- :rfc:`6886`
-- :rfc:`7953`
-- :rfc:`7986`
-- :rfc:`9073`
-- :rfc:`9074`
-- :rfc:`9253`
+- :rfc:`5545` - Internet Calendaring and Scheduling Core Object Specification (iCalendar)
+- :rfc:`7529` - Non-Gregorian Recurrence Rules in the Internet Calendaring and Scheduling Core Object Specification (iCalendar)
+- :rfc:`9074` - "VALARM" Extensions for iCalendar
+
+We do not claim compatibility to the following RFCs. They might work though.
+
+- :rfc:`2445` - obsoleted by :rfc:`5545`
+- :rfc:`6868` - Parameter Value Encoding in iCalendar and vCard
+- :rfc:`7953` - Calendar Availability
+- :rfc:`7986` - New Properties for iCalendar
+- :rfc:`9073` - Event Publishing Extensions to iCalendar
+- :rfc:`9253` - Support for iCalendar Relationships
 
 File structure
 --------------

src/icalendar/cal.py

@@ -1055,10 +1055,10 @@ class Alarm(Component):
     required = ('ACTION', 'TRIGGER',)
     singletons = (
             'ATTACH', 'ACTION', 'DESCRIPTION', 'SUMMARY', 'TRIGGER',
-            'DURATION', 'REPEAT',
+            'DURATION', 'REPEAT', 'UID', 'PROXIMITY', 'ACKNOWLEDGED'
             )
     inclusive = (('DURATION', 'REPEAT',), ('SUMMARY', 'ATTENDEE',))
-    multiple = ('ATTENDEE', 'ATTACH')
+    multiple = ('ATTENDEE', 'ATTACH', 'RELATED-TO')
 
 
 class Calendar(Component):

src/icalendar/prop.py

@@ -1073,6 +1073,7 @@ def __init__(self, *args, **kwargs):
         'action': 'text',
         'repeat': 'integer',
         'trigger': 'duration',
+        'acknowledged': 'date-time',
         # Change Management Component Properties
         'created': 'date-time',
         'dtstamp': 'date-time',