Document the protocol design in more detail

Author: mgorny

variantlib/plugins/_subprocess.py

@@ -46,6 +46,9 @@ def load_plugins(plugin_apis: list[str]) -> Generator[PluginType]:
         else:
             plugin_instance = plugin_callable
 
+        # We cannot use isinstance() here since some of the PluginType methods
+        # are optional. Instead, we use @abstractmethod decorator to naturally
+        # annotate required methods, and the remaining methods are optional.
         required_attributes = PluginType.__abstractmethods__
         if missing_attributes := required_attributes.difference(dir(plugin_instance)):
             raise TypeError(

variantlib/protocols.py

@@ -7,6 +7,27 @@
 # Must be standalone.
 # =============================================================================== #
 
+"""
+Protocols for the plugin API
+
+This file provides a number of protocols outlining the design of the plugin API.
+The classes serve a dual purpose: they are meant to help plugin authors
+visualize the plugin API, and they can also serve as abstract base classes
+for an actual plugin implementation. This module is intended to be fully
+self-contained and standalone, and it can be easily vendored into a plugin.
+
+The central class is PluginType, which defined the API provided by the plugin.
+The actual API can be implemented as regular methods on a class (optionally
+subclassing PluginType), class methods, static methods or top-level functions
+in a module.
+
+The methods declared as abstract here must be defined by the plugin.
+The remaining methods are optional. If they are not defined, the caller
+assumes a default value equivalent to the implementation provided in the class.
+This means that plugins do not need to define them even if they do not subclass
+the protocol classes.
+"""
+
 from __future__ import annotations
 
 from abc import abstractmethod