Merge pull request #1312 from pimutils/develop/plugins

basic plugin handling

CHANGELOG.rst

@@ -31,6 +31,7 @@ not released yet
   status of an event with a symbol (e.g. `✓` for accepted, `✗` for declined,
   `?` for tentative); partication status is shown for the email addresses
   configured for the event's calendar
+* NEW support for color theme, command, and formatter plugins
 
 0.11.2
 ======

doc/source/hacking.rst

@@ -31,6 +31,36 @@ Before we will accept your PR, we will ask you to:
  * make sure your patch conforms with :pep:`008` (should be covered by passing
    tests)
 
+Plugins
+-------
+
+Khal now supports plugins, currently for supporting new commands (`example
+command plugin`_), formatting (`example formatting plugin`), and
+colors (`example color plugin`).
+
+If you want to develop a new feature, please check if it can be implemented as
+a plugin.  If you are unsure, please ask us, we will gladly help you and, if
+needed, also extend the plugin API.  We would like to see new functionality
+matured in plugins before we consider integrating it into khal's core.
+
+.. _`example command plugin`: https://github.com/geier/khal_navigate
+.. _`example formatting plugin`: https://github.com/tcuthbert/khal/tree/plugin/example
+.. _`example color plugin`: https://github.com/geier/khal_gruvbox/tree/importlib
+
+
+Color scheme plugins
+*********************
+
+Khal color schemes plugins are only availlable for the `ikhal` interface. They
+are installed as python packages (e.g. `python -m pip install khal_gruvbox`).
+A color scheme plugin must provide an entry point `khal_colorscheme` and contain
+an urwid palette definition. The palette definition is a list of tuples, where
+each tuple contains an attribute name and a color definition.  See the `urwid
+documentation`_ for more information. All currently avaialable attributes can be
+found in `khal's source code`_.
+
+.. _`urwid documentation`: http://urwid.org/manual/displayattributes.html
+.. _`khal's source code`: https://github.com/pimutils/khal/blob/master/khal/ui/colors.py
 
 General notes for developing khal (and lots of other python packages)
 ---------------------------------------------------------------------

khal/_compat.py

@@ -0,0 +1,8 @@
+__all__ = ["importlib_metadata"]
+
+import sys
+
+if sys.version_info >= (3, 10):  # pragma: no cover
+    from importlib import metadata as importlib_metadata
+else:  # pragma: no cover
+    import importlib_metadata