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 12468792178

Details

• 70 of 70 (100.0%) changed or added relevant lines in 2 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.05%) to 96.422%

---

Totals
Change from base Build 12452278202:	0.05%
Covered Lines:	4650
Relevant Lines:	4817

---

💛 - 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]

It needs a new line:

>>> from pathlib import Path

# Read a calendar file

Otherwise the comment is considered output.

[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?

[abe-101]

Hi, could you write a test for that?

Sure.
Just wondering why the inline docs str tests are not enough?

[niccokunzmann]

Hi, thanks! I think that the doctests are not enough.

What needs to happen in testing is this:

• write a file with this method, check the file is there and has string content
• write a file with this method and read it with this method, check that the objects are equal

For now, not having any code in the method would also pass the doctests.