Factors for a Useful Open-Source Library

A Case Study on ICalendar Events in Python

You can watch this talk online on Youtube.

Factors for a Useful Open-Source Library

A Case Study on ICalendar Events in Python

by Nicco Kunzmann

Cat next to my phone
© Nicco Kunzmann

Structure

Are you curious about something? Ask instantly so I can fit answers in!

  1. About Me
  2. Learnings from the recurring_ical_events library
  3. Factors for open-source library success
  4. Questions and Answers

Slides: niccokunzmann.github.io/ical-talk-fossasia-2022

About Nicco Kunzmann

Sitting and programming in front of the burner.
© Kirstin Heidler

recurring_ical_events - History

  1. Federated calendar system: Open-Web-Calendar
  2. user-controlled multi-source calendar, no self-hosting required
  3. openwebcalendar.herokuapp.com
  4. Issue: How to display events from ICS files?

recurring_ical_events - History

  1. Decision: new library python-recurring-ical-events

Factor: Your Use Case

  1. Solves your problem.
  2. As small as possible
  3. Easy interface: between(start, end)

Factor: License

  1. open-source
  2. License: LGPL
  3. Not: MIT/Apache
  4. Not: GPL

Factor: Common Use Case

  1. Easy interface: at(a_date) and between(start, end)
  2. Interoperable Base: icalendar

Factor: Documentation First

  1. README first!
  2. How do you want to use it?
  3. Answer a few Stack Overflow questions.

Factor: Feedback

  1. Usage in unknown places
  2. Other users ➡ feedback
  3. Higher quality!

Factor: Test Second

  1. Test-Driven-Development (TDD)
  2. Knowledge not lost but increasing over time
  3. Changes not destructive
  4. long-term maintainability
  5. increasing quality with feedback
  6. Using pytest, more than 600 tests

Factor: Test Second

  1. Find an issue
  2. Get example ICS file
  3. Write tests
  4. Implement change
            def test_only_one_event_present(calendars):
                events = calendars.issue_1.at("20220408")
                assert len(events) == 1

Factor: Complexity Last

  1. Open Specifiation: RFC 5545
  2. Includes:
    1. events & time zones
    2. journal entries, alarms, TODOs, free/busy times

Factor: Complexity Last

          BEGIN:VEVENT
          ... removed lines ...
          DTSTART:20220307T120000Z
          RRULE:FREQ=WEEKLY;BYDAY=MO
          EXDATE:20220314T120000Z
          RDATE:20220326T14000Z
          END:VEVENT

Factor: Ecosystem Relationships

  1. icalendar - read and write ICalendar files
  2. icalevents - same use-case as recurring_ical_events
  3. icspy - create simple events
  4. open-web-calendar - display ICS files as web page
  5. x-wr-timezone - correct X-WR-TIMEZONE issues

All Factors:

  1. Your Use Case ➡ Common Use Case
  2. License
  3. Documentation First
  4. Test Second
  5. Complexity Last
  6. Feedback
  7. Ecosystem Relationships

Thanks for ...

  1. Shower logo shower - the presentation engine
  2. FOSSASIA Summit 2022
  3. Python, my teachers, your attention, the GPL, the support of my family, the smartphone apps I use for development. piwheels.org

This talk by Nicco Kunzmann is licensed under the CC-BY-SA 4.0 License.

Hands On!

  1. Example program:
    niccokunzmann.github.io/ical-talk-fossasia-2022/example.py
  2. Install Python3 and pip
  3. Run 
    pip install recurring-ical-events

Hands On!

          import icalendar, recurring_ical_events
          from urllib.request import urlopen
          ical_string = urlopen("http://tinyurl.com/y24m3r8f").read()
          calendar = icalendar.Calendar.from_ical(ical_string)
          events = recurring_ical_events.of(calendar).at((2019, 3))
          for event in events:
              print("start {} summary {}".format(event["DTSTART"].dt,
                                                 event.get("SUMMARY")))

ICalendar - Why?

  1. Sharing of calendar events around the world
  2. Files: .ics
  3. Used by: Nextloud, Eventyay, Thunderbird, Android, ...

ICalendar - Overview

  1. Version 1.0 from 1997
  2. Current Version 2.0 since 2009

ICalendar - Examples - Page 1

            BEGIN:VCALENDAR
            VERSION:2.0
            CALSCALE:GREGORIAN
            X-WR-CALNAME:FOSSASIA Talks
            BEGIN:VTIMEZONE
            TZID:Asia/Singapore
            ... removed lines ...
            END:VTIMEZONE

ICalendar - Examples - Page 2

          BEGIN:VEVENT
          UID:recurring-ical-events@FOSSASIA2022
          SUMMARY:Nicco's Talk about ICAL events!
          DTSTART;TZID=Asia/Singapore:20220408T213000
          DTEND;TZID=Asia/Singapore:20220408T215500
          
          END:VEVENT
          END:VCALENDAR

ICalendar - Examples - Page 3 - Lunch with Friends

          BEGIN:VEVENT
          ... removed lines ...
          DTSTART:20220307T120000Z
          RRULE:FREQ=WEEKLY;BYDAY=MO
          EXDATE:20220314T120000Z
          RDATE:20220326T14000Z
          END:VEVENT

Future

  1. Open an Issue!
  2. Command line interface?
  3. Generation of VTIMEZONE from Python time zones?

Questions!

  1. e.g. Your experience with ICAL, project ideas, contribution practice, CI, testing, pytest?
  2. Hands-on session next:
    niccokunzmann.github.io/ical-talk-fossasia-2022/example.py