Add from_file and to_file method

[abe-101]

closes #756

---

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

[abe-101]

A few questions:

• Are the Examples in the methods doc strings ran as part of the test suite?
• If yes, is that enough of a test? or should i create a dedicated test file for it?
• Regarding the projects documentation:
  • Should i add a section in usage.rst and how to use the new method?
  • Or better, perhaps i should change the given examples that open a file to instead use the new from_file() method? and seporatly demonstrate how to use from_ical() to parse a str?

[coveralls]

Pull Request Test Coverage Report for Build 12258919799

Details

• 10 of 10 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.009%) to 96.364%

---

Totals
Change from base Build 12219883617:	0.009%
Covered Lines:	4590
Relevant Lines:	4757

---

💛 - Coveralls

[niccokunzmann]

Hi @abe-101, I left a few comments. What are your thoughts?

[niccokunzmann]

You can remove the >>> here

[abe-101]

Are you suggestion to remove the >>> on the lines where there is a comment? or perhaps just remove the comments altogether?

[niccokunzmann]

https://github.com/collective/icalendar/pull/757/files/804ab5297092428c2ec0c440f28d50db5ac686ba#r1878247067

[abe-101]

if I remove the >>> from the comments then the test fails
This doesn't work:

        Example:
            >>> from icalendar import Calendar
            >>> from pathlib import Path
            # Read a calendar file
            >>> cal = Calendar.from_file("src/icalendar/tests/calendars/example.ics")
            # Read multiple calendars
            >>> cals = Calendar.from_file("src/icalendar/tests/calendars/multiple_calendar_components.ics", multiple=True)
            # or pass a Path object
            >>> path = Path("src/icalendar/tests/calendars/example.ics")
            >>> cal = Calendar.from_file(path)

This does work:

        Example:
            >>> from icalendar import Calendar
            >>> from pathlib import Path
            >>> # Read a calendar file
            >>> cal = Calendar.from_file("src/icalendar/tests/calendars/example.ics")
            >>> # Read multiple calendars
            >>> cals = Calendar.from_file("src/icalendar/tests/calendars/multiple_calendar_components.ics", multiple=True)
            >>> # or pass a Path object
            >>> path = Path("src/icalendar/tests/calendars/example.ics")
            >>> cal = Calendar.from_file(path)

[niccokunzmann]

The examples here seem to be the same as above. You can use a temporary file for this.

[abe-101]

I changed the examples to use the to_file() method

[niccokunzmann]

Hi @abe-101, thanks for your PR!

Are the Examples in the methods doc strings ran as part of the test suite?

Yes, if they are behind a >>>

Should i add a section in usage.rst and how to use the new method?

No, I think a proper API documentation is enough for now.

Or better, perhaps i should change the given examples that open a file to instead use the new from_file() method? and seporatly demonstrate how to use from_ical() to parse a str?

If you feel like it, a new PR might be the right place for that. Let's finish this one...

[niccokunzmann]

Suggested change

	>>> # Read a calendar file
	# Read a calendar file

[niccokunzmann]

Hi, could you write a test for that?