fix: Rename plugin hook

The plugin hook should always have been named `on_post_sample`.
Naming it `on_post_fit` was a mistake.

Closes #254

doc/plugins.rst

@@ -37,10 +37,10 @@ You can define multiple plugins in the entry points section.  Note that the
 plugin name (here, `names`) is required but is unused.
 
 All :py:class:`stan.plugins.PluginBase` subclasses implement methods which define behavior associated with *events*.
-Currently, there is only one event supported, ``post_fit``.
+There is only one event supported, ``post_sample``.
 
-on_post_fit
------------
+on_post_sample
+--------------
 
 This method defines what happens when sampling has finished and a
 :py:class:`stan.fit.Fit` object is about to be returned to the user.  The
@@ -56,7 +56,11 @@ additional method or changing the behavior or an existing method.
 For example, if you wanted to print the names of parameters you would define a plugin as follows::
 
     class PrintParameterNames(stan.plugins.PluginBase):
-        def on_post_fit(self, fit):
+        def on_post_sample(self, fit, **kwargs):
             for key in fit:
                 print(key)
             return fit
+
+Note that `on_post_sample` accepts additional keyword arguments (``**kwargs``). Accepting
+keyword arguments like this will allow your plugin to be compatible with future versions of the package.
+Future versions of the package could, in principle, add additional arguments to `on_post_sample`.

stan/model.py

@@ -271,7 +271,7 @@ def is_iteration_or_elapsed_time_logger_message(msg: simdjson.Object):
 
             for entry_point in stan.plugins.get_plugins():
                 Plugin = entry_point.load()
-                fit = Plugin().on_post_fit(fit)
+                fit = Plugin().on_post_sample(fit)
             return fit
 
         try:

stan/plugins.py

@@ -25,7 +25,7 @@ class PluginBase(abc.ABC):
     # (<https://docs.openstack.org/stevedore>).  This plugin system follows
     # (approximately) the pattern stevedore labels `ExtensionManager`.
 
-    def on_post_fit(self, fit: stan.fit.Fit) -> stan.fit.Fit:
+    def on_post_sample(self, fit: stan.fit.Fit) -> stan.fit.Fit:
         """Called with Fit instance when sampling has finished.
 
         The plugin can report information about the samples

tests/test_plugins.py

@@ -8,9 +8,9 @@
 
 
 class DummyPlugin(stan.plugins.PluginBase):
-    def on_post_fit(self, fit):
+    def on_post_sample(self, fit, **kwargs):
         """Do nothing other than print a string."""
-        print("In DummyPlugin `on_post_fit`.")
+        print("In DummyPlugin `on_post_sample`.")
         return fit
 
 
@@ -50,9 +50,9 @@ def test_dummy_plugin(monkeypatch, capsys, normal_posterior):
 
 
 class OtherDummyPlugin(stan.plugins.PluginBase):
-    def on_post_fit(self, fit):
+    def on_post_sample(self, fit, **kwargs):
         """Do nothing other than print a string."""
-        print("In OtherDummyPlugin `on_post_fit`.")
+        print("In OtherDummyPlugin `on_post_sample`.")
         return fit