Add import calendar events endpoint

[raulcodes]

Proposed change

This PR, along with a frontend PR, adds the ability to import an iCalendar file and add its events to an existing local calendar.
Feature was requested here.

This PR adds an http view at /api/calendars/import with a POST action that accepts a payload:

{
    "file": <ics file>,
    "entity_id": "calendar.test_calendar"
}

and attempts to add the events of the ics file to the pre-existing calendar with given entity_id.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

Corresponding frontend PR

• This PR fixes or closes issue: fixes #
• This PR is related to issue: feature request discussion
• Link to documentation pull request:

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.
• Untested files have been added to .coveragerc.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[home-assistant]

Hi @raulcodes

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Hey there @home-assistant/core, mind taking a look at this pull request as it has been labeled with an integration (calendar) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of calendar can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign calendar Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[home-assistant]

Hey there @allenporter, mind taking a look at this pull request as it has been labeled with an integration (local_calendar) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of local_calendar can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign local_calendar Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[allenporter]

Thank you for your contribution to this feature! I think users will appreciate the ability to upload/import .ics files.

My impression is that the desired behavior for something like this when discussed before would be to create a new calendar with the .ics content, which is typically how this works in the web calendars i've seen. I think doing this through a config flow would be pretty cool, then creating a new calendar with the uploaded events.

[raulcodes]

@allenporter
Thanks for the prompt feedback, it is much appreciated! I would be happy to explore different solutions, including creating a new calendar with the uploaded events.
I initially started with that as my intended solution, where an .ics file upload would be an optional step to the create calendar config flow, but after looking into how Google Calendar and Proton Calendar handle similar flows I opted for adding events to an existing calendar. They both allow for importing events to existing calendars:

Google Calendar

Proton Calendar

But If you would like to stick with creating a calendar on upload, I can rework this!

[allenporter]

I get your point that it would work more generally. If you want to add new API methods to the Calendar Entity model, then it deserves an architecture discussion.

For some reason my intution is that uploading a new .ics file would be the way to go (or also support pulling from a url) -- not sure why. Perhaps its just because in google calendar it already supports import so it feels like something specific to the downstream calendar provider... I don't think i have a super string justification.

Aside: I think folks have been in favor of a calendar export that works across all calendars, e.g. give you an .ics file from any calendar. There was a PR active to support this, but the author didn't follow through on feedback.

[raulcodes]

I think that you made a good point in your original comment about using a config flow. I opened a smaller PR that should set me up to rework this with a config flow.

I understand your intuition. I think adding this as an optional step of the create calendar config flow would be useful as well and that can be the direction I take here.

As for a calendar export, I would be interested in getting to that as well. I think I found the PR you mentioned.

[allenporter]

Awesome, happy to help review both.