rst-icalendar-event-tracker (riet)

December 8, 2022 ยท View on GitHub

Python3 script that finds calendar events in easily readable/editable ReST (.rst) <https://en.wikipedia.org/wiki/ReStructuredText>_ files with free-form structure, checks any associated feeds or conditions, and creates iCalendar entries, conky_ configuration snippets, plaintext reports and/or desktop notifications from these.

Basically a kind of simple local-only non-interactive calendar app for those who already know rst, like CLI unixy tools, with built-in RSS-poll/notification functionality.

Repository URLs:

Trivial example for one-off event spec anywhere in source rst file::

Any separate block with :ts: or :ts-start: fields in it (:name: description is an rst "field list" syntax) will be parsed as an event, with title picked-up either from :title:, section title or first line/paragraph (as in this example).

Time spec itself can be anything that "date -d" will accept on the command-line, with special handling for "every X" specs, which will add recurring event.

See cal.rst <cal.rst>_ (use raw view on github and such) for more precise syntax info and an extended example, and rst quickref doc <http://docutils.sourceforge.net/docs/user/rst/quickref.html>_ for more info on rst format itself.

Intended use is creating persistent on-screen notifications either from iCalendar entries generated by this script (and picked-up by some app) or a conky_ configuration snippet, to avoid forgetting things, yet not require editing raw iCalendar files, org-mode_ (special emacs-only markup for such stuff) or using anything but an arbitrary dumb text editor for these.

.. _conky: http://conky.sourceforge.net/ .. _org-mode: http://orgmode.org/

Usage

  • Install script requirements (see below): pip install --user docutils

  • Write free-form rst file with some sections containing some event descriptions (see cal.rst <cal.rst>_ doc/example)::

    Minor chores

    Stuff no one ever remembers doing.

    • Pick up groceries

      :ts: 2018-08-27 12:00

      Running low on salt, don't forget to grab some.

    • Do the laundry

      :ts: every 2w interval

      Pile is in the corner across the room.

    Total Annihilation

    :ts-start: 2018-09-04 21:00 :ts-end: 2018-09-20 21:00

    For behold, the LORD will come in fire And His chariots like the whirlwind, To render His anger with fury, And His rebuke with flames of fire. ... blah blah

  • | Run "riet" script to find all such sections, and e.g. create a conky config snippet out of this: | ./riet cal.rst -c /run/user/1000/conky.calendar | (or an icalendar file for something or other ./riet cal.rst -i cal.ics)

    Be sure to run it with -h/--help to check out misc other options.

  • | Add "catp" line to load/display conky snippet: | echo '${catp /run/user/1000/conky.calendar}' >> ~/.conkyrc

  • Behold (the madness):

    .. figure:: https://raw.githubusercontent.com/mk-fg/rst-icalendar-event-tracker/master/example.conky-calendar.jpg :alt: example.conky-calendar.jpg

  • Put "riet" invocation into crontab to update that calendar section occasionally.

  • Don't forget writing upcoming/recurring stuff down to that .rst file!

Requirements

  • Python 3.x <http://python.org/>_
  • docutils module <https://docutils.readthedocs.io/>_ - rst parser.
  • icalendar module <https://pypi.org/project/icalendar/>_ - only when generating .ics files with -i/--ical option.
  • feedparser module <https://pypi.org/project/feedparser/>_ - only for fetching feeds with -f/--feeds option.
  • libsystemd <https://systemd.io/>_ - to send desktop notifications via DBus.