Event schema

[rsgalloway]

This pull request modernizes and expands the event format for drawcal, updates the documentation, and improves the rendering code to support new event features. The main changes include introducing a structured event format with explicit style and marker support, updating the CLI and rendering logic to handle these new features, and providing comprehensive documentation for users.

Event Format Modernization and Backward Compatibility

• Switched from the legacy list-of-dates event format to a structured event object format in both the codebase and example files, supporting start_date, end_date, color, style, and markers fields. Legacy list-based events are still supported for backward compatibility. (README.md, events.json, docs/events.md, [1] [2] [3]
• Updated event validation and normalization logic to use a new normalize_events function, supporting both structured and legacy formats. (lib/drawcal/drawlib.py, lib/drawcal/events.py, [1] [2] [3] [4]

Rendering and CLI Improvements

• Enhanced the rendering logic to support new event styles (filled, rounded, diagonal) and explicit marker rendering, including marker-only events. Added a helper function _draw_event_segment to handle the new styles. (lib/drawcal/drawlib.py, [1] [2] [3] [4] [5] [6]
• Improved CLI error handling for event file loading and drawing errors, and added a short -o alias for the output file argument. (lib/drawcal/cli.py, [1] [2]

Documentation Expansion

• Added a new docs/ folder with detailed guides on event formats, rendering styles, customization, and the Python API. Updated the main README.md to reference these docs and explain the new event format. (README.md, docs/README.md, docs/events.md, docs/rendering.md, docs/customization.md, docs/python-api.md, [1] F2f32f3R1, [2] [3] [4] [5]

Customization and Advanced Usage

• Documented how to customize calendar colors programmatically by mutating module-level color attributes, with caveats about global state. (docs/customization.md, docs/customization.mdR1-R44)

These updates make drawcal more flexible, user-friendly, and extensible, while maintaining compatibility with existing event data.

[Copilot]

Pull request overview

This PR modernizes drawcal’s event schema by introducing a structured event object format (with start_date, end_date, color, style, and markers) while retaining support for the legacy list-of-dates format, and updates rendering/CLI/docs/tests accordingly.

Changes:

• Added a new drawcal.models module with an Event model plus normalization helpers to support both legacy and structured schemas.
• Updated rendering to support new span styles (filled, rounded, diagonal) and explicit marker-only events.
• Expanded documentation and added/updated tests and fixtures for both legacy and structured rendering.

Reviewed changes

Copilot reviewed 17 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_render.py	Adds fixture coverage for both legacy and structured renders; adds behavioral tests for markers and structured semantics.
tests/test_events.py	Adds tests for reading/validating/normalizing structured and marker-only events.
tests/test_cli.py	Adds CLI regression test for clean invalid-JSON error reporting.
tests/fixtures/march-2025-events-v2.json	Adds structured fixture event data for rendering tests.
README.md	Updates README to document the structured event format and links to new docs.
lib/drawcal/models.py	Introduces Event + normalization/validation logic for both schemas.
lib/drawcal/events.py	Switches validation to use the new normalization-based validator.
lib/drawcal/drawlib.py	Updates calendar rendering to use normalized events, new styles, and explicit markers.
lib/drawcal/cli.py	Improves CLI error handling and adds -o alias for --outfile.
events.json	Updates the example events file to the structured schema.
docs/README.md	Adds docs index.
docs/events.md	Documents structured, marker-only, and legacy formats and rules.
docs/rendering.md	Documents span styles, markers, and legacy checkout behavior.
docs/customization.md	Documents programmatic color customization caveats.
docs/python-api.md	Documents Python API usage and return value details.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.