collective / icalendar / 31139841965

98%

push

github

feat: Add example() to Journal and FreeBusy (#1632)

Journal and FreeBusy were the only two components in icalendar.cal without
an example() classmethod. This adds them, following the existing
Todo.example() pattern, together with the RFC 5545 example files they load
and usage examples in both class docstrings.

- src/icalendar/tests/journals/example.ics is the RFC 5545, Section 3.6.3
  journal example. Its DESCRIPTION is shortened to one sentence so that the
  docstring example stays unfolded and readable.
- src/icalendar/tests/freebusy/example.ics is the RFC 5545, Section 3.6.4
  free/busy example, verbatim, including its three FREEBUSY periods.
- conftest.py gains journals and freebusy DataSource fixtures so the new
  examples are checked by test_component_has_examples in the same way as the
  existing ones, and both components are added to test_default_example.

See #743. This addresses the Journal and FreeBusy items of that checklist.

AI model: Kiro CLI with claude-opus-5.

How I used it, summarized: I asked it to confirm that issue #743 was still
unclaimed for these components, to verify at main that journal.py and
free_busy.py were the only cal components lacking example(), and then to
implement the Journal and FreeBusy items by mirroring Todo.example(), taking
the example data from RFC 5545 and wiring the new examples into
test_examples.py. The expected output in the docstrings was generated by
running the code rather than written by hand.

Output: (this commit)

I reviewed and validated the output. Running
"pytest src/icalendar/tests/test_examples.py src/icalendar/tests/test_docstrings.py"
goes from 1745 to 1755 passed with no failures; the icalendar.cal.journal and
icalendar.cal.free_busy doctests pass; and reverting only journal.py and
free_busy.py while keeping the tests makes exactly the 10 new cases fail with
"AttributeError: type object 'Journal' has no attribute 'example'". The full
suite shows the same 1203 pre-existing failures befo... (continued)

849 of 869 branches covered (97.7%)

Branch coverage included in aggregate %.

13957 of 14229 relevant lines covered (98.09%)

6.86 hits per line