From 734057ff71cedbc3b758886189c7aa0dfa3e36c9 Mon Sep 17 00:00:00 2001 From: Shubham Date: Sun, 12 Apr 2026 11:42:58 +0530 Subject: [PATCH 1/4] Add docs in __new__ methods to resolve issue #1118 --- src/icalendar/prop/boolean.py | 27 +++++++++++++++++++++++++++ src/icalendar/prop/cal_address.py | 31 +++++++++++++++++++++++++++++++ src/icalendar/prop/float.py | 28 ++++++++++++++++++++++++++++ src/icalendar/prop/text.py | 29 +++++++++++++++++++++++++++++ src/icalendar/prop/uri.py | 30 ++++++++++++++++++++++++++++++ 5 files changed, 145 insertions(+) diff --git a/src/icalendar/prop/boolean.py b/src/icalendar/prop/boolean.py index 5ca903f51..28d30615c 100644 --- a/src/icalendar/prop/boolean.py +++ b/src/icalendar/prop/boolean.py @@ -55,6 +55,33 @@ class vBoolean(int): def __new__( cls, *args: Any, params: dict[str, Any] | None = None, **kwargs: Any ) -> Self: + """Create a new :class:`~icalendar.prop.boolean.vBoolean` instance. + + This method overrides :py:meth:`int.__new__` because BOOLEAN values + inherit from :class:`int`, which is immutable. The ``__new__`` method + creates the instance and attaches iCalendar property parameters. + + Parameters: + *args: Positional arguments passed to :py:meth:`int.__new__`. + Typically a single Python :class:`bool` or ``0`` / ``1``. + params: Optional property parameters according to :rfc:`5545`. + **kwargs: Additional keyword arguments passed to + :py:meth:`int.__new__`. + + Returns: + A new :class:`~icalendar.prop.boolean.vBoolean` instance with + associated parameters. + + Examples: + .. code-block:: pycon + + >>> from icalendar.prop import vBoolean + >>> b = vBoolean(True, params={"VALUE": "BOOLEAN"}) + >>> bool(b) + True + >>> b.params + Parameters({'VALUE': 'BOOLEAN'}) + """ self = super().__new__(cls, *args, **kwargs) self.params = Parameters(params) return self diff --git a/src/icalendar/prop/cal_address.py b/src/icalendar/prop/cal_address.py index 6893b5fd7..b0e3c5918 100644 --- a/src/icalendar/prop/cal_address.py +++ b/src/icalendar/prop/cal_address.py @@ -66,6 +66,37 @@ def __new__( /, params: dict[str, Any] | None = None, ) -> Self: + """Create a new :class:`~icalendar.prop.cal_address.vCalAddress` instance. + + This method overrides :py:meth:`str.__new__` because CAL-ADDRESS values + inherit from :class:`str`, which is immutable. The ``__new__`` method + decodes bytes if needed, creates the string instance, and attaches + iCalendar property parameters. + + Parameters: + value: Calendar user address, usually a ``mailto`` URI as defined in + :rfc:`5545#section-3.3.3`, passed through + :func:`~icalendar.parser_tools.to_unicode`. + encoding: Encoding used when ``value`` is :class:`bytes`. + params: Optional property parameters according to :rfc:`5545`. + + Returns: + A new :class:`~icalendar.prop.cal_address.vCalAddress` instance with + associated parameters. + + Examples: + .. code-block:: pycon + + >>> from icalendar.prop import vCalAddress + >>> a = vCalAddress( + ... "mailto:jsmith@example.com", + ... params={"CN": "John Smith"}, + ... ) + >>> str(a) + 'mailto:jsmith@example.com' + >>> a.params["CN"] + 'John Smith' + """ value = to_unicode(value, encoding=encoding) self = super().__new__(cls, value) self.params = Parameters(params) diff --git a/src/icalendar/prop/float.py b/src/icalendar/prop/float.py index 1fd286fea..dd5e1c1ee 100644 --- a/src/icalendar/prop/float.py +++ b/src/icalendar/prop/float.py @@ -59,6 +59,34 @@ class vFloat(float): def __new__( cls, *args: Any, params: dict[str, Any] | None = None, **kwargs: Any ) -> Self: + """Create a new :class:`~icalendar.prop.float.vFloat` instance. + + This method overrides :py:meth:`float.__new__` because FLOAT values + inherit from :class:`float`, which is immutable. The ``__new__`` method + creates the instance and attaches iCalendar property parameters. + + Parameters: + *args: Positional arguments passed to :py:meth:`float.__new__`. + Typically a single numeric value or string accepted by + :class:`float`. + params: Optional property parameters according to :rfc:`5545`. + **kwargs: Additional keyword arguments passed to + :py:meth:`float.__new__`. + + Returns: + A new :class:`~icalendar.prop.float.vFloat` instance with + associated parameters. + + Examples: + .. code-block:: pycon + + >>> from icalendar.prop import vFloat + >>> x = vFloat(1.333, params={"VALUE": "FLOAT"}) + >>> float(x) + 1.333 + >>> x.params + Parameters({'VALUE': 'FLOAT'}) + """ self = super().__new__(cls, *args, **kwargs) self.params = Parameters(params) return self diff --git a/src/icalendar/prop/text.py b/src/icalendar/prop/text.py index 94c273296..106446ac0 100644 --- a/src/icalendar/prop/text.py +++ b/src/icalendar/prop/text.py @@ -76,6 +76,35 @@ def __new__( /, params: dict[str, Any] | None = None, ) -> Self: + """Create a new :class:`~icalendar.prop.text.vText` instance. + + This method overrides :py:meth:`str.__new__` because TEXT values + inherit from :class:`str`, which is immutable. The ``__new__`` method + decodes bytes if needed, creates the string instance, and attaches + encoding metadata and iCalendar property parameters. + + Parameters: + value: Raw text passed to :func:`~icalendar.parser_tools.to_unicode` + before constructing the :class:`str` value. + encoding: Encoding used when ``value`` is :class:`bytes`. + params: Optional property parameters according to :rfc:`5545`. + + Returns: + A new :class:`~icalendar.prop.text.vText` instance with + associated parameters. + + Examples: + .. code-block:: pycon + + >>> from icalendar.prop import vText + >>> t = vText("Hello", params={"LANGUAGE": "en"}) + >>> str(t) + 'Hello' + >>> t.encoding + 'utf-8' + >>> t.params + Parameters({'LANGUAGE': 'en'}) + """ value = to_unicode(value, encoding=encoding) self = super().__new__(cls, value) self.encoding = encoding diff --git a/src/icalendar/prop/uri.py b/src/icalendar/prop/uri.py index 4b32cba4c..aca140a4e 100644 --- a/src/icalendar/prop/uri.py +++ b/src/icalendar/prop/uri.py @@ -65,6 +65,36 @@ def __new__( /, params: dict[str, Any] | None = None, ) -> Self: + """Create a new :class:`~icalendar.prop.uri.vUri` instance. + + This method overrides :py:meth:`str.__new__` because URI values inherit + from :class:`str`, which is immutable. The ``__new__`` method decodes + bytes if needed, creates the string instance, and attaches iCalendar + property parameters. + + Parameters: + value: URI string or bytes decoded with ``encoding``, passed through + :func:`~icalendar.parser_tools.to_unicode`. + encoding: Encoding used when ``value`` is :class:`bytes`. + params: Optional property parameters according to :rfc:`5545`. + + Returns: + A new :class:`~icalendar.prop.uri.vUri` instance with associated + parameters. + + Examples: + .. code-block:: pycon + + >>> from icalendar.prop import vUri + >>> u = vUri( + ... "http://example.com/agenda.doc", + ... params={"VALUE": "URI"}, + ... ) + >>> u.uri + 'http://example.com/agenda.doc' + >>> u.params["VALUE"] + 'URI' + """ value = to_unicode(value, encoding=encoding) self = super().__new__(cls, value) self.params = Parameters(params) From 5d72edf00e3ac9ec175b88bf47d5ab666de5423e Mon Sep 17 00:00:00 2001 From: Shubham Date: Sun, 12 Apr 2026 17:20:09 +0530 Subject: [PATCH 2/4] Address code review comments, add changelog entry --- CHANGES.rst | 1 + src/icalendar/prop/boolean.py | 4 ++-- src/icalendar/prop/cal_address.py | 2 +- src/icalendar/prop/float.py | 6 +++--- src/icalendar/prop/text.py | 2 +- src/icalendar/prop/uri.py | 2 +- 6 files changed, 9 insertions(+), 8 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index c30eb3663..cf3c68ec9 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -48,6 +48,7 @@ Bug fixes Documentation ~~~~~~~~~~~~~ +- Document ``__new__`` for :class:`~icalendar.prop.boolean.vBoolean`, :class:`~icalendar.prop.float.vFloat`, :class:`~icalendar.prop.text.vText`, :class:`~icalendar.prop.cal_address.vCalAddress`, and :class:`~icalendar.prop.uri.vUri`, and use the simple ``from icalendar import ...`` style in related docstring examples. - Run ``sphinx-build`` with ``-W`` to turn warnings into errors. :issue:`1306` - Added `sphinx-llms-txt `_ extension to generate :file:`llms.txt` and :file:`llms-full.txt` files for AI/LLM documentation consumption. :issue:`1302` - Fixed CI Vale check reporting and resolved Vale errors. :pr:`1278` diff --git a/src/icalendar/prop/boolean.py b/src/icalendar/prop/boolean.py index 28d30615c..74ff2284e 100644 --- a/src/icalendar/prop/boolean.py +++ b/src/icalendar/prop/boolean.py @@ -35,7 +35,7 @@ class vBoolean(int): .. code-block:: pycon - >>> from icalendar.prop import vBoolean + >>> from icalendar import vBoolean >>> boolean = vBoolean.from_ical('TRUE') >>> boolean True @@ -75,7 +75,7 @@ def __new__( Examples: .. code-block:: pycon - >>> from icalendar.prop import vBoolean + >>> from icalendar import vBoolean >>> b = vBoolean(True, params={"VALUE": "BOOLEAN"}) >>> bool(b) True diff --git a/src/icalendar/prop/cal_address.py b/src/icalendar/prop/cal_address.py index b0e3c5918..14a2c51b7 100644 --- a/src/icalendar/prop/cal_address.py +++ b/src/icalendar/prop/cal_address.py @@ -87,7 +87,7 @@ def __new__( Examples: .. code-block:: pycon - >>> from icalendar.prop import vCalAddress + >>> from icalendar import vCalAddress >>> a = vCalAddress( ... "mailto:jsmith@example.com", ... params={"CN": "John Smith"}, diff --git a/src/icalendar/prop/float.py b/src/icalendar/prop/float.py index dd5e1c1ee..835a27d50 100644 --- a/src/icalendar/prop/float.py +++ b/src/icalendar/prop/float.py @@ -38,7 +38,7 @@ class vFloat(float): .. code-block:: pycon - >>> from icalendar.prop import vFloat + >>> from icalendar import vFloat >>> float = vFloat.from_ical('1000000.0000001') >>> float 1000000.0000001 @@ -80,7 +80,7 @@ def __new__( Examples: .. code-block:: pycon - >>> from icalendar.prop import vFloat + >>> from icalendar import vFloat >>> x = vFloat(1.333, params={"VALUE": "FLOAT"}) >>> float(x) 1.333 @@ -129,7 +129,7 @@ def from_jcal(cls, jcal_property: list) -> Self: """ JCalParsingError.validate_property(jcal_property, cls) if jcal_property[0].upper() == "GEO": - from icalendar.prop import vGeo + from icalendar import vGeo return vGeo.from_jcal(jcal_property) JCalParsingError.validate_value_type(jcal_property[3], float, cls, 3) diff --git a/src/icalendar/prop/text.py b/src/icalendar/prop/text.py index 106446ac0..4c2e2c773 100644 --- a/src/icalendar/prop/text.py +++ b/src/icalendar/prop/text.py @@ -96,7 +96,7 @@ def __new__( Examples: .. code-block:: pycon - >>> from icalendar.prop import vText + >>> from icalendar import vText >>> t = vText("Hello", params={"LANGUAGE": "en"}) >>> str(t) 'Hello' diff --git a/src/icalendar/prop/uri.py b/src/icalendar/prop/uri.py index aca140a4e..e94ed9aaa 100644 --- a/src/icalendar/prop/uri.py +++ b/src/icalendar/prop/uri.py @@ -85,7 +85,7 @@ def __new__( Examples: .. code-block:: pycon - >>> from icalendar.prop import vUri + >>> from icalendar import vUri >>> u = vUri( ... "http://example.com/agenda.doc", ... params={"VALUE": "URI"}, From 797b26e4e08ab6bf4356e5d44e79fc5548b71d5f Mon Sep 17 00:00:00 2001 From: Shubham Date: Sun, 12 Apr 2026 17:25:34 +0530 Subject: [PATCH 3/4] minor changes revert --- src/icalendar/prop/boolean.py | 2 +- src/icalendar/prop/float.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/icalendar/prop/boolean.py b/src/icalendar/prop/boolean.py index 74ff2284e..9d5971883 100644 --- a/src/icalendar/prop/boolean.py +++ b/src/icalendar/prop/boolean.py @@ -35,7 +35,7 @@ class vBoolean(int): .. code-block:: pycon - >>> from icalendar import vBoolean + >>> from icalendar.prop import vBoolean >>> boolean = vBoolean.from_ical('TRUE') >>> boolean True diff --git a/src/icalendar/prop/float.py b/src/icalendar/prop/float.py index 835a27d50..d83bb7309 100644 --- a/src/icalendar/prop/float.py +++ b/src/icalendar/prop/float.py @@ -38,7 +38,7 @@ class vFloat(float): .. code-block:: pycon - >>> from icalendar import vFloat + >>> from icalendar.prop import vFloat >>> float = vFloat.from_ical('1000000.0000001') >>> float 1000000.0000001 @@ -129,7 +129,7 @@ def from_jcal(cls, jcal_property: list) -> Self: """ JCalParsingError.validate_property(jcal_property, cls) if jcal_property[0].upper() == "GEO": - from icalendar import vGeo + from icalendar.prop import vGeo return vGeo.from_jcal(jcal_property) JCalParsingError.validate_value_type(jcal_property[3], float, cls, 3) From c3210b7cedfdae4f502512e2fc16ec672d1cfd79 Mon Sep 17 00:00:00 2001 From: Shubham Date: Sun, 12 Apr 2026 17:34:50 +0530 Subject: [PATCH 4/4] minor doc changes --- CHANGES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index cf3c68ec9..cb17aa8b5 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -48,7 +48,7 @@ Bug fixes Documentation ~~~~~~~~~~~~~ -- Document ``__new__`` for :class:`~icalendar.prop.boolean.vBoolean`, :class:`~icalendar.prop.float.vFloat`, :class:`~icalendar.prop.text.vText`, :class:`~icalendar.prop.cal_address.vCalAddress`, and :class:`~icalendar.prop.uri.vUri`, and use the simple ``from icalendar import ...`` style in related docstring examples. +- Document ``__new__`` for :class:`~icalendar.prop.boolean.vBoolean`, :class:`~icalendar.prop.float.vFloat`, :class:`~icalendar.prop.text.vText`, :class:`~icalendar.prop.cal_address.vCalAddress`, and :class:`~icalendar.prop.uri.vUri` in related docstring examples. :issue: `1118` - Run ``sphinx-build`` with ``-W`` to turn warnings into errors. :issue:`1306` - Added `sphinx-llms-txt `_ extension to generate :file:`llms.txt` and :file:`llms-full.txt` files for AI/LLM documentation consumption. :issue:`1302` - Fixed CI Vale check reporting and resolved Vale errors. :pr:`1278`