Merge branch 'main' into niccokunzmann-shorten-example

CHANGES.rst

@@ -1,19 +1,16 @@
 Changelog
 =========
 
-6.1.1 (unreleased)
+6.1.2 (unreleased)
 ------------------
 
 Minor changes:
 
-- Add a ``weekday`` attribute to ``vWeekday`` components. See `Issue 749 <https://github.com/collective/icalendar/issues/749>`_.
-- Document ``vRecur`` property. See `Issue 758 <https://github.com/collective/icalendar/issues/758>`_.
-- Print failure of doctest to aid debugging.
-- Fix tests, improve code readability, fix typing. See `Issue 766 <https://github.com/collective/icalendar/issues/766>`_ and `Issue 765 <https://github.com/collective/icalendar/issues/765>`_.
+- ...
 
 Breaking changes:
 
-- The ``relative`` attribute of ``vWeekday`` components has the correct sign now. See `Issue 749 <https://github.com/collective/icalendar/issues/749>`_.
+- ...
 
 New features:
 
@@ -23,6 +20,25 @@ Bug fixes:
 
 - ...
 
+6.1.1 (2025-01-18)
+------------------
+
+Minor changes:
+
+- Add a ``weekday`` attribute to :class:`icalendar.prop.vWeekday` components. See `Issue 749 <https://github.com/collective/icalendar/issues/749>`_.
+- Document :class:`icalendar.prop.vRecur` property. See `Issue 758 <https://github.com/collective/icalendar/issues/758>`_.
+- Print failure of doctest to aid debugging.
+- Improve documentation of :class:`icalendar.prop.vGeo`
+- Fix tests, improve code readability, fix typing. See `Issue 766 <https://github.com/collective/icalendar/issues/766>`_ and `Issue 765 <https://github.com/collective/icalendar/issues/765>`_.
+
+Breaking changes:
+
+- The ``relative`` attribute of ``vWeekday`` components has the correct sign now. See `Issue 749 <https://github.com/collective/icalendar/issues/749>`_.
+
+New features:
+
+- Add :ref:`Security Policy`
+- Python types in documentation now link to their documentation pages using ``intersphinx``.
 
 6.1.0 (2024-11-22)
 ------------------

CONTRIBUTING.rst

@@ -18,12 +18,12 @@ For pull requests, keep this in mind
 
 - Add a test which proves your fix and make it pass.
 
-- Describe your change in CHANGES.rst
+- Describe your change in ``CHANGES.rst``
 
-- Add yourself to the docs/credits.rst
+- Add yourself to the ``docs/credits.rst``
 
-Development Setup
------------------
+Setup for Development
+---------------------
 
 If you would like to setup icalendar to
 contribute changes, the `Installation Section

README.rst

@@ -8,8 +8,9 @@ files.
 ----
 
 :Homepage: https://icalendar.readthedocs.io
+:Community Discussions: https://github.com/collective/icalendar/discussions
+:Issue Tracker: https://github.com/collective/icalendar/issues
 :Code: https://github.com/collective/icalendar
-:Mailing list: https://github.com/collective/icalendar/issues
 :Dependencies: `python-dateutil`_ and `tzdata`_.
 :License: `BSD`_
 

SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+Please find our [security policy in the documentation](https://icalendar.readthedocs.io/en/latest/security.html).
+
+See also:
+
+- [docs/security.rst](docs/security.rst)

docs/conf.py

@@ -21,7 +21,9 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
-    'sphinx_copybutton'
+    'sphinx_copybutton',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
 ]
 source_suffix = '.rst'
 master_doc = 'index'
@@ -41,3 +43,7 @@ man_pages = [
     ('index', 'icalendar', 'icalendar Documentation',
      ['Plone Foundation'], 1)
 ]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}

docs/contributing.rst

@@ -1,5 +1,3 @@
-.. _contributing:
-
 ------------------
 Contributing
 ------------------

docs/index.rst

@@ -21,3 +21,4 @@ Contents
     :titlesonly:
 
     contributing
+    security

docs/security.rst

@@ -0,0 +1,58 @@
+Security Policy
+===============
+
+This documents the security policy and actions to take to secure the package and its deployment and use.
+
+Supported Versions
+------------------
+
+Security vulnerabilities are fixed only for the latest version of ``icalendar``.
+
+.. list-table:: Versions to receive security updates
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Version
+     - Supported
+   * - 6.*
+     - YES
+   * - 5.*
+     - no
+   * - 4.*
+     - no
+   * - before 4.*
+     - no
+
+
+Reporting a Vulnerability
+-------------------------
+
+To report security issues of ``collective/icalendar``, use the ``Report a vulnerability`` button on the project's `Security Page <https://github.com/collective/icalendar/security>`_.
+If you cannot do this, please contact one of the :ref:`maintainers` directly.
+
+The maintainers of ``icalendar`` will then notify `Plone's security team <https://plone.org/security/report>`_.
+
+If we determine that your report may be a security issue with the project, we may contact you for further information.
+We volunteers ask that you delay public disclosure of your report for at least ninety (90) days from the date you report it to us.
+This will allow sufficient time for us to process your report and coordinate disclosure with you.
+
+Once verified and fixed, the following steps will be taken:
+
+-   We will use GitHub's Security Advisory tool to report the issue.
+-   GitHub will review our Security Advisory report for compliance with Common Vulnerabilities and Exposures (CVE) rules.
+    If it is compliant, they will submit it to the MITRE Corporation to generate a `CVE <https://www.cve.org/>`_.
+    This in turn submits the CVE to the `National Vulnerability Database (NVD) <https://nvd.nist.gov/vuln/search>`_.
+    GitHub notifies us of their decision.
+-   Assuming it is compliant, we then publish `our Security Advisory <https://github.com/collective/icalendar/security/advisories>`_ on GitHub, which triggers the next steps.
+-   GitHub will publish the CVE to the CVE List.
+-   GitHub will broadcast our Security Advisory via the `GitHub Advisory Database <https://github.com/advisories>`_.
+-   GitHub will send `security alerts <https://docs.github.com/en/code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/about-alerts-for-vulnerable-dependencies>`_ to all repositories that use our package (and have opted into security alerts).
+    This includes Dependabot alerts.
+-   We will make a bug-fix release.
+-   We will send an announcement through our usual channels:
+
+    - The :ref:`Changelog`
+    - The GitHub releases of ``icalendar``
+    - If possible also `Plone's Security Announcements <https://plone.org/security/announcements>`_
+
+-   We will provide credit to the reporter or researcher in the vulnerability notice.

src/icalendar/prop.py

@@ -1478,40 +1478,62 @@ class vGeo:
 
             GEO:37.386013;-122.082932
 
+        Parse vGeo:
+
         .. code-block:: pycon
 
             >>> from icalendar.prop import vGeo
             >>> geo = vGeo.from_ical('37.386013;-122.082932')
             >>> geo
             (37.386013, -122.082932)
+
+        Add a geo location to an event:
+
+        .. code-block:: pycon
+
+            >>> from icalendar import Event
+            >>> event = Event()
+            >>> latitude = 37.386013
+            >>> longitude = -122.082932
+            >>> event.add('GEO', (latitude, longitude))
+            >>> event['GEO']
+            vGeo((37.386013, -122.082932))
     """
 
-    def __init__(self, geo):
+    def __init__(self, geo: tuple[float|str|int, float|str|int]):
+        """Create a new vGeo from a tuple of (latitude, longitude).
+
+        Raises:
+            ValueError: if geo is not a tuple of (latitude, longitude)
+        """
         try:
             latitude, longitude = (geo[0], geo[1])
             latitude = float(latitude)
             longitude = float(longitude)
-        except Exception:
-            raise ValueError('Input must be (float, float) for '
-                             'latitude and longitude')
+        except Exception as e:
+            raise ValueError("Input must be (float, float) for "
+                             "latitude and longitude") from e
         self.latitude = latitude
         self.longitude = longitude
         self.params = Parameters()
 
     def to_ical(self):
-        return f'{self.latitude};{self.longitude}'
+        return f"{self.latitude};{self.longitude}"
 
     @staticmethod
     def from_ical(ical):
         try:
-            latitude, longitude = ical.split(';')
+            latitude, longitude = ical.split(";")
             return (float(latitude), float(longitude))
-        except Exception:
-            raise ValueError(f"Expected 'float;float' , got: {ical}")
+        except Exception as e:
+            raise ValueError(f"Expected 'float;float' , got: {ical}") from e
 
     def __eq__(self, other):
         return self.to_ical() == other.to_ical()
 
+    def __repr__(self):
+        """repr(self)"""
+        return f"{self.__class__.__name__}(({self.latitude}, {self.longitude}))"
 
 class vUTCOffset:
     """UTC Offset