feat!: collapse extraneous XBlock mixins

[kdmccormick]

Supporting info

Proposed in this DEPR issue:

• https://github.com/openedx/XBlock/issues/714

excerpt:

The implementations of the XBlock and XBlockAside classes are chopped into about a dozen tiny mixins. This was done many years ago, probably for some mix of reasons including code organization and theoretical reusability. Now, in 2024 in the openedx GitHub org, there are uses of the XBlock, XBlockAside, and XBlockMixin classes, but we do not see uses of any of the other classes or mixins (other than one extraneous reference to HandlersMixin in edx-platform, which can be removed).

Unfortunately, these mixins make it harder/impossible to write robust type constraints for XBlock and XBlockAside. They also make it harder to find code in the XBlock package. See discussion.

The edx-platform upgrade PR is here:

• https://github.com/openedx/edx-platform/pull/34231

Description

Various extraneous classes have been removed from the XBlock API. We believe that most, if not all, XBlock API users will be unaffected by this change.

Diagram

Generated with pyreverse and dot.

Before

After

Change list

• Removed:
  • xblock.XBlockMixin (still available as xblock.core.XBlockMixin)
  • xblock.core.SharedBlockBase (replaced with xblock.core.Blocklike)
  • xblock.internal.Nameable
  • xblock.internal.NamedAttributesMetaclass
  • xblock.django.request.HeadersDict
  • xblock.fields.XBlockMixin (still available as xblock.core.XBlockMixin)
  • xblock.mixins.RuntimeServicesMixin
  • xblock.mixins.ScopedStorageMixin
  • xblock.mixins.IndexInfoMixin
  • xblock.mixins.XmlSerializationMixin
  • xblock.mixins.HandlersMixin
  • xblock.mixins.ChildrenModelMetaclass
  • xblock.mixins.HierarchyMixin
  • xblock.mixins.ViewsMixin
• Added:
  • xblock.core.Blocklike, the new common ancestor of XBlock and XBlockAside, and XBlockMixin, replacing xblock.core.SharedBlockBase.
  • New attributes on xblock.core.XBlockAside, each behaving the same as their XBlock counterpart:
  • usage_key
  • context_key
  • index_dictionary
  • Various new attributes on xblock.core.XBlockMixin, encompassing the functionality of these former classes:
  • xblock.mixins.IndexInfoMixin
  • xblock.mixins.XmlSerializationMixin
  • xblock.mixins.HandlersMixin
• Docs
  • Various docstrings have been improved, some of which are published in the docs.
  • XBlockAside will now be represented in the API docs, right below XBlock on the "XBlock API" page.
  • XBlockMixin has been removed from the docs. It was only ever documented under the "Fields API" page (which didn't make any sense), and it was barely even documented there. We considered adding it back to the "XBlock API" page, but as noted in the class's new docstring, we do not want to encourage any new use of XBlockMixin.

Bumps version from 2.0.0 to 3.0.0.

Testing

Docs

You can preview the doc additions by clicking "Details" on the docs build, hitting "View Docs", and going to the "XBlock API" page).

Homepage: https://docsopenedxorg--718.org.readthedocs.build/projects/xblock/en/718/index.html New XBlockAside generated docs: https://docsopenedxorg--718.org.readthedocs.build/projects/xblock/en/718/xblock.html#xblock.core.XBlockAside

XBlock and XBlockAside attributes

From the root of the repo, you can run this script in order to compare the list of attributes on XBlock/XBlockAside before and after this PR, both for the classes and their instances.

rm -rf dir_before dir_after
mkdir dir_before dir_after

cd dir_before
git switch master
python -c 'from xblock import core; print(*sorted(dir(core.XBlock)), sep="\n")' > block_cls.list
python -c 'from xblock import core; print(*sorted(dir(core.XBlock(None, None, None))), sep="\n")' > block_obj.list
python -c 'from xblock import core; print(*sorted(dir(core.XBlockAside)), sep="\n")'  > aside_cls.list
python -c 'from xblock import core; print(*sorted(dir(core.XBlockAside(None, None, runtime=None))), sep="\n")' > aside_obj.list
cd ..

cd dir_after
git switch kdmccormick/mixins
python -c 'from xblock import core; print(*sorted(dir(core.XBlock)), sep="\n")' > block_cls.list
python -c 'from xblock import core; print(*sorted(dir(core.XBlock(None, None, None))), sep="\n")' > block_obj.list
python -c 'from xblock import core; print(*sorted(dir(core.XBlockAside)), sep="\n")'  > aside_cls.list
python -c 'from xblock import core; print(*sorted(dir(core.XBlockAside(None, None, runtime=None))), sep="\n")' > aside_obj.list
cd ..

diff dir_before list dir_after

This should yield:

diff dir_before/aside_cls.list dir_after/aside_cls.list
39a40
> context_key
49a51
> index_dictionary
62a65
> usage_key
diff dir_before/aside_obj.list dir_after/aside_obj.list
42a43
> context_key
52a54
> index_dictionary
67a70
> usage_key
diff dir_before/block_cls.list dir_after/block_cls.list
0a1
> __annotations__
diff dir_before/block_obj.list dir_after/block_obj.list
0a1
> __annotations__

which indicates that:

• XBlockAsides now have context_key, usage_key and index_dictionary attributes
• XBlocks have a few type annotations now (more to come in #707 )
• The list of attributes is otherwise unchanged

[kdmccormick]

@ormsbee

Can you manually invoke the decorator on Blocklike after it's defined? I haven't done something like this in ages, but I think it'd be something like this?

Good idea. That bit of backwards incompatibility was making me a little nervous, so I'm glad to smooth it out. The syntax ended up being:

Blocklike.needs('field-data')(Blocklike)