From 162957b3a1f44b10c39181fddb8fa6f2ed342089 Mon Sep 17 00:00:00 2001 From: Wahaj Ahmed Date: Fri, 8 May 2026 00:14:14 +0200 Subject: [PATCH 1/2] docs: fix broken cross-references in documentation Fixes #1158 - Remove :py: prefix from cross-references in docstrings (:py:class: -> :class:, :py:mod: -> :mod:, :py:meth: -> :meth:) - Fix unqualified references to use fully qualified names (e.g. :class:`BUSYTYPE` -> :class:`icalendar.enums.BUSYTYPE`) - Use tilde-prefixed references for cleaner display (:class:`~icalendar.cal.todo.Todo`) - Affected files: calendar.py, lazy.py, todo.py, caselessdict.py, enums.py, parser/ical/lazy.py, parser/parameter.py, parser/property.py, parser/string.py, prop/dt/date.py, prop/dt/datetime.py, prop/dt/duration.py, prop/dt/time.py --- src/icalendar/cal/calendar.py | 10 +++++----- src/icalendar/cal/lazy.py | 2 +- src/icalendar/cal/todo.py | 2 +- src/icalendar/caselessdict.py | 6 +++--- src/icalendar/enums.py | 4 ++-- src/icalendar/parser/ical/lazy.py | 2 +- src/icalendar/parser/parameter.py | 2 +- src/icalendar/parser/property.py | 4 ++-- src/icalendar/parser/string.py | 14 +++++++------- src/icalendar/prop/dt/date.py | 2 +- src/icalendar/prop/dt/datetime.py | 4 ++-- src/icalendar/prop/dt/duration.py | 2 +- src/icalendar/prop/dt/time.py | 2 +- 13 files changed, 28 insertions(+), 28 deletions(-) diff --git a/src/icalendar/cal/calendar.py b/src/icalendar/cal/calendar.py index e1ec4f049..8e9d763ec 100644 --- a/src/icalendar/cal/calendar.py +++ b/src/icalendar/cal/calendar.py @@ -101,7 +101,7 @@ def events(self) -> list[Event]: This is a shortcut to get all events. Modifications do not change the calendar. - Use :py:meth:`Component.add_component `. + Use :meth:`Component.add_component `. >>> from icalendar import Calendar >>> calendar = Calendar.example() @@ -119,7 +119,7 @@ def todos(self) -> list[Todo]: This is a shortcut to get all todos. Modifications do not change the calendar. - Use :py:meth:`Component.add_component `. + Use :meth:`Component.add_component `. """ return self.walk("VTODO") @@ -129,7 +129,7 @@ def journals(self) -> list[Journal]: This is a shortcut to get all journals. Modifications do not change the calendar. - Use :py:meth:`Component.add_component `. + Use :meth:`Component.add_component `. """ return self.walk("VJOURNAL") @@ -139,7 +139,7 @@ def availabilities(self) -> list[Availability]: This is a shortcut to get all availabilities. Modifications do not change the calendar. - Use :py:meth:`Component.add_component `. + Use :meth:`Component.add_component `. """ return self.walk("VAVAILABILITY") @@ -149,7 +149,7 @@ def freebusy(self) -> list[FreeBusy]: This is a shortcut to get all FreeBusy. Modifications do not change the calendar. - Use :py:meth:`Component.add_component `. + Use :meth:`Component.add_component `. """ return self.walk("VFREEBUSY") diff --git a/src/icalendar/cal/lazy.py b/src/icalendar/cal/lazy.py index 349b0940d..3fdcfa371 100644 --- a/src/icalendar/cal/lazy.py +++ b/src/icalendar/cal/lazy.py @@ -188,7 +188,7 @@ class LazyCalendar(Calendar): >>> calendar.is_lazy() True - When you access all :attr:`subcomponents` of the calendar, + When you access all :attr:`~icalendar.cal.component.Component.subcomponents` of the calendar, for example by getting their count, the entire calendar is parsed and becomes not lazy. diff --git a/src/icalendar/cal/todo.py b/src/icalendar/cal/todo.py index 42840af48..85cde9c34 100644 --- a/src/icalendar/cal/todo.py +++ b/src/icalendar/cal/todo.py @@ -382,7 +382,7 @@ def new( url: The :attr:`url` of the todo. Returns: - :class:`Todo` + :class:`~icalendar.cal.todo.Todo` Raises: ~error.InvalidCalendar: If the content is not valid diff --git a/src/icalendar/caselessdict.py b/src/icalendar/caselessdict.py index f34f92cf4..f91b3d7c7 100644 --- a/src/icalendar/caselessdict.py +++ b/src/icalendar/caselessdict.py @@ -173,7 +173,7 @@ def get(self, key: Any, default: Any = None) -> Any: def setdefault(self, key: Any, value: Any = None) -> Any: """Create the (key, value) pair, optionally with a ``value``. - Once set, to change default value use :meth:`update`. + Once set, to change default value use :meth:`~icalendar.caselessdict.CaselessDict.update`. Parameters: key: The key to look up or create, case-insensitively. @@ -292,7 +292,7 @@ def __ne__(self, other: object) -> bool: def sorted_keys(self) -> list[str]: """Sort keys according to the canonical order for this class. - Keys listed in :attr:`canonical_order` appear first in that order. + Keys listed in :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` appear first in that order. Remaining keys appear alphabetically at the end. Returns: @@ -303,7 +303,7 @@ def sorted_keys(self) -> list[str]: def sorted_items(self) -> list[tuple[Any, Any]]: """Sort items according to the canonical order for this class. - Items whose keys are listed in :attr:`canonical_order` appear first + Items whose keys are listed in :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` appear first in that order. Remaining items appear alphabetically by key. Returns: diff --git a/src/icalendar/enums.py b/src/icalendar/enums.py index bca668e72..040f4819e 100644 --- a/src/icalendar/enums.py +++ b/src/icalendar/enums.py @@ -118,7 +118,7 @@ class FBTYPE(StrEnum): ``BUSY_UNAVAILABLE``, ``BUSY_TENTATIVE`` - See also :class:`BUSYTYPE`. + See also :class:`icalendar.enums.BUSYTYPE`. Purpose: To specify the free or busy time type. @@ -416,7 +416,7 @@ class BUSYTYPE(StrEnum): Description: This property is used to specify the default busy time - type. The values correspond to those used by the :class:`FBTYPE` + type. The values correspond to those used by the :class:`icalendar.enums.FBTYPE` parameter used on a "FREEBUSY" property, with the exception that the "FREE" value is not used in this property. If not specified on a component that allows this property, the default is "BUSY- diff --git a/src/icalendar/parser/ical/lazy.py b/src/icalendar/parser/ical/lazy.py index 61f7773a7..6490a43a5 100644 --- a/src/icalendar/parser/ical/lazy.py +++ b/src/icalendar/parser/ical/lazy.py @@ -128,7 +128,7 @@ def parse(self) -> Component: def is_lazy(self) -> bool: """Return whether the subcomponents were accessed and parsed lazily. - Call :meth:`parse` to get the fully parsed component. + Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully parsed component. """ return True diff --git a/src/icalendar/parser/parameter.py b/src/icalendar/parser/parameter.py index 08a135231..46848bf75 100644 --- a/src/icalendar/parser/parameter.py +++ b/src/icalendar/parser/parameter.py @@ -165,7 +165,7 @@ def q_split(st: str, sep: str = ",", maxsplit: int = -1) -> list[str]: def q_join(lst: Sequence[str], sep: str = ",", always_quote: bool = False) -> str: """Join a list with a separator, quoting items as needed. - Joins list items with the separator, applying :func:`dquote` to each item + Joins list items with the separator, applying :func:`~icalendar.parser.parameter.dquote` to each item to add double quotes when they contain special characters. Parameters: diff --git a/src/icalendar/parser/property.py b/src/icalendar/parser/property.py index 6efca840a..1f25451cc 100644 --- a/src/icalendar/parser/property.py +++ b/src/icalendar/parser/property.py @@ -8,7 +8,7 @@ def unescape_list_or_string(val: str | list[str]) -> str | list[str]: """Unescape a value that may be a string or list of strings. - Applies :func:`_unescape_string` to the value. If the value is a list, + Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value is a list, unescapes each element. Parameters: @@ -28,7 +28,7 @@ def unescape_list_or_string(val: str | list[str]) -> str | list[str]: def unescape_backslash(val: str): r"""Unescape backslash sequences in iCalendar text. - Unlike :py:meth:`unescape_string`, this only handles actual backslash escapes + Unlike :meth:`unescape_string`, this only handles actual backslash escapes per :rfc:`5545`, not URL encoding. This preserves URL-encoded values like ``%3A`` in URLs. diff --git a/src/icalendar/parser/string.py b/src/icalendar/parser/string.py index 96f6d3d66..bfd6a0a49 100644 --- a/src/icalendar/parser/string.py +++ b/src/icalendar/parser/string.py @@ -47,7 +47,7 @@ def escape_char(text: str | bytes) -> str: r"""Format value according to iCalendar TEXT escaping rules. .. deprecated:: 7.0.0 - Use the private :func:`_escape_char` internally. For external use, + Use the private :func:`~icalendar.parser.string._escape_char` internally. For external use, this function is deprecated. Please use alternative escaping methods or contact the maintainers. @@ -84,7 +84,7 @@ def escape_char(text: str | bytes) -> str: def _unescape_char(text: str | bytes) -> str | bytes | None: r"""Unescape iCalendar TEXT values. - Reverses the escaping applied by :func:`_escape_char` according to + Reverses the escaping applied by :func:`~icalendar.parser.string._escape_char` according to :rfc:`5545#section-3.3.11` TEXT escaping rules. Parameters: @@ -130,11 +130,11 @@ def unescape_char(text: str | bytes) -> str | bytes | None: r"""Unescape iCalendar TEXT values. .. deprecated:: 7.0.0 - Use the private :func:`_unescape_char` internally. For external use, + Use the private :func:`~icalendar.parser.string._unescape_char` internally. For external use, this function is deprecated. Please use alternative unescaping methods or contact the maintainers. - Reverses the escaping applied by :func:`escape_char` according to + Reverses the escaping applied by :func:`~icalendar.parser.string.escape_char` according to :rfc:`5545#section-3.3.11` TEXT escaping rules. Parameters: @@ -231,7 +231,7 @@ def escape_string(val: str) -> str: r"""Escape backslash sequences to URL-encoded hex values. .. deprecated:: 7.0.0 - Use the private :func:`_escape_string` internally. For external use, + Use the private :func:`~icalendar.parser.string._escape_string` internally. For external use, this function is deprecated. """ warnings.warn( @@ -246,7 +246,7 @@ def escape_string(val: str) -> str: def _unescape_string(val: str) -> str: r"""Unescape URL-encoded hex values to their original characters. - Reverses :func:`_escape_string` by converting percent-encoded hex values + Reverses :func:`~icalendar.parser.string._escape_string` by converting percent-encoded hex values back to their original characters. This is used for parameter parsing. Parameters: @@ -275,7 +275,7 @@ def unescape_string(val: str) -> str: r"""Unescape URL-encoded hex values to their original characters. .. deprecated:: 7.0.0 - Use the private :func:`_unescape_string` internally. For external use, + Use the private :func:`~icalendar.parser.string._unescape_string` internally. For external use, this function is deprecated. """ warnings.warn( diff --git a/src/icalendar/prop/dt/date.py b/src/icalendar/prop/dt/date.py index 40ee2e076..c17565ba0 100644 --- a/src/icalendar/prop/dt/date.py +++ b/src/icalendar/prop/dt/date.py @@ -104,7 +104,7 @@ def to_jcal(self, name: str) -> list: @classmethod def parse_jcal_value(cls, jcal: str) -> date: - """Parse a jCal string to a :py:class:`datetime.date`. + """Parse a jCal string to a :class:`datetime.date`. Raises: ~error.JCalParsingError: If it can't parse a date. diff --git a/src/icalendar/prop/dt/datetime.py b/src/icalendar/prop/dt/datetime.py index 88178e4d6..238145d08 100644 --- a/src/icalendar/prop/dt/datetime.py +++ b/src/icalendar/prop/dt/datetime.py @@ -52,7 +52,7 @@ class vDatetime(TimeBase): vDatetime is timezone aware and uses a timezone library. When a vDatetime object is created from an ical string, you can pass a valid timezone identifier. When a - vDatetime object is created from a Python :py:mod:`datetime` object, it uses the + vDatetime object is created from a Python :mod:`datetime` object, it uses the tzinfo component, if present. Otherwise a timezone-naive object is created. Be aware that there are certain limitations with timezone naive DATE-TIME components in the icalendar standard. @@ -155,7 +155,7 @@ def is_utc(self) -> bool: @classmethod def parse_jcal_value(cls, jcal: str) -> datetime: - """Parse a jCal string to a :py:class:`datetime.datetime`. + """Parse a jCal string to a :class:`datetime.datetime`. Raises: ~error.JCalParsingError: If it can't parse a date-time value. diff --git a/src/icalendar/prop/dt/duration.py b/src/icalendar/prop/dt/duration.py index 871ca5a48..ce87e0d40 100644 --- a/src/icalendar/prop/dt/duration.py +++ b/src/icalendar/prop/dt/duration.py @@ -166,7 +166,7 @@ def to_jcal(self, name: str) -> list: @classmethod def parse_jcal_value(cls, jcal: str) -> timedelta: - """Parse a jCal string to a :py:class:`datetime.timedelta`. + """Parse a jCal string to a :class:`datetime.timedelta`. Raises: ~error.JCalParsingError: If it can't parse a duration.""" diff --git a/src/icalendar/prop/dt/time.py b/src/icalendar/prop/dt/time.py index a592bf00d..fde4e4e51 100644 --- a/src/icalendar/prop/dt/time.py +++ b/src/icalendar/prop/dt/time.py @@ -204,7 +204,7 @@ def to_jcal(self, name: str) -> list: @classmethod def parse_jcal_value(cls, jcal: str) -> time: - """Parse a jCal string to a :py:class:`datetime.time`. + """Parse a jCal string to a :class:`datetime.time`. Raises: ~error.JCalParsingError: If it can't parse a time. From 70440f3130e53eca5a02360f78d6771caaae988a Mon Sep 17 00:00:00 2001 From: Wahaj Ahmed Date: Thu, 14 May 2026 13:31:28 +0200 Subject: [PATCH 2/2] fix: resolve ruff E501 line-length errors and add changelog entry --- CHANGES.rst | 1 + src/icalendar/caselessdict.py | 9 ++++++--- src/icalendar/enums.py | 3 ++- src/icalendar/parser/ical/lazy.py | 3 ++- src/icalendar/parser/parameter.py | 3 ++- src/icalendar/parser/property.py | 3 ++- src/icalendar/parser/string.py | 21 ++++++++++++++------- 7 files changed, 29 insertions(+), 14 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 8b5040c01..30d06b4b0 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -10,6 +10,7 @@ Change log Minor changes ~~~~~~~~~~~~~ +- Fix broken cross-references in documentation by replacing ``:py:`` prefixed roles with standard Sphinx roles and qualifying ambiguous references. See `#1158 `_ - ... Breaking changes diff --git a/src/icalendar/caselessdict.py b/src/icalendar/caselessdict.py index f91b3d7c7..0f338af21 100644 --- a/src/icalendar/caselessdict.py +++ b/src/icalendar/caselessdict.py @@ -173,7 +173,8 @@ def get(self, key: Any, default: Any = None) -> Any: def setdefault(self, key: Any, value: Any = None) -> Any: """Create the (key, value) pair, optionally with a ``value``. - Once set, to change default value use :meth:`~icalendar.caselessdict.CaselessDict.update`. + Once set, to change default value use + :meth:`~icalendar.caselessdict.CaselessDict.update`. Parameters: key: The key to look up or create, case-insensitively. @@ -292,7 +293,8 @@ def __ne__(self, other: object) -> bool: def sorted_keys(self) -> list[str]: """Sort keys according to the canonical order for this class. - Keys listed in :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` appear first in that order. + Keys listed in :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` + appear first in that order. Remaining keys appear alphabetically at the end. Returns: @@ -303,7 +305,8 @@ def sorted_keys(self) -> list[str]: def sorted_items(self) -> list[tuple[Any, Any]]: """Sort items according to the canonical order for this class. - Items whose keys are listed in :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` appear first + Items whose keys are listed in + :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` appear first in that order. Remaining items appear alphabetically by key. Returns: diff --git a/src/icalendar/enums.py b/src/icalendar/enums.py index 040f4819e..52c2f0d55 100644 --- a/src/icalendar/enums.py +++ b/src/icalendar/enums.py @@ -416,7 +416,8 @@ class BUSYTYPE(StrEnum): Description: This property is used to specify the default busy time - type. The values correspond to those used by the :class:`icalendar.enums.FBTYPE` + type. The values correspond to those used by the + :class:`icalendar.enums.FBTYPE` parameter used on a "FREEBUSY" property, with the exception that the "FREE" value is not used in this property. If not specified on a component that allows this property, the default is "BUSY- diff --git a/src/icalendar/parser/ical/lazy.py b/src/icalendar/parser/ical/lazy.py index 6490a43a5..73ab19146 100644 --- a/src/icalendar/parser/ical/lazy.py +++ b/src/icalendar/parser/ical/lazy.py @@ -128,7 +128,8 @@ def parse(self) -> Component: def is_lazy(self) -> bool: """Return whether the subcomponents were accessed and parsed lazily. - Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully parsed component. + Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully + parsed component. """ return True diff --git a/src/icalendar/parser/parameter.py b/src/icalendar/parser/parameter.py index 46848bf75..c9d56ef78 100644 --- a/src/icalendar/parser/parameter.py +++ b/src/icalendar/parser/parameter.py @@ -165,7 +165,8 @@ def q_split(st: str, sep: str = ",", maxsplit: int = -1) -> list[str]: def q_join(lst: Sequence[str], sep: str = ",", always_quote: bool = False) -> str: """Join a list with a separator, quoting items as needed. - Joins list items with the separator, applying :func:`~icalendar.parser.parameter.dquote` to each item + Joins list items with the separator, applying + :func:`~icalendar.parser.parameter.dquote` to each item to add double quotes when they contain special characters. Parameters: diff --git a/src/icalendar/parser/property.py b/src/icalendar/parser/property.py index 1f25451cc..5c76e5bc6 100644 --- a/src/icalendar/parser/property.py +++ b/src/icalendar/parser/property.py @@ -8,7 +8,8 @@ def unescape_list_or_string(val: str | list[str]) -> str | list[str]: """Unescape a value that may be a string or list of strings. - Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value is a list, + Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value + is a list, unescapes each element. Parameters: diff --git a/src/icalendar/parser/string.py b/src/icalendar/parser/string.py index bfd6a0a49..2d4cce366 100644 --- a/src/icalendar/parser/string.py +++ b/src/icalendar/parser/string.py @@ -47,7 +47,8 @@ def escape_char(text: str | bytes) -> str: r"""Format value according to iCalendar TEXT escaping rules. .. deprecated:: 7.0.0 - Use the private :func:`~icalendar.parser.string._escape_char` internally. For external use, + Use the private :func:`~icalendar.parser.string._escape_char` internally. For + external use, this function is deprecated. Please use alternative escaping methods or contact the maintainers. @@ -84,7 +85,8 @@ def escape_char(text: str | bytes) -> str: def _unescape_char(text: str | bytes) -> str | bytes | None: r"""Unescape iCalendar TEXT values. - Reverses the escaping applied by :func:`~icalendar.parser.string._escape_char` according to + Reverses the escaping applied by :func:`~icalendar.parser.string._escape_char` + according to :rfc:`5545#section-3.3.11` TEXT escaping rules. Parameters: @@ -130,11 +132,13 @@ def unescape_char(text: str | bytes) -> str | bytes | None: r"""Unescape iCalendar TEXT values. .. deprecated:: 7.0.0 - Use the private :func:`~icalendar.parser.string._unescape_char` internally. For external use, + Use the private :func:`~icalendar.parser.string._unescape_char` internally. For + external use, this function is deprecated. Please use alternative unescaping methods or contact the maintainers. - Reverses the escaping applied by :func:`~icalendar.parser.string.escape_char` according to + Reverses the escaping applied by :func:`~icalendar.parser.string.escape_char` + according to :rfc:`5545#section-3.3.11` TEXT escaping rules. Parameters: @@ -231,7 +235,8 @@ def escape_string(val: str) -> str: r"""Escape backslash sequences to URL-encoded hex values. .. deprecated:: 7.0.0 - Use the private :func:`~icalendar.parser.string._escape_string` internally. For external use, + Use the private :func:`~icalendar.parser.string._escape_string` internally. For + external use, this function is deprecated. """ warnings.warn( @@ -246,7 +251,8 @@ def escape_string(val: str) -> str: def _unescape_string(val: str) -> str: r"""Unescape URL-encoded hex values to their original characters. - Reverses :func:`~icalendar.parser.string._escape_string` by converting percent-encoded hex values + Reverses :func:`~icalendar.parser.string._escape_string` by converting + percent-encoded hex values back to their original characters. This is used for parameter parsing. Parameters: @@ -275,7 +281,8 @@ def unescape_string(val: str) -> str: r"""Unescape URL-encoded hex values to their original characters. .. deprecated:: 7.0.0 - Use the private :func:`~icalendar.parser.string._unescape_string` internally. For external use, + Use the private :func:`~icalendar.parser.string._unescape_string` internally. + For external use, this function is deprecated. """ warnings.warn(