What is needed for "Books" compatible reports?

Development
5

Perplexity prompt:

as an expert in Python and Gramps genealogical software’s source code, describe what is necessary to make a “Report” addon plugin compatible with the “Book” collated report generator. Note any specific unit tests to verify compatibility.
To make a “Report” addon plugin compatible with the “Books” collated report generator in Gramps, you need to consider several key aspects:

  1. Report Class Structure:

    • Ensure your report class inherits from the appropriate base class, typically gramps.gen.plug.report.Report.
    • Implement the write_report() method, which is called by the Book generator.

  2. Option Class:

    • Create an option class that inherits from gramps.gen.plug.menu.MenuReportOptions.
    • Define all necessary options for your report in the add_menu_options() method.

  3. Report Modes:

    • Support multiple report modes, especially REPORT_MODE_BKI (Book Include mode).
    • In your .gpr.py file, include REPORT_MODE_BKI in the report_modes list:
      report_modes = [REPORT_MODE_GUI, REPORT_MODE_CLI, REPORT_MODE_BKI]

  4. Handling Book Context:

    • In your write_report() method, check for the book context:
      if self.doc.doc.book_mode:
    # Adjust report behavior for book inclusion

  5. Document Handling:

    • Use the provided self.doc object for all document operations.
    • Avoid creating new pages or sections unless necessary for your report’s structure.

  6. Localization:

    • Ensure all user-visible strings are properly localized using the _() function.

  7. Error Handling:

    • Implement robust error handling to prevent crashes during book generation.

  8. Performance Considerations:

    • Optimize your report for efficiency, as it may be called multiple times in a book.

Unit Tests for Book Compatibility:

  1. Test Book Mode Detection:

    def test_book_mode_detection(self):
    # Mock a book context
    # Verify that the report behaves correctly in book mode

  2. Test Option Handling:

    def test_book_options(self):
    # Verify that all options are properly handled in book context

  3. Test Document Structure:

    def test_document_structure_in_book(self):
    # Ensure the report doesn't create unnecessary pages/sections in book mode

  4. Test Error Handling:

    def test_error_handling_in_book(self):
    # Simulate various error conditions
    # Verify that errors are handled gracefully without crashing the book generation

  5. Test Localization in Book Context:

    def test_localization_in_book(self):
    # Verify that all strings are properly localized when included in a book

  6. Performance Test:

    def test_performance_in_book(self):
    # Measure the execution time of the report in book mode
    # Compare it with standalone mode to ensure no significant performance degradation

  7. Test Multiple Instances:

    def test_multiple_instances_in_book(self):
    # Simulate including the report multiple times in a book
    # Verify that each instance behaves correctly and independently

By implementing these features and running these unit tests, you can ensure that your Report addon plugin is compatible with the Book collated report generator in Gramps. This will provide a seamless experience for users who want to include your report in their book compilations.

Citations:
[1] Discourse: Need help getting started with a new addon
[2] Discourse: What is needed for "Books" compatible reports?
[3] 5.2 Addons - Gramps
[4] GitHub - gramps-project/addons: Third-party plugins for Gramps genealogy program
[5] Reddit: gramps/comments/gpccyk/best_reports_to_run