Simplifying & documenting the Tutor Hooks API

Hey all, @regis recently merged some simplifications and documentation improvements to the hooks-based V1 Plugin API. The goal is to make the API more approachable and less ambiguous. We have removed or renamed parts of the API that were particularly susceptible to typos or type-unsafety.

API changes

These changes are live on the nightly and master branches of Tutor. They will be part of the next Tutor release in a few days.

The modules tutor.hooks.actions, tutor.hooks.filters, and tutor.hooks.contexts are no longer part of the API. This change should not affect most developers, who only use the Actions and Filters classes (notice the plural) from tutor.hooks. If it does affect you, though, then you can upgrade easily:

  • Instead of tutor.hooks.actions.get("some:action"), use tutor.hooks.Actions.SOME_ACTION.
  • Instead of tutor.hooks.filters.get("some:filter"), use tutor.hooks.Filters.SOME_FILTER.
  • Instead of tutor.hooks.actions.add("some:action"), use tutor.hooks.Actions.SOME_ACTION.add(). The same applies to the do method.
  • Instead of tutor.hooks.filters.add("some:filter"), use tutor.hooks.Filters.SOME_FILTER.add(). The same applies to the add_item, add_items, apply, and iterate methods.
  • Instead of tutor.hooks.contexts.enter, use tutor.core.hooks.contexts.enter.

Doc improvements

We’ve added a new landing page for Plugins and reorganized all hooks-related content under Reference.

In a few days, the changes will be visible on the official docs site. If you want to see them now, you can:

  • Check out Tutor’s master or nightly branch and git pull
  • pip install -r requirements/docs.txt
  • make docs
  • Go to file:///<path/to/tutor>/docs/_build/html/index.html in your browser

Thanks for this write-up Kyle!

Actually, the change will be part of Olive starting from the next Tutor release, which should happen in a few days. The change was merged into the master branch :slight_smile: This means that the changes will be visible in the docs very soon.


Whoops, you’re totally right! I corrected my post.