From af3156085d0acd33905945e768b44191a5761838 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 18 Nov 2026 23:01:19 -0800 Subject: [PATCH 1/4] Documented and standardize "private" or "internal use only" methods with Sphinx ``:meta private:`` field flag. - If a private method already had a docstring, inserted the flag. Else did nothing. - If an ``__init__`` method contained docstrings, merged it with its class. - Added missing Parameters section as needed. - Added "Required." flag as needed. - Sorted parameters as needed. Closes #1711 --- news/1711.documentation | 1 + src/icalendar/alarms.py | 53 ++++-- src/icalendar/attr/__init__.py | 184 ++++++++++++++++----- src/icalendar/attr/property_list.py | 65 ++++++-- src/icalendar/cal/alarm.py | 8 + src/icalendar/cal/calendar.py | 5 +- src/icalendar/cal/component.py | 54 +++++- src/icalendar/cal/component_factory.py | 3 +- src/icalendar/cal/event.py | 5 +- src/icalendar/cal/lazy.py | 11 +- src/icalendar/cal/timezone.py | 6 +- src/icalendar/cal/todo.py | 5 +- src/icalendar/caselessdict.py | 44 +++-- src/icalendar/cli.py | 4 + src/icalendar/config.py | 6 +- src/icalendar/enums.py | 7 +- src/icalendar/error.py | 40 +++-- src/icalendar/param.py | 65 +++++--- src/icalendar/parser/content_line.py | 2 + src/icalendar/parser/ical/component.py | 15 +- src/icalendar/parser/ical/lazy.py | 1 - src/icalendar/parser/parameter.py | 17 +- src/icalendar/parser/string.py | 10 ++ src/icalendar/parser/xcal/adapter.py | 5 +- src/icalendar/parser/xcal/base.py | 7 +- src/icalendar/parser/xcal/string.py | 7 +- src/icalendar/prop/adr.py | 22 ++- src/icalendar/prop/binary.py | 10 +- src/icalendar/prop/broken.py | 2 + src/icalendar/prop/cal_address.py | 11 +- src/icalendar/prop/categories.py | 15 +- src/icalendar/prop/dt/base.py | 12 +- src/icalendar/prop/dt/list.py | 5 +- src/icalendar/prop/dt/period.py | 6 +- src/icalendar/prop/dt/types.py | 5 +- src/icalendar/prop/empty.py | 5 +- src/icalendar/prop/factory.py | 5 +- src/icalendar/prop/float.py | 2 + src/icalendar/prop/geo.py | 61 +++---- src/icalendar/prop/image.py | 31 +--- src/icalendar/prop/n.py | 22 ++- src/icalendar/prop/org.py | 22 ++- src/icalendar/prop/recur/month.py | 10 +- src/icalendar/prop/recur/recur.py | 28 +++- src/icalendar/prop/request_status.py | 10 +- src/icalendar/prop/text.py | 2 + src/icalendar/prop/uid.py | 5 +- src/icalendar/prop/uri.py | 5 +- src/icalendar/prop/xml.py | 28 +++- src/icalendar/tests/test_jcal_recursion.py | 2 +- src/icalendar/timezone/tzid.py | 8 +- src/icalendar/timezone/tzp.py | 10 +- src/icalendar/timezone/zoneinfo.py | 10 +- 53 files changed, 694 insertions(+), 290 deletions(-) create mode 100644 news/1711.documentation diff --git a/news/1711.documentation b/news/1711.documentation new file mode 100644 index 000000000..12a95ff6f --- /dev/null +++ b/news/1711.documentation @@ -0,0 +1 @@ +Documented and standardize "private" or "internal use only" methods with Sphinx ``:meta private:`` field flag. :user:`stevepiercy` \ No newline at end of file diff --git a/src/icalendar/alarms.py b/src/icalendar/alarms.py index 75bfb1d0a..36506a0de 100644 --- a/src/icalendar/alarms.py +++ b/src/icalendar/alarms.py @@ -44,6 +44,17 @@ class AlarmTime: An AlarmTime instance combines an alarm component with its resolved trigger time and additional state information, such as acknowledgment and snoozing. + + Create an instance of ``AlarmTime`` with any of its parameters. + + Parameters: + alarm: Required. The underlying alarm component. + trigger: Required. A date or datetime at which to trigger the alarm. + acknowledged_until: Optional datetime in UTC until which + the alarm has been acknowledged. + parent: Optional parent component to which the alarm refers. + snoozed_until: Optional datetime in UTC until which + the alarm has been snoozed. """ def __init__( @@ -54,17 +65,6 @@ def __init__( snoozed_until: datetime | None = None, parent: Parent | None = None, ) -> None: - """Create an instance of ``AlarmTime`` with any of its parameters. - - Parameters: - alarm: The underlying alarm component. - trigger: A date or datetime at which to trigger the alarm. - acknowledged_until: Optional datetime in UTC until which - the alarm has been acknowledged. - snoozed_until: Optional datetime in UTC until which - the alarm has been snoozed. - parent: Optional parent component to which the alarm refers. - """ self._alarm = alarm self._parent = parent self._trigger = trigger @@ -230,7 +230,6 @@ class Alarms: """ def __init__(self, component: Alarm | Event | Todo | None = None) -> None: - """Start computing alarm times.""" self._absolute_alarms: list[Alarm] = [] self._start_alarms: list[Alarm] = [] self._end_alarms: list[Alarm] = [] @@ -308,7 +307,10 @@ def _add(self, dt: datetime, td: timedelta) -> datetime: ... def _add(self, dt: date, td: timedelta) -> date: ... def _add(self, dt: date, td: timedelta) -> date | datetime: - """Add a timedelta to a datetime.""" + """Add a timedelta to a datetime. + + :meta private: + """ if is_date(dt): if td.seconds == 0: return dt + td @@ -369,7 +371,10 @@ def times(self) -> list[AlarmTime]: ) def _repeat(self, first: datetime, alarm: Alarm) -> Generator[datetime]: - """The times when the alarm is triggered relative to start.""" + """The times when the alarm is triggered relative to start. + + :meta private: + """ yield first # we trigger at the start repeat = alarm.repeat duration = alarm.DURATION @@ -378,7 +383,10 @@ def _repeat(self, first: datetime, alarm: Alarm) -> Generator[datetime]: yield self._add(first, duration * i) def _alarm_time(self, alarm: Alarm, trigger: date) -> AlarmTime: - """Create an alarm time with the additional attributes.""" + """Create an alarm time with the additional attributes. + + :meta private: + """ if getattr(trigger, "tzinfo", None) is None and self._local_tzinfo is not None: trigger = normalize_pytz(trigger.replace(tzinfo=self._local_tzinfo)) return AlarmTime( @@ -386,7 +394,10 @@ def _alarm_time(self, alarm: Alarm, trigger: date) -> AlarmTime: ) def _get_absolute_alarm_times(self) -> list[AlarmTime]: - """Return a list of absolute alarm times.""" + """Return a list of absolute alarm times. + + :meta private: + """ return [ self._alarm_time(alarm, trigger) for alarm in self._absolute_alarms @@ -394,7 +405,10 @@ def _get_absolute_alarm_times(self) -> list[AlarmTime]: ] def _get_start_alarm_times(self) -> list[AlarmTime]: - """Return a list of alarm times relative to the start of the component.""" + """Return a list of alarm times relative to the start of the component. + + :meta private: + """ if self._start is None and self._start_alarms: raise ComponentStartMissing( "Use Alarms.set_start because at least one alarm is relative to the " @@ -407,7 +421,10 @@ def _get_start_alarm_times(self) -> list[AlarmTime]: ] def _get_end_alarm_times(self) -> list[AlarmTime]: - """Return a list of alarm times relative to the end of the component.""" + """Return a list of alarm times relative to the end of the component. + + :meta private: + """ if self._end is None and self._end_alarms: raise ComponentEndMissing( "Use Alarms.set_end because at least one alarm is relative to the end " diff --git a/src/icalendar/attr/__init__.py b/src/icalendar/attr/__init__.py index f55042b7c..08408cbc9 100644 --- a/src/icalendar/attr/__init__.py +++ b/src/icalendar/attr/__init__.py @@ -42,6 +42,8 @@ def _get_rdates( ) -> list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]: """The RDATE property defines the list of DATE-TIME values for recurring components. + :meta private: + RDATE is defined in :rfc:`5545`. The return value is a list of tuples ``(start, end)``. @@ -94,7 +96,7 @@ def _get_rdates( Duplicate instances are ignored. Example: - Below, we set one RDATE in a list and get the resulting tuple of start and end. + Set one RDATE in a list, and get the resulting tuple of start and end. .. code-block:: pycon @@ -112,7 +114,7 @@ def _get_rdates( Modifying the returned list does not change the RDATE value. Assign to ``rdates`` for the relevant component or use :meth:`Component.add ` instead. - If you want to compute recurrences, have a look at + If you want to compute recurrences, see `Related Projects `_. """ @@ -136,9 +138,12 @@ def _get_rdates( def _set_rdates(self: Component, value) -> None: """Set the RDATE values, replacing any existing ones. - ``value`` is a list as returned by :attr:`rdates` (each item a date, a - datetime, or a ``(start, end)`` period tuple). Setting an empty list or - :obj:`None` removes the RDATE property. + :meta private: + + Parameters: + value: A list, as returned by :attr:`rdates`, where each item is either a date, + a datetime, or a ``(start, end)`` period tuple. Setting an empty list or + :obj:`None` removes the RDATE property. """ _del_rdates(self) if value: @@ -146,7 +151,10 @@ def _set_rdates(self: Component, value) -> None: def _del_rdates(self: Component) -> None: - """Delete all RDATE values.""" + """Delete all RDATE values. + + :meta private: + """ self.pop("RDATE", None) @@ -154,9 +162,10 @@ def _del_rdates(self: Component) -> None: def _get_exdates(self: Component) -> list[date | datetime]: - """EXDATE defines the list of DATE-TIME exceptions for recurring components. + """EXDATE defines the list of DATE-TIME exceptions for recurring components + according to :rfc:`5545`. - EXDATE is defined in :rfc:`5545`. + :meta private: Value Type: The default value type for this property is DATE-TIME. @@ -201,7 +210,7 @@ def _get_exdates(self: Component) -> list[date | datetime]: dependencies by other properties such as the "RECURRENCE-ID". Example: - Below, we add an exdate in a list and get the resulting list of exdates. + Add an EXDATE in a list, and get the resulting list of EXDATEs. .. code-block:: pycon @@ -219,7 +228,7 @@ def _get_exdates(self: Component) -> list[date | datetime]: Modifying the returned list does not change the EXDATE value. Assign to ``exdates`` for the relevant component or use :meth:`Component.add ` instead. - If you want to compute recurrences, have a look at + If you want to compute recurrences, see `Related Projects `_. """ @@ -236,8 +245,11 @@ def _get_exdates(self: Component) -> list[date | datetime]: def _set_exdates(self: Component, value) -> None: """Set the EXDATE values, replacing any existing ones. - ``value`` is a list as returned by :attr:`exdates` (each item a date or a - datetime). Setting an empty list or :obj:`None` removes the EXDATE property. + :meta private: + + Parameters: + value: A list, as returned by :attr:`exdates`, where each item is a date + or a datetime. Setting an empty list or :obj:`None` removes the EXDATE property. """ _del_exdates(self) if value: @@ -245,7 +257,10 @@ def _set_exdates(self: Component, value) -> None: def _del_exdates(self: Component) -> None: - """Delete all EXDATE values.""" + """Delete all EXDATE values. + + :meta private: + """ self.pop("EXDATE", None) @@ -255,6 +270,8 @@ def _del_exdates(self: Component) -> None: def _get_rrules(self: Component) -> list[vRecur]: """RRULE defines a rule or repeating pattern for recurring components. + :meta private: + RRULE is defined in :rfc:`5545`. :rfc:`7529` adds the ``SKIP`` parameter :class:`icalendar.prop.vSkip`. @@ -451,6 +468,12 @@ def fdel(self: Component): def _decode_single_utc_value(name: str, value: object) -> date | datetime: """Extract and check one datetime value of a singleton UTC property. + :meta private: + + Parameters: + name: The name of the property. + value: The value of the property. + Raises: ValueError: If a text or unknown value cannot be parsed. InvalidCalendar: If the decoded value is not a date or datetime. @@ -672,7 +695,13 @@ def fdel(self: Component): def _get_categories(component: Component) -> list[str]: - """Get all the categories.""" + """Get all the categories. + + :meta private: + + Parameters: + component: Required. The component from which to extract its categories. + """ categories: vCategory | list[vCategory] | None = component.get("CATEGORIES") if isinstance(categories, list): _set_categories( @@ -687,7 +716,14 @@ def _get_categories(component: Component) -> list[str]: def _set_categories(component: Component, cats: Sequence[str] | None) -> None: - """Set the categories.""" + """Set the categories. + + :meta private: + + Parameters: + cats: Required. The categories to set in the component. + component: Required. The component in which to set categories. + """ if not cats and cats != []: _del_categories(component) return @@ -699,7 +735,13 @@ def _set_categories(component: Component, cats: Sequence[str] | None) -> None: def _del_categories(component: Component) -> None: - """Delete the categories.""" + """Delete the categories. + + :meta private: + + Parameters: + component: The component from which to remove its categories. + """ component.pop("CATEGORIES", None) @@ -761,7 +803,10 @@ def _del_categories(component: Component) -> None: def _get_attendees(self: Component) -> list[vCalAddress]: - """Get attendees.""" + """Get attendees. + + :meta private: + """ value = self.get("ATTENDEE") if value is None: value = [] @@ -776,7 +821,13 @@ def _get_attendees(self: Component) -> list[vCalAddress]: def _set_attendees(self: Component, value: ATTENDEE_TYPE_SETTER): - """Set attendees.""" + """Set attendees. + + :meta private: + + Parameters: + value: Required. The attendee type to use when setting attendees. + """ _del_attendees(self) if value is None: return @@ -792,7 +843,10 @@ def _set_attendees(self: Component, value: ATTENDEE_TYPE_SETTER): def _del_attendees(self: Component): - """Delete all attendees.""" + """Delete all attendees. + + :meta private: + """ self.pop("ATTENDEE", None) @@ -1273,10 +1327,7 @@ def fdel(self: Component): def _get_organizer(self: Component) -> vCalAddress | None: """ORGANIZER defines the organizer for a calendar component. - Property Parameters: - IANA, non-standard, language, common name, - directory entry reference, and sent-by property parameters can be - specified on this property. + :meta private: Conformance: This property MUST be specified in an iCalendar object @@ -1310,14 +1361,20 @@ def _get_organizer(self: Component) -> vCalAddress | None: def _set_organizer(self: Component, value: vCalAddress | str | None): - """Set the value.""" + """Set the value. + + :meta private: + """ _del_organizer(self) if value is not None: self.add("ORGANIZER", value) def _del_organizer(self: Component): - """Delete the value.""" + """Delete the value. + + :meta private: + """ self.pop("ORGANIZER") @@ -1713,7 +1770,10 @@ def fget(self): def _timezone_datetime_property(name: str, docs: str): - """Create a property to access the values with a proper timezone.""" + """Create a property to access the values with a proper timezone. + + :meta private: + """ return single_utc_property(name, docs) @@ -2096,6 +2156,8 @@ def set_end_with_locking( def _get_images(self: Component) -> list[Image]: """IMAGE specifies an image associated with the calendar or a calendar component. + :meta private: + Description: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline @@ -2119,7 +2181,7 @@ def _get_images(self: Component) -> list[Image]: .. note:: At the present moment, this property is read-only. If you require a setter, - please open an issue or a pull request. + open an issue or a pull request. """ images = self.get("IMAGE", []) if not isinstance(images, SEQUENCE_TYPES): @@ -2133,6 +2195,8 @@ def _get_images(self: Component) -> list[Image]: def _get_conferences(self: Component) -> list[Conference]: """Return the CONFERENCE properties as a list. + :meta private: + Purpose: This property specifies information for accessing a conferencing system. @@ -2223,14 +2287,20 @@ def _get_conferences(self: Component) -> list[Conference]: def _set_conferences(self: Component, conferences: list[Conference] | None): - """Set the conferences.""" + """Set the conferences + + :meta private: + """ _del_conferences(self) for conference in conferences or []: self.add("CONFERENCE", conference.to_uri()) def _del_conferences(self: Component): - """Delete all conferences.""" + """Delete all conferences. + + :meta private: + """ self.pop("CONFERENCE") @@ -2240,6 +2310,8 @@ def _del_conferences(self: Component): def _get_links(self: Component) -> list[vUri | vUid | vXmlReference]: """LINK properties as a list. + :meta private: + Purpose: LINK provides a reference to external information related to a component. @@ -2355,7 +2427,10 @@ def _get_links(self: Component) -> list[vUri | vUid | vXmlReference]: def _set_links(self: Component, links: LINKS_TYPE_SETTER) -> None: - """Set the LINKs.""" + """Set the LINKs. + + :meta private: + """ _del_links(self) if links is None: return @@ -2368,7 +2443,10 @@ def _set_links(self: Component, links: LINKS_TYPE_SETTER) -> None: def _del_links(self: Component) -> None: - """Delete all links.""" + """Delete all links. + + :meta private: + """ self.pop("LINK") @@ -2382,6 +2460,8 @@ def _del_links(self: Component) -> None: def _get_related_to(self: Component) -> list[vText | vUri | vUid]: """RELATED-TO properties as a list. + :meta private: + Purpose: This property is used to represent a relationship or reference between one calendar component and another. @@ -2508,12 +2588,18 @@ def _get_related_to(self: Component) -> list[vText | vUri | vUid]: def _set_related_to(self: Component, values: RELATED_TO_TYPE_SETTER) -> None: - """Set the RELATED-TO properties.""" + """Set the RELATED-TO properties. + + :meta private: + """ PropertyListView(self, "RELATED-TO").replace_with(values) def _del_related_to(self: Component): - """Delete the RELATED-TO properties.""" + """Delete the RELATED-TO properties. + + :meta private: + """ PropertyListView(self, "RELATED-TO").clear() @@ -2523,6 +2609,8 @@ def _del_related_to(self: Component): def _get_concepts(self: Component) -> list[vUri]: """CONCEPT + :meta private: + Purpose: CONCEPT defines the formal categories for a calendar component. @@ -2565,12 +2653,18 @@ def _get_concepts(self: Component) -> list[vUri]: def _set_concepts(self: Component, concepts: CONCEPTS_TYPE_SETTER): - """Set the concepts.""" + """Set the concepts. + + :meta private: + """ PropertyListView(self, "CONCEPT").replace_with(concepts) def _del_concepts(self: Component): - """Delete the concepts.""" + """Delete the concepts. + + :meta private: + """ PropertyListView(self, "CONCEPT").clear() @@ -2805,7 +2899,10 @@ def fdel(self: Component): def _normalize_attachment(value: str | bytes | vUri | vBinary) -> vUri | vBinary: - """Convert one attachment value.""" + """Convert one attachment value. + + :meta private: + """ if isinstance(value, (vUri, vBinary)): return value if isinstance(value, str): @@ -2818,7 +2915,10 @@ def _normalize_attachment(value: str | bytes | vUri | vBinary) -> vUri | vBinary def _get_attachments(self: Component) -> list[vUri | vBinary]: - """Get all the attachments""" + """Get all the attachments. + + :meta private: + """ attachments = self.get("ATTACH", []) if not isinstance(attachments, SEQUENCE_TYPES): return [attachments] @@ -2826,7 +2926,10 @@ def _get_attachments(self: Component) -> list[vUri | vBinary]: def _set_attachments(self: Component, value: ATTACHMENTS_TYPE_SETTER) -> None: - """Set attachments properties""" + """Set attachments properties. + + :meta private: + """ if value is None: _del_attachments(self) return @@ -2839,7 +2942,10 @@ def _set_attachments(self: Component, value: ATTACHMENTS_TYPE_SETTER) -> None: def _del_attachments(self: Component) -> None: - """Delete all attachments""" + """Delete all attachments. + + :meta private: + """ self.pop("ATTACH", None) diff --git a/src/icalendar/attr/property_list.py b/src/icalendar/attr/property_list.py index cda253fd0..fa610d83a 100644 --- a/src/icalendar/attr/property_list.py +++ b/src/icalendar/attr/property_list.py @@ -17,23 +17,24 @@ class PropertyListView(MutableSequence): This view synchronizes modifications, such as ``append``, ``extend``, ``insert``, ``clear``, and ``delete``, with the underlying component dictionary. + + Parameters: + component: The component to view. + name: The name of the property to view. """ __hash__ = None def __init__(self, component: Component, name: str) -> None: - """Initialize the property list view for a given component and property name. - - Parameters: - component: The component to view. - name: The name of the property to view. - """ self._component = component self._name = name @contextlib.contextmanager def _values(self) -> Iterator[list[Any]]: - """Synchronize the value list with the component.""" + """Synchronize the value list with the component. + + :meta private: + """ raw = self._component.get(self._name, []) values = [raw] if not isinstance(raw, list) else list(raw) try: @@ -45,22 +46,34 @@ def _values(self) -> Iterator[list[Any]]: self._component[self._name] = values def __getitem__(self, index: Any) -> Any: - """Get an item or slice from the property list.""" + """Get an item or slice from the property list. + + :meta private: + """ with self._values() as values: return values[index] def __setitem__(self, index: Any, value: Any) -> None: - """Set an item or slice in the property list.""" + """Set an item or slice in the property list. + + :meta private: + """ with self._values() as values: values[index] = value def __delitem__(self, index: Any) -> None: - """Delete an item or slice from the property list.""" + """Delete an item or slice from the property list. + + :meta private: + """ with self._values() as values: del values[index] def __len__(self) -> int: - """Return the number of items in the property list.""" + """Return the number of items in the property list. + + :meta private: + """ raw = self._component.get(self._name, []) if not raw: return 0 @@ -107,7 +120,10 @@ def replace_with(self, values: Any) -> None: self._component.add(self._name, value) def __eq__(self, other: object) -> bool: - """Check equality against another sequence.""" + """Check equality against another sequence. + + :meta private: + """ if isinstance(other, PropertyListView): return list(self) == list(other) if hasattr(other, "__iter__"): @@ -115,29 +131,44 @@ def __eq__(self, other: object) -> bool: return False def __repr__(self) -> str: - """Return the string representation of the property list view.""" + """Return the string representation of the property list view. + + :meta private: + """ return f"PropertyListView({list(self)!r})" def __add__(self, other: Any) -> list[Any]: - """Concatenate this list with a sequence and return a new list.""" + """Concatenate this list with a sequence and return a new list. + + :meta private: + """ if isinstance(other, Sequence) and not isinstance(other, (str, bytes)): return list(self) + list(other) return NotImplemented def __radd__(self, other: Any) -> list[Any]: - """Concatenate a sequence with this list and return a new list.""" + """Concatenate a sequence with this list and return a new list. + + :meta private: + """ if isinstance(other, Sequence) and not isinstance(other, (str, bytes)): return list(other) + list(self) return NotImplemented def __mul__(self, n: int) -> list[Any]: - """Multiply the property list by an integer to return a new repeated list.""" + """Multiply the property list by an integer to return a new repeated list. + + :meta private: + """ if isinstance(n, int): return list(self) * n return NotImplemented def __rmul__(self, n: int) -> list[Any]: - """Multiply the property list by an integer to return a new repeated list.""" + """Multiply the property list by an integer to return a new repeated list. + + :meta private: + """ if isinstance(n, int): return list(self) * n return NotImplemented diff --git a/src/icalendar/cal/alarm.py b/src/icalendar/cal/alarm.py index 9349dcd49..a6a3c7a15 100644 --- a/src/icalendar/cal/alarm.py +++ b/src/icalendar/cal/alarm.py @@ -462,6 +462,14 @@ def _apply_duration_repeat( duration: timedelta | None, repeat: int | None, ) -> None: + """Apply a repeating duration to an alarm. + + :meta private: + + Parameters: + duration: The duration to repeat. + repeat: The number of times to repeat the duration. + """ if duration is not None or repeat is not None: if duration is None or repeat is None: raise InvalidCalendar( diff --git a/src/icalendar/cal/calendar.py b/src/icalendar/cal/calendar.py index cbff14632..30c880599 100644 --- a/src/icalendar/cal/calendar.py +++ b/src/icalendar/cal/calendar.py @@ -157,7 +157,10 @@ def example(cls, name: str = "example") -> Calendar: @classmethod def _get_ical_parser(cls, st: str | bytes) -> ComponentIcalParser: - """Get the iCal parser for the given input string.""" + """Get the iCal parser for the given input string. + + :meta private: + """ return CalendarIcalParser(st, cls._get_component_factory(), cls.types_factory) @overload diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index 953160cc6..ce7eb66d7 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -76,6 +76,8 @@ class Component(CaselessDict): Component is the base object for calendar, Event and the other components defined in :rfc:`5545`. Normally you will not use this class directly, but rather one of the subclasses. + + On initialization, this class sets its keys to upper case. """ name: ClassVar[str | None] = None @@ -175,7 +177,10 @@ class Component(CaselessDict): @classmethod def _get_component_factory(cls) -> ComponentFactory: - """Get the component factory.""" + """Get the component factory. + + :meta private: + """ if cls._components_factory is None: cls._components_factory = ComponentFactory() return cls._components_factory @@ -233,6 +238,8 @@ def _infer_value_type( ) -> str | None: """Infer the ``VALUE`` parameter from a Python type. + :meta private: + Parameters: value: Python native type, one of :class:`datetime.date`, :class:`datetime.datetime`, :class:`datetime.timedelta`, :class:`datetime.time`, :class:`tuple`, @@ -262,18 +269,23 @@ def _infer_value_type( return None def __init__(self, *args: Any, **kwargs: Any) -> None: - """Set keys to upper for initial dict.""" super().__init__(*args, **kwargs) # set parameters here for properties that use non-default values self.subcomponents: list[Component] = [] # Components can be nested. self.errors: list[tuple[str | None, str]] = [] def __bool__(self) -> bool: - """Returns True, CaselessDict would return False if it had no items.""" + """Returns ``True``, CaselessDict would return ``False`` if it had no items. + + :meta private: + """ return True def __getitem__(self, key) -> VPROPERTY: - """Get property value from the component dictionary.""" + """Get property value from the component dictionary. + + :meta private: + """ return super().__getitem__(key) def get(self, key, default=None) -> Any: @@ -294,6 +306,8 @@ def is_empty(self) -> bool: def _encode(cls, name, value, parameters=None, encode=1): """Encode values to icalendar property values. + :meta private: + Parameters: name (str): Required. Name of the property. value (obj): Required. Value of the property. Either a native Python type or @@ -415,7 +429,10 @@ def add( self[name] = value def _decode(self, name: str, value: VPROPERTY): - """Internal for decoding property values.""" + """Internal for decoding property values. + + :meta private: + """ # TODO: Currently the decoded method calls the icalendar.prop instances # from_ical. We probably want to decode properties into Python native @@ -478,7 +495,10 @@ def add_component(self, component: Component) -> None: def _walk( self, name: str | None, select: callable[[Component], bool] ) -> list[Component]: - """Walk to given component.""" + """Walk to given component. + + :meta private: + """ result = [] stack = [self] while stack: @@ -527,6 +547,8 @@ def with_uid(self, uid: str) -> list[Component]: def _validate_name(self): """Make sure the component has a name. + :meta private: + Raises: ValueError: If this component does not have a name. """ @@ -594,7 +616,10 @@ def from_ical( @classmethod def _get_ical_parser(cls, st: str | bytes) -> ComponentIcalParser: - """Get the iCal parser for the given input string.""" + """Get the iCal parser for the given input string. + + :meta private: + """ return ComponentIcalParser(st, cls._get_component_factory(), cls.types_factory) @classmethod @@ -671,6 +696,8 @@ def to_ical(self, sorted: bool = True): def __repr__(self) -> str: """String representation of class with all of its subcomponents. + :meta private: + Implemented iteratively rather than recursively so that calendars with deeply nested subcomponents do not raise ``RecursionError``. A pathological ``.ics`` payload of only ~13 KB can otherwise nest @@ -880,7 +907,10 @@ def is_thunderbird(self) -> bool: @staticmethod def _utc_now() -> datetime: - """Return now as UTC value.""" + """Return now as UTC value. + + :meta private: + """ return datetime.now(timezone.utc) uid = uid_property @@ -924,6 +954,12 @@ def _utc_now() -> datetime: def _validate_start_and_end(start, end): """This validates start and end. + :meta private: + + Parameters: + end: Required. The end of the calendar component. + start: Required. The start of the calendar component. + Raises: ~icalendar.error.InvalidCalendar: If the information is not valid """ @@ -1368,6 +1404,8 @@ def from_xcal(cls, xcal: Element | bytes | Path | BinaryIO) -> list[Self]: def _node_from_jcal(jcal, starting_cls: type[Component]) -> tuple[Component, list]: """Parse a single jCal component without recursing into subcomponents. + :meta private: + Module-level helper for :meth:`~icalendar.cal.component.Component.from_jcal`: it has no ties to a class or instance (the relevant class is passed in as ``starting_cls``), so it is a plain function rather than a (static) method. diff --git a/src/icalendar/cal/component_factory.py b/src/icalendar/cal/component_factory.py index 78d726e43..0dc7d77a0 100644 --- a/src/icalendar/cal/component_factory.py +++ b/src/icalendar/cal/component_factory.py @@ -15,6 +15,8 @@ class ComponentFactory(CaselessDict): """Registered components from :rfc:`7953` and :rfc:`5545`. + On initialization, this class sets its keys to uppercase. + To get a component, use this class as shown below. .. code-block:: pycon @@ -42,7 +44,6 @@ class ComponentFactory(CaselessDict): """ def __init__(self, *args: Any, **kwargs: Any) -> None: - """Set keys to upper for initial dict.""" super().__init__(*args, **kwargs) from icalendar.cal.alarm import Alarm from icalendar.cal.availability import Availability diff --git a/src/icalendar/cal/event.py b/src/icalendar/cal/event.py index 31f823827..6fd534909 100644 --- a/src/icalendar/cal/event.py +++ b/src/icalendar/cal/event.py @@ -312,7 +312,10 @@ def example(cls, name: str = "rfc_9074_example_3") -> Event: ) def _get_start_end_duration(self): - """Verify the calendar validity and return the right attributes.""" + """Verify the calendar validity and return the right attributes. + + :meta private: + """ return get_start_end_duration_with_validation( self, "DTSTART", "DTEND", "VEVENT" ) diff --git a/src/icalendar/cal/lazy.py b/src/icalendar/cal/lazy.py index d244b3571..f20375b61 100644 --- a/src/icalendar/cal/lazy.py +++ b/src/icalendar/cal/lazy.py @@ -278,7 +278,6 @@ class LazyCalendar(Calendar): """The strategy pattern for subcomponents of the calendar.""" def __init__(self, *args: Any, **kwargs: Any) -> None: - """Initialize the calendar.""" self._subcomponents = InitialSubcomponentsStrategy() super().__init__(*args, **kwargs) @@ -310,14 +309,20 @@ def subcomponents(self, value: list[Component]) -> None: @classmethod def _get_ical_parser(cls, st: str | bytes) -> ComponentIcalParser: - """Get the iCal parser for the given input string.""" + """Get the iCal parser for the given input string. + + :meta private: + """ return LazyCalendarIcalParser( st, cls._get_component_factory(), cls.types_factory ) @classmethod def _get_component_factory(cls) -> ComponentFactory: - """Get the component factory for this calendar.""" + """Get the component factory for this calendar. + + :meta private: + """ factory = ComponentFactory() factory.add_component_class(cls) return factory diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 68b6e9b81..2c8818a9c 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -75,7 +75,9 @@ def example(cls, name: str = "pacific_fiji") -> Timezone: def _extract_offsets(component: TimezoneDaylight | TimezoneStandard, tzname: str): """Extract offsets and transition times from a VTIMEZONE component. - Args: + :meta private: + + Parameters: component: A STANDARD or DAYLIGHT timezone component. tzname: The name of the timezone. @@ -135,6 +137,8 @@ def _extract_offsets(component: TimezoneDaylight | TimezoneStandard, tzname: str def _make_unique_tzname(tzname: str, tznames: set[str]) -> str: """Make a unique tzname and add it to ``tznames``. + :meta private: + Parameters: tzname: The candidate timezone name. tznames: The timezone names already in use. diff --git a/src/icalendar/cal/todo.py b/src/icalendar/cal/todo.py index 64fd73c41..350383287 100644 --- a/src/icalendar/cal/todo.py +++ b/src/icalendar/cal/todo.py @@ -174,7 +174,10 @@ class Todo(Component): ) def _get_start_end_duration(self): - """Verify the calendar validity and return the right attributes.""" + """Verify the calendar validity and return the right attributes. + + :meta private: + """ return get_start_end_duration_with_validation(self, "DTSTART", "DUE", "VTODO") @property diff --git a/src/icalendar/caselessdict.py b/src/icalendar/caselessdict.py index 4f4b7226c..8d61a3ca9 100644 --- a/src/icalendar/caselessdict.py +++ b/src/icalendar/caselessdict.py @@ -79,26 +79,26 @@ class CaselessDict(OrderedDict[str, _VT]): their original case. Keys can be provided as ``str`` or ``bytes``. They are converted to Unicode via :func:`~icalendar.parser_tools.to_unicode`, then uppercased before storage. - """ - def __init__(self, *args: Any, **kwargs: Any) -> None: - """Parameters: - *args: Positional arguments passed to :class:`~collections.OrderedDict`. - **kwargs: Keyword arguments passed to :class:`~collections.OrderedDict`. + Parameters: + *args: Positional arguments passed to :class:`~collections.OrderedDict`. + **kwargs: Keyword arguments passed to :class:`~collections.OrderedDict`. + + Example: - Example: + Create a new ``CaselessDict`` and normalize existing keys to uppercase. - Create a new ``CaselessDict`` and normalize existing keys to uppercase. + .. code-block:: pycon - .. code-block:: pycon + >>> from icalendar.caselessdict import CaselessDict + >>> d = CaselessDict(summary="Meeting") + >>> d["SUMMARY"] + 'Meeting' + >>> "summary" in d + True + """ - >>> from icalendar.caselessdict import CaselessDict - >>> d = CaselessDict(summary="Meeting") - >>> d["SUMMARY"] - 'Meeting' - >>> "summary" in d - True - """ + def __init__(self, *args: Any, **kwargs: Any) -> None: super().__init__(*args, **kwargs) for key, value in self.items(): key_upper = to_unicode(key).upper() @@ -112,6 +112,8 @@ def __getitem__(self, key: str) -> _VT: """Get the item from the ``CaselessDict`` instance by ``key``, case-insensitively. + :meta private: + Parameters: key: The key to look up, case-insensitively. @@ -127,6 +129,8 @@ def __getitem__(self, key: str) -> _VT: def __setitem__(self, key: str, value: _VT) -> None: """Set a (key, value) pair, storing the key in uppercase. + :meta private: + Parameters: key: The key of the pair, case-insensitive. value: The value to associate with the key. @@ -137,6 +141,8 @@ def __setitem__(self, key: str, value: _VT) -> None: def __delitem__(self, key: str) -> None: """Delete a (key, value) pair by its case-insensitive key. + :meta private: + Parameters: key: The key to delete, case-insensitively. @@ -149,6 +155,8 @@ def __delitem__(self, key: str) -> None: def __contains__(self, key: object) -> bool: """Check whether a key exists in the mapping, case-insensitively. + :meta private: + Parameters: key: The key to check case-insensitively. @@ -253,6 +261,8 @@ def copy(self) -> Self: def __repr__(self) -> str: """Return a string representation of the dictionary. + :meta private: + Returns: A string in the form ``CaselessDict({...})``. """ @@ -261,6 +271,8 @@ def __repr__(self) -> str: def __eq__(self, other: object) -> bool: """Check equality with another dictionary. + :meta private: + Two ``CaselessDict`` instances are equal if they contain the same (key, value) pairs after uppercasing keys. Comparison with a regular ``dict`` also works. @@ -278,6 +290,8 @@ def __eq__(self, other: object) -> bool: def __ne__(self, other: object) -> bool: """Check inequality with another dictionary. + :meta private: + Parameters: other: The object to compare. diff --git a/src/icalendar/cli.py b/src/icalendar/cli.py index b5d94ac49..890953e6d 100755 --- a/src/icalendar/cli.py +++ b/src/icalendar/cli.py @@ -15,6 +15,8 @@ def _format_name(address: str) -> str: """Format a display name and email from an address string. + :meta private: + Parameters: address: An address object, such as mailto:name@example.com. @@ -32,6 +34,8 @@ def _format_name(address: str) -> str: def _format_attendees(attendees: list | str | vCalAddress) -> str: """Format the list of attendees. + :meta private: + Parameters: attendees: Either a list, a string, or a vCalAddress object. diff --git a/src/icalendar/config.py b/src/icalendar/config.py index 86ed19882..716dda009 100644 --- a/src/icalendar/config.py +++ b/src/icalendar/config.py @@ -21,8 +21,10 @@ def _clamp_repeat(n: int) -> int: """Return *n* clamped to ``[0, MAX_ALARM_REPEAT]``. - Negative values are treated as 0. When :data:`MAX_ALARM_REPEAT` is ``-1`` - the value is returned unchanged after clamping negatives to 0. + :meta private: + + Negative values are treated as ``0``. When :data:`MAX_ALARM_REPEAT` is ``-1`` + the value is returned unchanged after clamping negatives to ``0``. """ if n < 0: return 0 diff --git a/src/icalendar/enums.py b/src/icalendar/enums.py index 1e0701920..6ab2959e2 100644 --- a/src/icalendar/enums.py +++ b/src/icalendar/enums.py @@ -15,7 +15,10 @@ class Enum(_Enum): """Enum class that can be pickled.""" def __reduce_ex__(self, _p): - """For pickling.""" + """For pickling. + + :meta private: + """ return self.__class__, (self._value_,) @@ -27,6 +30,8 @@ class StrEnum(str, Enum): def __str__(self) -> str: """Convert to a string. + :meta private: + This is needed when we set the value directly in components. """ return self.value diff --git a/src/icalendar/error.py b/src/icalendar/error.py index 3c10b6c46..d49cad92c 100644 --- a/src/icalendar/error.py +++ b/src/icalendar/error.py @@ -118,6 +118,8 @@ class GloballyUniqueTZIDGuessed(UserWarning): def _repr_index(index: str | int) -> str: """Create a JSON compatible representation for the index. + :meta private: + Parameters: index: It is either a dict key (string) or a list position (integer). @@ -131,7 +133,15 @@ def _repr_index(index: str | int) -> str: class JCalParsingError(InvalidCalendar): - """Could not parse a part of the JCal.""" + """Could not parse a part of the JCal. + + Parameters: + message: Required. A description of the error that occurred while parsing. + parser: The parser class or its name where the error occurred. + path: The location in the jCal structure where the error occurred. + value: The value which caused the error, if available. + + """ _default_value = object() path: list[str | int] @@ -150,14 +160,6 @@ def __init__( path: list[str | int] | None | str | int = None, value: object = _default_value, ) -> None: - """Create a new JCalParsingError. - - Parameters: - message: A description of the error that occurred while parsing. - parser: The parser class or its name where the error occurred. - path: The location in the jCal structure where the error occurred. - value: The value which caused the error, if available. - """ self.path = self._get_path(path) if not isinstance(parser, str): parser = parser.__name__ @@ -199,7 +201,10 @@ def reraise_with_path_added( @staticmethod def _get_path(path: list[str | int] | None | str | int) -> list[str | int]: - """Return the path as a list.""" + """Return the path as a list. + + :meta private: + """ if path is None: path = [] elif not isinstance(path, list): @@ -363,7 +368,13 @@ def validate_jcal_token( class XCalParsingError(InvalidCalendar): - """Could not parse a part of the xCal.""" + """Could not parse a part of the xCal. + + Parameters: + element: Required. The XML element that caused the error. + message: Required. A description of the error that occurred while parsing. + value: Required. The value that caused the error. + """ message: str """A description of the error that occurred while parsing.""" @@ -380,13 +391,6 @@ def __init__( value: str | None, element: ElementAdapter, ) -> None: - """Create a new XCalParsingError. - - Parameters: - message: A description of the error that occurred while parsing. - value: The value that caused the error. - element: The XML element that caused the error. - """ self.value = value self.element = element self.short_message = message diff --git a/src/icalendar/param.py b/src/icalendar/param.py index bca86330f..bef05cb6f 100644 --- a/src/icalendar/param.py +++ b/src/icalendar/param.py @@ -26,12 +26,18 @@ def _default_return_none() -> str | None: - """Return None by default.""" + """Return ``None`` by default. + + :meta private: + """ return None def _default_return_string() -> str: - """Return None by default.""" + """Return ``None`` by default. + + :meta private: + """ return "" @@ -156,7 +162,10 @@ def fdel(self: VPROPERTY): def _default_return_individual() -> enums.CUTYPE | str: - """Default value.""" + """Default value. + + :meta private: + """ return enums.CUTYPE.INDIVIDUAL @@ -263,7 +272,10 @@ def fdel(self: VPROPERTY): def _default_return_busy() -> enums.FBTYPE | str: - """Default value.""" + """Default value. + + :meta private: + """ return enums.FBTYPE.BUSY @@ -309,7 +321,10 @@ def _default_return_busy() -> enums.FBTYPE | str: def _default_return_needs_action() -> enums.PARTSTAT | str: - """Default value.""" + """Default value. + + :meta private: + """ return enums.PARTSTAT.NEEDS_ACTION @@ -552,23 +567,9 @@ def _default_return_parent() -> enums.RELTYPE: def _get_value(self: VPROPERTY) -> str: """The VALUE parameter or the default. - Purpose: - VALUE explicitly specify the value type format for a property value. + :meta private: - Description: - This parameter specifies the value type and format of - the property value. The property values MUST be of a single value - type. For example, a "RDATE" property cannot have a combination - of DATE-TIME and TIME value types. - - If the property's value is the default value type, then this - parameter need not be specified. However, if the property's - default value type is overridden by some other allowable value - type, then this parameter MUST be specified. - - Applications MUST preserve the value data for ``x-name`` and - ``iana-token`` values that they don't recognize without attempting - to interpret or parse the value data. + This method explicitly specifies the value type format for a property value. Returns: The VALUE parameter or the default. @@ -613,12 +614,18 @@ def _get_value(self: VPROPERTY) -> str: def _set_value(self: VPROPERTY, value: str | None): - """Set the VALUE parameter.""" + """Set the VALUE parameter. + + :meta private: + """ self.params.value = value def _del_value(self: VPROPERTY): - """Delete the VALUE parameter.""" + """Delete the VALUE parameter. + + :meta private: + """ del self.params.value @@ -765,6 +772,8 @@ def _del_value(self: VPROPERTY): def _get_GAP(prop) -> timedelta | None: # noqa: N802 """GAP + :meta private: + Purpose: GAP specifies the length of the gap, positive or negative, between two components with a temporal relationship. @@ -822,7 +831,10 @@ def _get_GAP(prop) -> timedelta | None: # noqa: N802 def _set_GAP(prop, value: timedelta | str | None): # noqa: N802 - """Set the GAP parameter as a timedelta.""" + """Set the GAP parameter as a timedelta. + + :meta private: + """ if value is None: prop.params.pop("GAP", None) return @@ -832,7 +844,10 @@ def _set_GAP(prop, value: timedelta | str | None): # noqa: N802 def _del_GAP(prop): # noqa: N802 - """Delete the GAP parameter.""" + """Delete the GAP parameter. + + :meta private: + """ prop.params.pop("GAP", None) diff --git a/src/icalendar/parser/content_line.py b/src/icalendar/parser/content_line.py index 9047546b0..c9cff96f8 100644 --- a/src/icalendar/parser/content_line.py +++ b/src/icalendar/parser/content_line.py @@ -33,6 +33,8 @@ def _strip_ows_around_delimiters(st: str, delimiters: str = ";=") -> str: respecting backslash escapes so that escaped delimiters are not treated as separators. + :meta private: + This is a lenient parsing helper (used when strict=False) to support iCalendar content lines that contain extra whitespace around tokens. """ diff --git a/src/icalendar/parser/ical/component.py b/src/icalendar/parser/ical/component.py index 7f87b0972..4c1c03b87 100644 --- a/src/icalendar/parser/ical/component.py +++ b/src/icalendar/parser/ical/component.py @@ -21,6 +21,13 @@ class ComponentIcalParser: This uses the template method pattern, where the main parsing logic can be refined in subclasses. + + Parameters: + data: The raw iCalendar data to parse, either as bytes + or a list of content lines. + component_factory: The factory to use for creating components. + types_factory: The factory to use for creating property values. + """ datetime_names: ClassVar[tuple[str, ...]] = ( @@ -43,14 +50,6 @@ def __init__( component_factory: ComponentFactory, types_factory: TypesFactory, ) -> None: - """Initialize the parser with the raw data. - - Parameters: - data: The raw iCalendar data to parse, either as bytes - or a list of content lines. - component_factory: The factory to use for creating components. - types_factory: The factory to use for creating property values. - """ self._data = data self._component_factory = component_factory self._types_factory = types_factory diff --git a/src/icalendar/parser/ical/lazy.py b/src/icalendar/parser/ical/lazy.py index 22acd4db6..5beefb9b9 100644 --- a/src/icalendar/parser/ical/lazy.py +++ b/src/icalendar/parser/ical/lazy.py @@ -104,7 +104,6 @@ class LazySubcomponent: """ def __init__(self, name: str, parser: ComponentIcalParser) -> None: - """Initialize the lazy subcomponent with the raw data.""" self._name = name self._parser = parser self._component: Component | None = None diff --git a/src/icalendar/parser/parameter.py b/src/icalendar/parser/parameter.py index 7168dd808..41d3e408a 100644 --- a/src/icalendar/parser/parameter.py +++ b/src/icalendar/parser/parameter.py @@ -259,6 +259,8 @@ def q_join(lst: Sequence[str], sep: str = ",", always_quote: bool = False) -> st def _single_string_parameter(upper: bool = False): """Create a parameter getter/setter for a single string parameter. + :meta private: + Parameters: upper: Convert the return value of the property getter to uppercase. @@ -304,6 +306,10 @@ class Parameters(CaselessDict[str | list[str]]): It knows nothing of datatypes. Its main concern is textual structure. + Parameters: + *args: The arguments to parse. + **kwargs: The keyword arguments to parse. + Examples: Modify parameters: @@ -337,7 +343,6 @@ class Parameters(CaselessDict[str | list[str]]): """ def __init__(self, *args: Any, **kwargs: Any) -> None: - """Create new parameters.""" if args and args[0] is None: # allow passing None args = args[1:] @@ -486,11 +491,13 @@ def _parameter_value_to_jcal( ) -> str | int | float | list[str] | list[int] | list[float]: """Convert a parameter value to jCal format. + :meta private: + Parameters: - value: The parameter value + value: The parameter value. Returns: - The jCal representation of the parameter value + The jCal representation of the parameter value. """ if isinstance(value, list): return [self._parameter_value_to_jcal(v) for v in value] @@ -700,6 +707,8 @@ def get_multiple(self, key: str) -> list: def _rfc_6868_unescape(param_value: str) -> str: """Take care of :rfc:`6868` unescaping. + :meta private: + - ^^ -> ^ - ^n -> system specific newline - ^' -> " @@ -721,6 +730,8 @@ def _rfc_6868_unescape(param_value: str) -> str: def _rfc_6868_escape(param_value: str) -> str: """Take care of :rfc:`6868` escaping. + :meta private: + - ^ -> ^^ - " -> ^' - newline -> ^n diff --git a/src/icalendar/parser/string.py b/src/icalendar/parser/string.py index 8c879dcb5..c3849db46 100644 --- a/src/icalendar/parser/string.py +++ b/src/icalendar/parser/string.py @@ -9,6 +9,8 @@ def _escape_char(text: str | bytes) -> str: r"""Format value according to iCalendar TEXT escaping rules. + :meta private: + Escapes special characters in text values according to :rfc:`5545#section-3.3.11` rules. The order of replacements matters to avoid double-escaping. @@ -58,6 +60,8 @@ def _escape_char(text: str | bytes) -> str: def _unescape_char(text: str | bytes) -> str | bytes: r"""Unescape iCalendar TEXT values. + :meta private: + Reverses the escaping applied by ``_escape_char`` according to :rfc:`5545#section-3.3.11` TEXT escaping rules. @@ -105,6 +109,8 @@ def _unescape_char(text: str | bytes) -> str | bytes: def _foldline(line: str, limit: int = 75, fold_sep: str = "\r\n ") -> str: r"""Make a string folded as defined in :rfc:`5545#section-3.1`. + :meta private: + Lines of text SHOULD NOT be longer than 75 octets, excluding the line break. Long content lines SHOULD be split into a multiple line representations using a line "folding" technique. That is, a long @@ -152,6 +158,8 @@ def _foldline(line: str, limit: int = 75, fold_sep: str = "\r\n ") -> str: def _escape_string(val: str) -> str: r"""Escape backslash sequences to URL-encoded hex values. + :meta private: + Converts backslash-escaped characters to their percent-encoded hex equivalents. This is used for parameter parsing to preserve escaped characters during processing. @@ -188,6 +196,8 @@ def _escape_string(val: str) -> str: def _unescape_string(val: str) -> str: r"""Unescape URL-encoded hex values to their original characters. + :meta private: + Reverses ``_escape_string`` by converting percent-encoded hex values back to their original characters. This is used for parameter parsing. diff --git a/src/icalendar/parser/xcal/adapter.py b/src/icalendar/parser/xcal/adapter.py index 34138c268..64d81c892 100644 --- a/src/icalendar/parser/xcal/adapter.py +++ b/src/icalendar/parser/xcal/adapter.py @@ -140,7 +140,10 @@ def get_xsd_float(self) -> float: ) from e def __repr__(self) -> str: - """Return the text representation of this element.""" + """Return the text representation of this element. + + :meta private: + """ return f"Element@{self.get_xpath()}" def make_parent(self, tag: str) -> ElementAdapter: diff --git a/src/icalendar/parser/xcal/base.py b/src/icalendar/parser/xcal/base.py index 4e2730367..ba1f198ee 100644 --- a/src/icalendar/parser/xcal/base.py +++ b/src/icalendar/parser/xcal/base.py @@ -72,7 +72,10 @@ def tag(self) -> str: @staticmethod def _sanitize_tags(tags: str | Sequence[str]) -> set[str]: - """Return a set of tags to test.""" + """Return a set of tags to test. + + :meta private: + """ if isinstance(tags, str): return {tags.lower()} return {t.lower() for t in tags} @@ -112,6 +115,8 @@ def parse_tag(self, tag: str | Sequence[str] | None = None) -> ElementAdapter: def _parse_tag(self, tags: set[str]) -> ElementAdapter | None: """Find a child tag and return it. + :meta private: + This child is then considered parsed. """ for i, child in enumerate(self._children): diff --git a/src/icalendar/parser/xcal/string.py b/src/icalendar/parser/xcal/string.py index 5b1fb5067..95f939413 100644 --- a/src/icalendar/parser/xcal/string.py +++ b/src/icalendar/parser/xcal/string.py @@ -53,8 +53,13 @@ def xsd_float_to_string(f: float) -> str: def _to_valid_xml_string(string: str) -> str: """Remove all characters that are not valid XML characters. - Returns: + :meta private: + + Parameters: + string: The string from which to remove characters that are not valid + XML characters. + Returns: A string with all characters that are not valid XML characters removed. .. seealso:: diff --git a/src/icalendar/prop/adr.py b/src/icalendar/prop/adr.py index cb09d22fa..180e49f92 100644 --- a/src/icalendar/prop/adr.py +++ b/src/icalendar/prop/adr.py @@ -51,6 +51,11 @@ class vAdr: Semicolons are field separators and are NOT escaped. Commas and backslashes within field values ARE escaped per :rfc:`6350`. + Parameters: + fields: Either an AdrFields, tuple, or list of seven strings, one per field, + or a vCard format string with semicolon-separated fields. + params: Optional property parameters. + Examples: .. code-block:: pycon @@ -72,13 +77,6 @@ def __init__( /, params: dict[str, Any] | None = None, ) -> None: - """Initialize ADR with seven fields or parse from vCard format string. - - Parameters: - fields: Either an AdrFields, tuple, or list of seven strings, one per field, - or a vCard format string with semicolon-separated fields - params: Optional property parameters - """ if isinstance(fields, str): fields = self.from_ical(fields) if isinstance(fields, AdrFields): @@ -119,11 +117,17 @@ def from_ical(ical: str | bytes) -> AdrFields: return AdrFields(*fields) def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ return isinstance(other, vAdr) and self.fields == other.fields def __repr__(self) -> str: - """String representation.""" + """String representation. + + :meta private: + """ return f"{self.__class__.__name__}({self.fields}, params={self.params})" @property diff --git a/src/icalendar/prop/binary.py b/src/icalendar/prop/binary.py index bc8079ecc..cc199cd9e 100644 --- a/src/icalendar/prop/binary.py +++ b/src/icalendar/prop/binary.py @@ -98,11 +98,17 @@ def uri(self) -> str: return f"data:{quote(media_type, safe='/;=')};base64,{self.base64data}" def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ return isinstance(other, vBinary) and self.bytes == other.bytes def __hash__(self) -> int: - """Hash of the vBinary object.""" + """Hash of the vBinary object. + + :meta private: + """ return hash(self.bytes) @classmethod diff --git a/src/icalendar/prop/broken.py b/src/icalendar/prop/broken.py index 5002a54e8..70ecb2320 100644 --- a/src/icalendar/prop/broken.py +++ b/src/icalendar/prop/broken.py @@ -47,6 +47,8 @@ def __new__( def __getattr__(self, name: str): """Raise BrokenCalendarProperty for attribute access. + :meta private: + Attributes like ``.dt`` that the expected type would have raise :class:`~icalendar.error.BrokenCalendarProperty` with the original parse error chained. Private attributes diff --git a/src/icalendar/prop/cal_address.py b/src/icalendar/prop/cal_address.py index 98cdab585..7173e5e67 100644 --- a/src/icalendar/prop/cal_address.py +++ b/src/icalendar/prop/cal_address.py @@ -92,6 +92,8 @@ def from_ical(cls, ical: str | bytes) -> Self: def __eq__(self, other: object) -> bool: """Compare calendar addresses by email address. + :meta private: + Two addresses are equal if their email addresses match case-insensitively. The ``mailto:`` prefix is optional on either side, so ``mailto:user@example.com`` equals ``user@example.com``. @@ -128,6 +130,8 @@ def __eq__(self, other: object) -> bool: def __ne__(self, other: object) -> bool: """Negation of :meth:`__eq__`. + :meta private: + This method is required because :class:`vCalAddress` extends :class:`str`. Without it, ``!=`` would use :meth:`str.__ne__` using plain string comparison and could disagree with @@ -140,7 +144,10 @@ def __ne__(self, other: object) -> bool: return not result def __hash__(self) -> int: - """Hash of the lowercased email address, consistent with :meth:`__eq__`.""" + """Hash of the lowercased email address, consistent with :meth:`__eq__`. + + :meta private: + """ return hash(self.email.lower()) @property @@ -263,6 +270,8 @@ def has_email(self, email: str) -> bool: def _get_email(email: str) -> str: """Extract email and add mailto: prefix if needed. + :meta private: + Handles case-insensitive mailto: prefix checking. Parameters: diff --git a/src/icalendar/prop/categories.py b/src/icalendar/prop/categories.py index d02f747a7..5cefe1168 100644 --- a/src/icalendar/prop/categories.py +++ b/src/icalendar/prop/categories.py @@ -64,7 +64,10 @@ def from_ical(ical: list[str] | str) -> list[str]: return ical.split(",") def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ if isinstance(other, vCategory): return self.cats == other.cats if isinstance(other, list): @@ -72,11 +75,17 @@ def __eq__(self, other: object) -> bool: return NotImplemented def __hash__(self) -> int: - """Hash of the vCategory object.""" + """Hash of the vCategory object. + + :meta private: + """ return hash(tuple(self.cats)) def __repr__(self) -> str: - """String representation.""" + """String representation. + + :meta private: + """ return f"{self.__class__.__name__}({self.cats}, params={self.params})" def to_jcal(self, name: str) -> list: diff --git a/src/icalendar/prop/dt/base.py b/src/icalendar/prop/dt/base.py index a21e10022..44ae87648 100644 --- a/src/icalendar/prop/dt/base.py +++ b/src/icalendar/prop/dt/base.py @@ -12,7 +12,10 @@ class TimeBase: ignore_for_equality = {"TZID", "VALUE"} def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ if isinstance(other, date): return self.dt == other if isinstance(other, TimeBase): @@ -34,10 +37,11 @@ def __eq__(self, other: object) -> bool: def __hash__(self) -> int: return hash(self.dt) - from icalendar.param import RANGE, RELATED, TZID - def __repr__(self) -> str: - """String representation.""" + """String representation. + + :meta private: + """ return f"{self.__class__.__name__}({self.dt}, {self.params})" diff --git a/src/icalendar/prop/dt/list.py b/src/icalendar/prop/dt/list.py index 86ecb057f..c2fc4bfe4 100644 --- a/src/icalendar/prop/dt/list.py +++ b/src/icalendar/prop/dt/list.py @@ -64,7 +64,10 @@ def __eq__(self, other): return False def __repr__(self): - """String representation.""" + """String representation. + + :meta private: + """ return f"{self.__class__.__name__}({self.dts})" @classmethod diff --git a/src/icalendar/prop/dt/period.py b/src/icalendar/prop/dt/period.py index 1deb428cf..280fb69dd 100644 --- a/src/icalendar/prop/dt/period.py +++ b/src/icalendar/prop/dt/period.py @@ -26,6 +26,8 @@ def _to_midnight(dt: date, tz: tzinfo | None) -> datetime: """Convert a date to the datetime at midnight. + :meta private: + Parameters: dt: The date to convert. tz: The timezone of the result, or ``None`` for a naive result. @@ -46,6 +48,8 @@ def _to_period_datetimes( ) -> tuple[datetime, datetime | timedelta]: """Convert the dates of a period to datetimes. + :meta private: + :rfc:`5545#section-3.3.9` builds a period from datetimes only, but calendars in the wild use dates. A date becomes midnight so that the period can be used and written back out. @@ -55,8 +59,8 @@ def _to_period_datetimes( duration. Parameters: - start: The start of the period. end_or_duration: The end of the period or its duration. + start: The start of the period. Returns: The start and the end or duration, with any date converted. diff --git a/src/icalendar/prop/dt/types.py b/src/icalendar/prop/dt/types.py index bad267e01..5be07d611 100644 --- a/src/icalendar/prop/dt/types.py +++ b/src/icalendar/prop/dt/types.py @@ -139,7 +139,10 @@ def examples(cls) -> list[vDDDTypes]: return [cls(date(2025, 11, 10)), cls(timedelta(days=1, hours=5))] def _get_value(self) -> str | None: - """Determine the VALUE parameter.""" + """Determine the VALUE parameter. + + :meta private: + """ return self.to_property_type().VALUE from icalendar.param import VALUE diff --git a/src/icalendar/prop/empty.py b/src/icalendar/prop/empty.py index 5aa4ba025..de9e589b6 100644 --- a/src/icalendar/prop/empty.py +++ b/src/icalendar/prop/empty.py @@ -92,7 +92,10 @@ def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: # noqa: ARG return cls(params=params) def __repr__(self) -> str: - """The text representation.""" + """The text representation. + + :meta private: + """ return f"{self.__class__.__name__}()" diff --git a/src/icalendar/prop/factory.py b/src/icalendar/prop/factory.py index 20b73da44..a12cfd31d 100644 --- a/src/icalendar/prop/factory.py +++ b/src/icalendar/prop/factory.py @@ -42,7 +42,9 @@ class TypesFactory(CaselessDict): - """Factory for all value types defined in :rfc:`5545` and subsequent. + """Factory for all value types defined in :rfc:`5545` and subsequent RFCs. + + On initialization, this class sets its keys to uppercase. The value and parameter names don't overlap. So one factory is enough for both kinds. @@ -58,7 +60,6 @@ def instance() -> TypesFactory: return TypesFactory._instance def __init__(self, *args: Any, **kwargs: Any) -> None: - """Set keys to upper for initial dict""" super().__init__(*args, **kwargs) self.all_types = ( vBinary, diff --git a/src/icalendar/prop/float.py b/src/icalendar/prop/float.py index c0bf6ba0f..770b38d3d 100644 --- a/src/icalendar/prop/float.py +++ b/src/icalendar/prop/float.py @@ -16,6 +16,8 @@ def _float_to_ical(value: float) -> str: """Convert a float to the ``FLOAT`` notation of :rfc:`5545#section-3.3.7`. + :meta private: + The ``FLOAT`` grammar has no exponent. Python writes very small and very large floats with one, such as ``1e-05``. Those values are written with all their digits instead. diff --git a/src/icalendar/prop/geo.py b/src/icalendar/prop/geo.py index 60b2e432e..c584a4d7f 100644 --- a/src/icalendar/prop/geo.py +++ b/src/icalendar/prop/geo.py @@ -18,54 +18,40 @@ class vGeo: - """Geographic Position + """Geographic position. - Property Name: - GEO + This property specifies information related to the global position for the + activity specified by a calendar component. - Purpose: - This property specifies information related to the global - position for the activity specified by a calendar component. + This property value specifies latitude and longitude, in that order. The + acceptable ranges are ``-90.000000`` to ``+90.000000`` for latitude and + ``-180.000000`` to ``+180.000000`` for longitude. The longitude and + latitude values may be specified up to six decimal places, which will allow + for accuracy to within one meter of geographical position. - Value Type: - FLOAT. The value MUST be two SEMICOLON-separated FLOAT values. + This property can be specified in VEVENT or VTODO calendar components. - Property Parameters: - IANA and non-standard property parameters can be specified on - this property. + Raises: + ValueError: if geo is not a tuple of (latitude, longitude). - Conformance: - This property can be specified in "VEVENT" or "VTODO" - calendar components. + Examples: - Description: - This property value specifies latitude and longitude, - in that order (i.e., "LAT LON" ordering). The longitude - represents the location east or west of the prime meridian as a - positive or negative real number, respectively. The longitude and - latitude values MAY be specified up to six decimal places, which - will allow for accuracy to within one meter of geographical - position. Receiving applications MUST accept values of this - precision and MAY truncate values of greater precision. - - Example: - - .. code-block:: ics + .. code-block:: ics GEO:37.386013;-122.082932 Parse vGeo: - .. code-block:: pycon + .. 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: + Add a geographic location to an event: - .. code-block:: pycon + .. code-block:: pycon >>> from icalendar import Event >>> event = Event() @@ -91,11 +77,6 @@ def __init__( /, params: dict[str, Any] | None = None, ) -> None: - """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) @@ -131,11 +112,17 @@ def __eq__(self, other: object) -> bool: return isinstance(other, vGeo) and self.to_ical() == other.to_ical() def __hash__(self) -> int: - """Hash of the vGeo object.""" + """Hash of the vGeo object. + + :meta private: + """ return hash((self.latitude, self.longitude)) def __repr__(self) -> str: - """repr(self)""" + """repr(self) + + :meta private: + """ return f"{self.__class__.__name__}(({self.latitude}, {self.longitude}))" def to_jcal(self, name: str) -> list: diff --git a/src/icalendar/prop/image.py b/src/icalendar/prop/image.py index 71328f332..a54d246f4 100644 --- a/src/icalendar/prop/image.py +++ b/src/icalendar/prop/image.py @@ -14,31 +14,19 @@ class Image: """An image as URI or BINARY according to :rfc:`7986`. - Value Type: - URI or BINARY -- no default. The value MUST be data - with a media type of "image" or refer to such data. + The value must be a URI or binary data with a media type of "image" or + refer to such data. - Description: - This property specifies an image for an iCalendar - object or a calendar component via a URI or directly with inline - data that can be used by calendar user agents when presenting the - calendar data to a user. Multiple properties MAY be used to - specify alternative sets of images with, for example, varying - media subtypes, resolutions, or sizes. When multiple properties - are present, calendar user agents SHOULD display only one of them, - picking one that provides the most appropriate image quality, or - display none. The "DISPLAY" parameter is used to indicate the - intended display mode for the image. The "ALTREP" parameter, - defined in :rfc:`5545`, can be used to provide a "clickable" image - where the URI in the parameter value can be "launched" by a click - on the image in the calendar user agent. + This property specifies an image for an iCalendar object or a calendar + component via a URI or directly with inline data that can be used by + calendar user agents when presenting the calendar data to a user. Parameters: - uri: The URI of the image. - b64data: The data of the image, base64 encoded. - fmttype: The format type, e.g. ``"image/png"``. altrep: Link target of the image. - display: The display mode, e.g. ``"BADGE"``. + b64data: The data of the image, base64 encoded. + display: The display mode, for example, ``"BADGE"``. + fmttype: The format type, for example, ``"image/png"``. + uri: The URI of the image. """ @@ -79,7 +67,6 @@ def __init__( altrep: str | None = None, display: str | None = None, ) -> None: - """Create a new image according to :rfc:`7986`.""" if uri is not None and b64data is not None: raise ValueError("Image cannot have both URI and binary data (RFC 7986)") if uri is None and b64data is None: diff --git a/src/icalendar/prop/n.py b/src/icalendar/prop/n.py index e84f4b56f..83ccf4469 100644 --- a/src/icalendar/prop/n.py +++ b/src/icalendar/prop/n.py @@ -44,6 +44,11 @@ class vN: Semicolons are field separators and are NOT escaped. Commas and backslashes within field values ARE escaped per :rfc:`6350`. + Parameters: + fields: Either an NFields, tuple, or list of five strings, one per field, + or a vCard format string with semicolon-separated fields + params: Optional property parameters + Examples: .. code-block:: pycon @@ -66,13 +71,6 @@ def __init__( /, params: dict[str, Any] | None = None, ) -> None: - """Initialize N with five fields or parse from vCard format string. - - Parameters: - fields: Either an NFields, tuple, or list of five strings, one per field, - or a vCard format string with semicolon-separated fields - params: Optional property parameters - """ if isinstance(fields, str): fields = self.from_ical(fields) if isinstance(fields, NFields): @@ -109,11 +107,17 @@ def from_ical(ical: str | bytes) -> NFields: return NFields(*fields) def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ return isinstance(other, vN) and self.fields == other.fields def __repr__(self) -> str: - """String representation.""" + """String representation. + + :meta private: + """ return f"{self.__class__.__name__}({self.fields}, params={self.params})" @property diff --git a/src/icalendar/prop/org.py b/src/icalendar/prop/org.py index cda9a92ca..0dbecda11 100644 --- a/src/icalendar/prop/org.py +++ b/src/icalendar/prop/org.py @@ -25,6 +25,11 @@ class vOrg: Semicolons are field separators and are NOT escaped. Commas and backslashes within field values ARE escaped per :rfc:`6350`. + Parameters: + fields: Either a tuple or list of one or more strings, or a + vCard format string with semicolon-separated fields. + params: Optional property parameters. + Examples: A property value consisting of an organizational name, organizational unit #1 name, and organizational unit #2 name. @@ -55,13 +60,6 @@ def __init__( /, params: dict[str, Any] | None = None, ) -> None: - """Initialize ORG with variable fields or parse from vCard format string. - - Parameters: - fields: Either a tuple or list of one or more strings, or a - vCard format string with semicolon-separated fields - params: Optional property parameters - """ if isinstance(fields, str): fields = self.from_ical(fields) if len(fields) < 1: @@ -93,11 +91,17 @@ def from_ical(ical: str | bytes) -> tuple[str, ...]: return tuple(fields) def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ return isinstance(other, vOrg) and self.fields == other.fields def __repr__(self) -> str: - """String representation.""" + """String representation. + + :meta private: + """ return f"{self.__class__.__name__}({self.fields}, params={self.params})" @property diff --git a/src/icalendar/prop/recur/month.py b/src/icalendar/prop/recur/month.py index fd2bda57a..fb6a5ee2b 100644 --- a/src/icalendar/prop/recur/month.py +++ b/src/icalendar/prop/recur/month.py @@ -90,11 +90,17 @@ def leap(self, value: bool) -> None: self._leap = value def __repr__(self) -> str: - """repr(self)""" + """repr(self) + + :meta private: + """ return f"{self.__class__.__name__}({str(self)!r})" def __str__(self) -> str: - """str(self)""" + """str(self) + + :meta private: + """ return f"{int(self)}{'L' if self.leap else ''}" @classmethod diff --git a/src/icalendar/prop/recur/recur.py b/src/icalendar/prop/recur/recur.py index 8e6920334..244c510d1 100644 --- a/src/icalendar/prop/recur/recur.py +++ b/src/icalendar/prop/recur/recur.py @@ -30,6 +30,8 @@ def _contains_part_separator(value: str) -> bool: """Whether a text value of a recurrence rule part contains a separator. + :meta private: + RECUR has no escaping, so a text value, such as that of ``RSCALE`` or an unknown part, cannot contain the part separator ``;`` or the list separator ``,``. @@ -208,18 +210,27 @@ def __init__( @staticmethod def _normalize_key(key: str) -> str: - """Return the iCalendar name for a recurrence rule part.""" + """Return the iCalendar name for a recurrence rule part. + + :meta private: + """ return "BYDAY" if key.upper() == "BYWEEKDAY" else key def _normalize_byweekday(self) -> None: - """Normalize the dateutil spelling to the RFC 5545 spelling.""" + """Normalize the dateutil spelling to the RFC 5545 spelling. + + :meta private: + """ if "BYWEEKDAY" in self: if "BYDAY" in self: raise ValueError("BYDAY and BYWEEKDAY cannot both be specified") self["BYDAY"] = self.pop("BYWEEKDAY") def _normalized(self) -> Self: - """Return a recurrence with canonical rule-part names.""" + """Return a recurrence with canonical rule-part names. + + :meta private: + """ return type(self)(self) if "BYWEEKDAY" in self else self def to_ical(self): @@ -334,6 +345,12 @@ def from_jcal(cls, jcal_property: list) -> Self: def _parse_jcal_part_value(cls, value_type: type, jcal_value: Any) -> VPROPERTY: """Parse the jCal value of one recurrence rule part. + :meta private: + + Parameters: + jcal_value: Required. The jCal value to parse. + value_type: Required. The value type to parse. + Raises: ~error.JCalParsingError: If a text value contains a part separator. """ @@ -479,7 +496,10 @@ def wkst(self) -> None: self.pop("WKST", None) def __eq__(self, other: object) -> bool: - """self == other""" + """self == other + + :meta private: + """ if not isinstance(other, vRecur): return super().__eq__(other) if self.keys() != other.keys(): diff --git a/src/icalendar/prop/request_status.py b/src/icalendar/prop/request_status.py index 03f1d8c8b..7c9913932 100644 --- a/src/icalendar/prop/request_status.py +++ b/src/icalendar/prop/request_status.py @@ -69,7 +69,10 @@ class vRequestStatus(vText): __match: re.Match | None = None def _get_match(self) -> re.Match | None: - """Return a match for parsing.""" + """Return a match for parsing. + + :meta private: + """ if self.__match is None: self.__match = REQUEST_STATUS_GRAMMAR.match(self) return self.__match @@ -101,7 +104,10 @@ def code_string(self) -> str: return match.group("code") def _unescape(self, string: str): - """Unescape a string.""" + """Unescape a string. + + :meta private: + """ return UNESCAPE.sub(r"\1", string) @property diff --git a/src/icalendar/prop/text.py b/src/icalendar/prop/text.py index 3c4e7f5c1..7169a2e6a 100644 --- a/src/icalendar/prop/text.py +++ b/src/icalendar/prop/text.py @@ -33,6 +33,8 @@ def _strip_unsafe_text_chars(value: object) -> str: r"""Remove CONTROL characters that :rfc:`5545#section-3.3.11` forbids in TEXT. + :meta private: + ``\r\n`` and a lone ``\r`` become ``\n`` first, so an intentional line break is kept and escaped on serialize. Remaining matches of :data:`_UNSAFE_TEXT_CHARS` (NUL, other C0 controls, DEL) are stripped. diff --git a/src/icalendar/prop/uid.py b/src/icalendar/prop/uid.py index 6fbdd16d8..88d06ea68 100644 --- a/src/icalendar/prop/uid.py +++ b/src/icalendar/prop/uid.py @@ -40,7 +40,10 @@ def ical_value(self) -> str: return self.uid def __repr__(self) -> str: - """repr(self)""" + """repr(self) + + :meta private: + """ return f"{self.__class__.__name__}({self.uid!r})" from icalendar.param import FMTTYPE, LABEL, LINKREL diff --git a/src/icalendar/prop/uri.py b/src/icalendar/prop/uri.py index d8f3abccd..bc115d221 100644 --- a/src/icalendar/prop/uri.py +++ b/src/icalendar/prop/uri.py @@ -124,7 +124,10 @@ def uri(self) -> str: return str(self) def __repr__(self) -> str: - """repr(self)""" + """repr(self) + + :meta private: + """ return f"{self.__class__.__name__}({self.uri!r})" from icalendar.param import FMTTYPE, GAP, LABEL, LANGUAGE, LINKREL, RELTYPE, VALUE diff --git a/src/icalendar/prop/xml.py b/src/icalendar/prop/xml.py index 388747924..4c885c029 100644 --- a/src/icalendar/prop/xml.py +++ b/src/icalendar/prop/xml.py @@ -48,7 +48,10 @@ def _decode(data: bytes) -> str | bytes: - """Decode XML bytes with the encoding of their XML declaration, if they have one.""" + """Decode XML bytes with the encoding of their XML declaration, if they have one. + + :meta private: + """ match = _DECLARED_ENCODING_OF_BYTES.match(data) if match: with suppress(LookupError, UnicodeDecodeError): @@ -145,6 +148,8 @@ def __new__( def _parse(self) -> Element: """Parse the text of this value as XML. + :meta private: + Raises: xml.etree.ElementTree.ParseError: If the value is not XML. """ @@ -283,6 +288,8 @@ def to_xcal(self, element: Element) -> None: def _get_normal_form(self) -> tuple | str: """What equality compares: the XML elements, or the text. + :meta private: + The text is compared if the value is not XML, or if it has a document type, which could make the XML much larger than the text. The normal form is computed once. @@ -297,6 +304,8 @@ def _get_normal_form(self) -> tuple | str: def _get_elements(self) -> tuple: """The elements of the XML in document order, without recursion. + :meta private: + Each element has its tag with the namespace, its sorted attributes, its text, its tail, and its number of children. @@ -315,7 +324,10 @@ def _get_elements(self) -> tuple: return tuple(elements) def __eq__(self, other: object) -> bool: - """Compare the XML of two vXml values.""" + """Compare the XML of two vXml values. + + :meta private: + """ if not isinstance(other, vXml): return NotImplemented return ( @@ -324,12 +336,18 @@ def __eq__(self, other: object) -> bool: ) def __ne__(self, other: object) -> bool: - """The opposite of ``==``.""" + """The opposite of ``==``. + + :meta private: + """ result = self.__eq__(other) return result if result is NotImplemented else not result def __hash__(self) -> int: - """Hash what two vXml values compare.""" + """Hash what two vXml values compare. + + :meta private: + """ return hash(self._get_normal_form()) @classmethod @@ -344,6 +362,8 @@ def _preserve_indentation_of_xcal_extension_properties( ) -> Iterator[None]: """Keep the whitespace in the elements of XML properties in xCal. + :meta private: + :func:`xml.etree.ElementTree.indent` changes the whitespace in elements. In this context, the elements of XML properties are replaced by empty elements. diff --git a/src/icalendar/tests/test_jcal_recursion.py b/src/icalendar/tests/test_jcal_recursion.py index ffe3930bc..d7b7b8163 100644 --- a/src/icalendar/tests/test_jcal_recursion.py +++ b/src/icalendar/tests/test_jcal_recursion.py @@ -36,7 +36,7 @@ def _nested_jcal(depth: int) -> list: def _nesting_depth(component: Component) -> int: - """Count how many levels of single-child nesting ``component`` has.""" + """Count the levels of single-child nesting ``component`` has.""" depth = 0 while component.subcomponents: depth += 1 diff --git a/src/icalendar/timezone/tzid.py b/src/icalendar/timezone/tzid.py index 304291ffd..f9cbeb89f 100644 --- a/src/icalendar/timezone/tzid.py +++ b/src/icalendar/timezone/tzid.py @@ -102,11 +102,15 @@ def tzid_from_dt(dt: datetime | time) -> str | None: def _add_equivalent_ids(value: tuple | dict | set): - """This adds equivalent ids/ + """This adds equivalent IDs. + + :meta private: As soon as one timezone implementation used claims their equivalence, they are considered equivalent. - Have a look at icalendar.timezone.equivalent_timezone_ids. + + See also: + :mod:`timezone.equivalent_timezone_ids ` """ if isinstance(value, set): for tzid in value: diff --git a/src/icalendar/timezone/tzp.py b/src/icalendar/timezone/tzp.py index 138c399bf..d56cff242 100644 --- a/src/icalendar/timezone/tzp.py +++ b/src/icalendar/timezone/tzp.py @@ -27,13 +27,12 @@ class TZP: """This is the timezone provider proxy. - If you would like to have another timezone implementation, + To use another timezone implementation, you can create a new one and pass it to this proxy. All of icalendar will then use this timezone implementation. """ def __init__(self, provider: str | TZProvider = DEFAULT_TIMEZONE_PROVIDER) -> None: - """Create a new timezone implementation proxy.""" self.use(provider) def use_pytz(self) -> None: @@ -49,7 +48,10 @@ def use_zoneinfo(self) -> None: self._use(ZONEINFO()) def _use(self, provider: TZProvider) -> None: - """Use a timezone implementation.""" + """Use a timezone implementation. + + :meta private: + """ self.__tz_cache = {} self.__guessed_ids = {} self.__provider = provider @@ -214,6 +216,8 @@ def timezone(self, tz_id: str) -> tzinfo | None: def _lookup_ids(self, tz_id: str) -> Iterator[tuple[str, bool]]: """Yield ``(id, is_global_guess)`` tuples to try, best match first. + :meta private: + 1. The cleaned ID, without any surrounding ``/``. 2. The Olson name of a Windows timezone (for example, ``W. Europe Standard Time`` -> ``Europe/Berlin``). diff --git a/src/icalendar/timezone/zoneinfo.py b/src/icalendar/timezone/zoneinfo.py index 3cc969ccd..4fcdd2751 100644 --- a/src/icalendar/timezone/zoneinfo.py +++ b/src/icalendar/timezone/zoneinfo.py @@ -49,7 +49,10 @@ def utc(self) -> zoneinfo.ZoneInfo: @property def _available_timezones(self) -> set: - """Return available timezones, initializing lazily on first access.""" + """Return available timezones, initializing lazily on first access. + + :meta private: + """ if self._available_timezones_cache is None: with self._init_lock: # Double-check after acquiring lock @@ -110,7 +113,10 @@ def create_timezone(self, tz: Timezone) -> tzinfo: raise ValueError(f"Invalid iCalendar VTIMEZONE: {e}") from e def _create_timezone(self, tz: Timezone) -> tzinfo: - """Create a timezone and maybe fail""" + """Create a timezone and maybe fail. + + :meta private: + """ file = StringIO(tz.to_ical().decode("UTF-8", "replace")) return tzical(file).get() From c34fbbbfed7cc209b6092f2096a819d7e1d13826 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 18 Nov 2026 23:11:52 -0800 Subject: [PATCH 2/4] ruff --- src/icalendar/attr/__init__.py | 3 ++- src/icalendar/timezone/tzid.py | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/icalendar/attr/__init__.py b/src/icalendar/attr/__init__.py index 08408cbc9..5e068e8bc 100644 --- a/src/icalendar/attr/__init__.py +++ b/src/icalendar/attr/__init__.py @@ -249,7 +249,8 @@ def _set_exdates(self: Component, value) -> None: Parameters: value: A list, as returned by :attr:`exdates`, where each item is a date - or a datetime. Setting an empty list or :obj:`None` removes the EXDATE property. + or a datetime. Setting an empty list or :obj:`None` removes the EXDATE + property. """ _del_exdates(self) if value: diff --git a/src/icalendar/timezone/tzid.py b/src/icalendar/timezone/tzid.py index f9cbeb89f..bcbda3f10 100644 --- a/src/icalendar/timezone/tzid.py +++ b/src/icalendar/timezone/tzid.py @@ -110,7 +110,8 @@ def _add_equivalent_ids(value: tuple | dict | set): they are considered equivalent. See also: - :mod:`timezone.equivalent_timezone_ids ` + :mod:`timezone.equivalent_timezone_ids + ` """ if isinstance(value, set): for tzid in value: From ec1db39386f05e2a7b0450732529e7fcbe5b3923 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 18 Nov 2026 23:12:20 -0800 Subject: [PATCH 3/4] Document private Sphinx flag --- docs/contribute/documentation/style-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/contribute/documentation/style-guide.rst b/docs/contribute/documentation/style-guide.rst index 2e5098c84..7918adae0 100644 --- a/docs/contribute/documentation/style-guide.rst +++ b/docs/contribute/documentation/style-guide.rst @@ -300,6 +300,9 @@ The following docstrings items are the most frequently used in icalendar, althou Summary Docstrings must begin with a one-line summary of the Python object, terminated by a period. +Private flag + Use `:meta private: `_ after the summary for "private" or :ref:`internal-use-only` methods. + Description When the one-line summary is insufficient to describe the Python object, then write an overall description of what it does, without going into details of how it does it. Leave implementation details to the code, and optionally inline code comments. From e1f2a2f1fafbd9b7eb5f4770e93379a4ac37eed4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 19 Nov 2026 00:00:18 -0800 Subject: [PATCH 4/4] Restore accidentally deleted import --- src/icalendar/prop/dt/base.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/icalendar/prop/dt/base.py b/src/icalendar/prop/dt/base.py index 44ae87648..a1af2493f 100644 --- a/src/icalendar/prop/dt/base.py +++ b/src/icalendar/prop/dt/base.py @@ -37,6 +37,8 @@ def __eq__(self, other: object) -> bool: def __hash__(self) -> int: return hash(self.dt) + from icalendar.param import RANGE, RELATED, TZID + def __repr__(self) -> str: """String representation.