Skip to content

from_ical() should only raise ICalParsingError #1448

Open

Description

@niccokunzmann

We have from_jcal() which provides a really nice interface to help us understand where we hit a problem within an JSON structure. In order to reach consistency and remove inconsistencies of the past, from_ical() should only raise ICalParsingError, a subclass of ValueError.

Implementation:

  • create ICalParsingError in icalendar.errors (Subclass of InvalidCalendar)
  • Consistency: make JCalParsingError a subclass of InvalidCalendar
  • When the error is raised, it should mention the line it is in (the line of the property) - optional, can be unknown
  • The error should contain the wrong value, e.g. a malformed date - as an argument and an attribute - consistent formatting ensures that this is mentioned in the same place always and never required to be part of the description. E.g. raise ICalParsingError("Malformed date", value=dt_string, ...) yields: ICalParsingError: Malformed date: 20240399
  • line AND line number should be properties of the error
  • The line MUST be filled when we operate on passed data - optional only e.g. in vProperty types
  • Make sure the line also works after a property value that goes over several lines
  • move all fuzzer catches over to only match ICalParsingError
  • document this as Raises: in the docstring of all such implementations
  • test all implementations of from_ical with all kinds of errors that are there
  • catch/check/replace the current places where the errors are raised (TypeError, ValueError)
    • Create tests for the errors or modify existing tests
    • create a list of places that need working on
    • use the with statement style of JCalParsingError in order to add the line while parsing
    • test that line numbers are not set in certain cases (create a wrapper for that test to avoid duplication)
    • test the attributes of the error message (consistently with a function to avoid duplication and assure nothing is forgotten during development)
    • use test parametrization where possible pytest.mark.parametrize
  • The error message should contain the line number only if given (pytest this unit)
  • Unittest how the arguments create the error message
  • clearly disclose AI usage and make sure before submission that we do not have to look through low quality code, unneeded edits and code duplication

Notes

This is a big issue. Before you start, discuss your strategy of how to go about it to make it work. Invite others for collaboration.

Suggestion

Some places can be started with already:

  1. Create a list of all raise places that can occur during parsing.
  2. sort: which ones raise ValueError - move them over first, e.g. in several PRs (The change does not break the old interface)
  3. discuss how to go about this further.

See also

Activity

  1. binggao1230 commented on Jun 10, 2026

    @binggao1230
    Contributor

    I'd like to help with this, following the phased approach from the suggestion. Here is the strategy I'd follow — feedback welcome before I start.

    Error class design (mirroring JCalParsingError):

    class ICalParsingError(ValueError):
        """Could not parse a part of the iCalendar data."""
    
        def __init__(self, message: str, value=_default_value,
                     line: str | None = None, line_number: int | None = None): ...
    • message, value, line and line_number are attributes; the full message is composed in one place so the value always appears in the same position, e.g. ICalParsingError: Wrong date format: '20240399' (line 5: 'DTSTART;VALUE=DATE:20240399') — the line part only appears when known.
    • A with-statement helper like JCalParsingError.reraise_with_path_added: with ICalParsingError.reraise_with_line(line, line_number): re-raises any ICalParsingError from the block with the line context added.

    Where the line gets attached: ComponentIcalParser.parse_content_lines() and the lazy parser iterate the unfolded Contentlines — wrapping each line's handling there means every value-level error carries the property line whenever we parse passed data, while direct calls such as vDatetime.from_ical("20240399") keep line=None / line_number=None. For folded properties, Contentlines.from_ical would record the physical line number where each logical line starts, so the reported number points at the first line of the folded property.

    Phasing (each step keeps existing except ValueError code working, since ICalParsingError subclasses it):

    1. Add ICalParsingError to icalendar.error with unit tests for message composition and attributes, and migrate the ValueError sites in the value-type from_ical() implementations (inventory below), with a shared parametrized test helper so every type is covered the same way.
    2. Line/line-number attachment in the ical parsers, including the folded-line case, plus tests that line info stays unset for direct type-level calls.
    3. TypeError sites reachable during parsing, moving the fuzzer catches over to ICalParsingError only, and a Raises: docstring sweep.

    Scope check: raise sites that validate programmatic input rather than iCalendar text — e.g. vDuration's "Value MUST be a timedelta instance", the email setters, Event/Todo.DURATION setters — would stay untouched; only text-parsing paths move. Is that the intent?

    Inventory of raise sites in parsing paths (suggestion step 1)

    ValueError in value-type from_ical()s:

    • prop/geo.py (vGeo, 2×), prop/n.py (vN), prop/org.py (vOrg), prop/adr.py (vAdr)
    • prop/binary.py (vBinary), prop/boolean.py (vBoolean), prop/float.py (vFloat, 2×), prop/integer.py (vInt), prop/uri.py (vUri)
    • prop/dt/date.py (vDate), prop/dt/time.py (vTime), prop/dt/datetime.py (vDatetime, 3×), prop/dt/types.py (vDDDTypes), prop/dt/utc_offset.py (vUTCOffset, 2×), prop/dt/period.py (vPeriod)
    • prop/recur/frequency.py, prop/recur/weekday.py, prop/recur/month.py, prop/recur/recur.py

    Parser layer:

    • parser/content_line.py: Contentline.parts() ("Invalid content line", 2×), Contentlines.from_ical
    • parser/parameter.py: Parameters.from_ical ("not a valid parameter string")
    • parser/ical/component.py: "END encountered without an accompanying BEGIN!", property without parent component
    • parser/ical/lazy.py: "BEGIN:x encountered outside of a parent component", "Expected exactly one component"
    • cal/component.py Component.from_ical: "Found multiple components…" / "Found no components…"

    Dual-use (raised in __init__s that run both during parsing and on programmatic construction — case by case): vPeriod "Start time is greater than end time"; the shared validators validate_token / validate_param_value.

    Out of scope (programmatic validation, not parsing): __init__/setter TypeErrors in prop/dt/types.py, duration.py, date.py, utc_offset.py, cal_address.py; parameter.py's jCal conversion TypeError (jCal, not iCal); a few sites such as prop/image.py need an individual check.

    If this sounds right I'd start with step 1 as its own PR — and happy for others to pick up parts in parallel.

    Per the Responsible AI Use policy: the implementation would be done by an AI coding agent (Claude) running under my account and direction, with model and usage disclosed in the commit messages and the change log, as in #1442/#1447.

  2. GAUTAMSANSWAL commented on Jul 9, 2026

    @GAUTAMSANSWAL
    Contributor

    Hi @niccokunzmann and @gaoflow! This is an incredibly thorough and well-thought-out roadmap.

    Since this is a large issue and you mentioned inviting others for collaboration, I would love to team up and take on a clear slice of Step 1. Specifically, I can handle migrating the ValueError raise sites inside the structural property modules (prop/geo.py, prop/n.py, prop/org.py, prop/adr.py, prop/binary.py, prop/boolean.py, prop/float.py, prop/integer.py, and prop/uri.py) to use the new ICalParsingError format, along with writing the associated parametrized unit tests for them.

    If this division of labor sounds good to you both, please let me know so we can coordinate, and I can open a targeted PR for this section!

  3. niccokunzmann commented on Jul 9, 2026

    @niccokunzmann
    MemberAuthor

    Hi,

    the scope check is interesting. On one hand, the errors arise, e.g. a wrong type is passed while parsing. On the other hand, moving from type error to value error breaks Python's idea of what they are for.

    So, I would say that the intent is to only throw that error when parsing and treat everyting else as a bug. The test cases can handle that bit by bit and we can approach more difficult places later on, when there is more clarity of how this works best.

    Yes, thanks for the roadmap! And offering to help! You are free to collaborate as you like.
    My suggestion is that you create one PR for the programmatic minimal interface (it can be adapted later), that could be just the error and a test case file and we merge that. You can help each other through reviews and discussion. Once the some minimum is there, it is easier to have several PRs at the same time to different places. They will go through review and it might take them different amounts of times.
    How would you like to work on it?

    We value the documentation to make the features accessible to developers in a beautiful way, so small code changes to classes are optimally accompanied by improving their documentation and examples. By touching many classes in this issue, it might be more lines of code than expected.

    Thanks for picking this up and giving it so much thought. Please go ahead with your proposal and ping me any time you want!
    Thanks!

  4. niccokunzmann commented on Jul 9, 2026

    @niccokunzmann
    MemberAuthor

    For AI usage, we are struggeling at the moment (us here and the whole FOSS ecosystem) with AI slop, low value PRs or just talkativity overwhealm where human understanding would really help build connection and reduce misunderstanding of intention. So, when you use an agent, please make sure that you follow our AI policy and that we interact with you and not ever directly with your AI, that you fully understand the code and that you enjoy the community!

    Also, as a request, we have the pre-commit hook for AI-prompts. Help the projects by making sure it works for you.

  5. angatha commented on Jul 13, 2026

    @angatha
    Collaborator

    Make sure the line also works after a property value that goes over several lines

    What should line and line_number be for such a case?

    1. line_number is the line number of the first line belonging to the value and line is the unfolded version?
    2. line_number is the line number of the first line belonging to the value and line is the folded version?
    3. line_number encodes from and to line number and line is the unfolded version?
    4. line_number encodes from and to line number and line is the folded version?
  6. GAUTAMSANSWAL commented on Jul 13, 2026

    @GAUTAMSANSWAL
    Contributor

    My intention was for line_number to be the first line of the property and for line to contain the unfolded property. That way the line number points to the original location in the input, while the error message shows the complete property that was parsed. I'm happy to change it if you'd prefer a different approach.

  7. angatha commented on Jul 14, 2026

    @angatha
    Collaborator

    It does not influence the your current work but we need a decision for that once one starts adapting the raise statements. I would prefere one of 1 and 2.

  8. added this to the 8.0.0 milestone on Oct 14, 2026
  9. added a commit that references this issue on Oct 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions