Calendar: calendar.ical, calendar.google

calendar.ical

Fetches and parses a public ICS feed. This is the calendar source actually in use (see configs/dev.yml’s stanstorp/school_work sources).

sources:
  school_work:
    source: calendar.ical
    params:
      url: https://cal.vklass.se/....ics

Params

pydantic model todays_paper_web.widgets.calendar.ical.ICalendarParams[source]

Bases: DataSourceParams

field url: str [Required]

The .ics feed URL, fetched fresh on every .fetch() call.

Returns

An ICalendarModel wrapping the parsed feed, with:

  • .walk(name=None) — delegates straight to icalendar.Calendar.walk(). ical.walk('vevent') iterates every VEVENT component as-is, without expanding recurring events (a weekly RRULE event appears once, at its original occurrence, however far in the past).

  • .eventsOn(day) / .eventsBetween(start, end) — use these instead when a screen needs “what’s happening today/this week”: they expand recurring events into their concrete occurrences within the given range via recurring_ical_events, and return them sorted by start time.

{% for event in source("school_work").walk('vevent') %}
    <text>{{ event.get('summary') }}</text>
{% endfor %}

calendar.google

Reads events from a Google Calendar via the Calendar API. Requires a one-time local OAuth login before it will return anything.

One-time setup

  1. Create an OAuth client (Desktop app) in the Google Cloud Console for the Calendar API, and download its credentials as google_client_secret.json in the server’s working directory.

  2. Run uv run python todays_paper_web/widgets/calendar/google-cli.py once. It opens a browser login flow and writes token.json next to it, which is what calendar.google reads at runtime; the token is refreshed automatically as long as it stays valid.

Params

pydantic model todays_paper_web.widgets.calendar.google.GoogleCalendarParams[source]

Bases: DataSourceParams

field calendarId: str [Required]

The calendar to read, e.g. primary or a shared calendar’s id.

field maxResults: int [Required]

Max number of upcoming events to return.

Returns

A list of raw event dicts as returned by the Google Calendar API’s events.list, ordered by start time, with each event’s start.dateTime parsed into a datetime. Returns {} if token.json doesn’t exist yet (setup not done) or if the API call fails.