Document vText

[NvyGreen]

Documentation for vText class

• Closes Document Properties with Text from RFC 5545 #742

Description

Added documentation for vText class.

Checklist

• I've added a change log entry to CHANGES.rst.
• I've added or updated tests if applicable.
• I've run and ensured all tests pass locally by following Run tests.
• I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary.

Additional information

---

📚 Documentation preview 📚: https://icalendar--1210.org.readthedocs.build/

[coveralls]

Pull Request Test Coverage Report for Build 22115328829

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 98.091%

---

Totals
Change from base Build 22089382994:	0.0%
Covered Lines:	11382
Relevant Lines:	11597

---

💛 - Coveralls

[niccokunzmann]

Thanks for your PR! It is good to see such an important class documented :)

[niccokunzmann]

It is nice to see you work together on a PR!

[niccokunzmann]

@NvyGreen
Thanks. I see that the CI is failing because we run the code inside the documentation.

On your device, you can run

tox -e py

Or online, you can see the error:

https://github.com/collective/icalendar/actions/runs/22244471369/job/64355366147?pr=1210#step:5:313

It suggests to change the line. You are right - it should be bytes - but for the test cases, I changed print to show the ical output in a way that can be more easily read.

[stevepiercy]

Substantially, this is really good. There's minor syntax issues, and moving the change log where it should go, then it's good to merge. Thank you!

[niccokunzmann]

The tests fail.

This is the output:

Failed example:
    print(event.to_ical())
Expected:
    b'BEGIN:VEVENT\r\nSUMMARY:Project XYZ Final Review\\nConference Room - 3B\\nCome Prepared.\r\nEND:VEVENT\r\n'
Got:
    BEGIN:VEVENT
    SUMMARY:Project XYZ Final Review\nConference Room - 3B\nCome Prepared.
    END:VEVENT

I usually just copy the correct lines from the tests into the place where they should be.

[NvyGreen]

I tried to reproduce the issue on my computer, and this is the result I'm getting. It looks to be the expected result. Can you review and let me know your thoughts?

[niccokunzmann]

Yes. I changed the way that print works in the tests. Maybe that should be changed as it is confusing?
At some point icalendar was Python 2 compatible. Now, it is not. Do you think it should be changed?

[stevepiercy]

Fix ruff formatting.

[niccokunzmann]

ValueError: line 36 of the docstring for icalendar.prop.text.vText has inconsistent leading whitespace: ' Add a SUMMARY to an event:'

[stevepiercy]

Yes. I changed the way that print works in the tests. Maybe that should be changed as it is confusing?
At some point icalendar was Python 2 compatible. Now, it is not. Do you think it should be changed?

Yes.

Alternatively, remove the print statement.

>>> event.to_ical()
b'BEGIN:VEVENT\r\nSUMMARY:Project XYZ Final Review\\nConference Room - 3B\\nCome Prepared.\r\nEND:VEVENT\r\n'

[niccokunzmann]

I opened the issue: #1257
Still, one can copy and paste the doctest error output to solve the issue in this PR.

[NvyGreen]

Yes. I changed the way that print works in the tests. Maybe that should be changed as it is confusing? At some point icalendar was Python 2 compatible. Now, it is not. Do you think it should be changed?

Got it, thanks for clarifying. I see the examples are run as doctests, so I believe the expected output would need to be changed to match the test/doctest formatting. To avoid confusion around bytes vs str in Python 3, I can update the example to use print(event.to_ical().decode()) instead so it’s clearer for users.
Please review and let me know what you think.