Deprecate string file paths in Component.from_ical

Right now, if you pass from_ical a single-line string that happens to be
the path of an existing file, it quietly reads that file off disk. That's
surprising and a little risky, so warn when it happens and line the
behaviour up for removal in icalendar 8. To read a file, pass a Path.

Refs #1362

Author: uwezkhan

news/1362.removal

@@ -0,0 +1 @@
+``Component.from_ical`` now warns when you hand it a file path as a string. It still reads the file as before, but this is deprecated: in icalendar 8 a string will always be parsed as calendar data, never treated as a path. If you want to read from a file, pass a :class:`pathlib.Path`. @uwezkhan

src/icalendar/cal/component.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import warnings
 from copy import deepcopy
 from datetime import date, datetime, time, timedelta, timezone
 from pathlib import Path
@@ -22,7 +23,11 @@
 )
 from icalendar.cal.component_factory import ComponentFactory
 from icalendar.caselessdict import CaselessDict
-from icalendar.error import InvalidCalendar, JCalParsingError
+from icalendar.error import (
+    FeatureWillBeRemovedInFutureVersion,
+    InvalidCalendar,
+    JCalParsingError,
+)
 from icalendar.parser import (
     Contentline,
     Contentlines,
@@ -525,7 +530,12 @@ def from_ical(
 
         Parameters:
             st: iCalendar data as bytes or string, or a path to an iCalendar file as
-                :class:`pathlib.Path` or string.
+                :class:`pathlib.Path`.
+
+                .. deprecated:: 7.2.0
+                    Passing a file path as a :class:`str` is deprecated and will be
+                    removed in icalendar 8. A ``str`` will then always be parsed as
+                    iCalendar data. Pass a :class:`pathlib.Path` to read from a file.
             multiple: If ``True``, returns list. If ``False``, returns single component.
 
         Returns:
@@ -543,6 +553,14 @@ def from_ical(
             except OSError:
                 is_file = False
             if is_file:
+                warnings.warn(
+                    "Passing a file path as a string to from_ical() is deprecated "
+                    "and will be removed in icalendar 8. A string will then always "
+                    "be parsed as iCalendar data. Pass a pathlib.Path instead to "
+                    "read iCalendar data from a file.",
+                    FeatureWillBeRemovedInFutureVersion,
+                    stacklevel=2,
+                )
                 st = path.read_bytes()
         parser = cls._get_ical_parser(st)
         components = parser.parse()

src/icalendar/tests/test_issue_756_read_calendar_from_file.py

@@ -3,12 +3,14 @@
 See issue: https://github.com/collective/icalendar/issues/756
 """
 
+import warnings
 from pathlib import Path
 
 import pytest
 
 from icalendar import Calendar
 from icalendar.cal.examples import get_example
+from icalendar.error import FeatureWillBeRemovedInFutureVersion
 
 
 @pytest.fixture
@@ -28,10 +30,19 @@ def test_reading_cal_from_path(dummy_cal):
     assert actual_cal.to_ical() == expected_cal.to_ical()
 
 
+def test_reading_cal_from_path_does_not_warn(dummy_cal):
+    """Reading from a :class:`~pathlib.Path` is the explicit API and must not warn."""
+    _, path = dummy_cal
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", FeatureWillBeRemovedInFutureVersion)
+        Calendar.from_ical(path)
+
+
 def test_reading_cal_from_string_path(dummy_cal):
-    """Test reading a calendar from a valid string path."""
+    """Reading from a string path still works but is deprecated (see issue #1362)."""
     expected_cal, path = dummy_cal
-    actual_cal = Calendar.from_ical(str(path))
+    with pytest.warns(FeatureWillBeRemovedInFutureVersion):
+        actual_cal = Calendar.from_ical(str(path))
 
     assert actual_cal.to_ical() == expected_cal.to_ical()