Simplifying & documenting the Tutor Hooks API

Working Groups Dev Experience
,
1

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
5 Likes
2

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.

2 Likes
3

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

4

Is it documented anywhere yet what the translation is from “I want to change an entry in cms/envs/common.py” (e.g. this) to what the corresponding tutor made up string like “common-env-features” or “openedx-lms-common-settings” or “openedx-cms-common-settings” or “mfe-lms-common-settings” is?

I am starting to infer that the “openedx-lms-common-settings” == “lms/envs/common.py” and “openedx-cms-common-settings” == “cms/envs/common.py”, but it’d be great if things were documented, rather than folks like me having to continuously guess and search the forums. It doesn’t help us to know the API if we can’t figure out the magic strings.

1 Like