openedx-events 10.5.0
Open edX events from the Hooks Extensions Framework
License: Apache 2.0
Requires Python: >=3.11
Keywords: Python edx

Open edX Events
###############

|pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|
|license-badge| |status-badge|

Open edX Events from Hooks Extensions Framework (`OEP-50`_).

.. _OEP-50: https://open-edx-proposals.readthedocs.io/en/latest/oep-0050-hooks-extension-framework.html

Purpose
*******

This repository implements the necessary tooling and definitions used by the
Hooks Extension Framework to manage the events execution and extra tools.

Getting Started with Development
********************************

Please see the Open edX documentation for `guidance on Python development <https://docs.openedx.org/en/latest/developers/how-tos/get-ready-for-python-dev.html>`_ in this repo.

Deploying
*********

The Open edX Events component is a Python library which doesn't need independent deployment. Therefore,
its setup is reasonably straightforward. First, it needs to be added to your service requirements,
and then it will be installed alongside requirements of the service.

If the service you intend to use is either the LMS or CMS, then the library is installed alongside
their requirements since the Maple release.

Getting Help
************

Documentation
=============

See `documentation on Read the Docs <https://openedx-events.readthedocs.io/en/latest/>`_.

More Help
=========

If you're having trouble, we have discussion forums at
https://discuss.openedx.org where you can connect with others in the
community.

Our real-time conversations are on Slack. You can request a `Slack
invitation`_, then join our `community Slack workspace`_.

For anything non-trivial, the best path is to open an issue in this
repository with as many details about the issue you are facing as you
can provide.

https://github.com/openedx/openedx-events/issues

For more information about these options, see the `Getting Help`_ page.

.. _Slack invitation: https://openedx.org/slack
.. _community Slack workspace: https://openedx.slack.com/
.. _Getting Help: https://openedx.org/getting-help

License
*******

The code in this repository is licensed under the Apache 2.0 license unless
otherwise noted.

Please see `LICENSE.txt <LICENSE.txt>`_ for details.

Contributing
************

Contributions are very welcome.
Please read `How To Contribute <https://openedx.org/r/how-to-contribute>`_ for details.

This project is currently accepting all types of contributions, bug fixes,
security fixes, maintenance work, or new features.  However, please make sure
to have a discussion about your new feature idea with the maintainers prior to
beginning development to maximize the chances of your change being accepted.
You can start a conversation by creating a new issue on this repo summarizing
your idea.

The Open edX Code of Conduct
****************************

All community members are expected to follow the `Open edX Code of Conduct`_.

.. _Open edX Code of Conduct: https://openedx.org/code-of-conduct/

People
******

The assigned maintainers for this component and other project details may be
found in `Backstage`_. Backstage pulls this data from the ``catalog-info.yaml``
file in this repo.

.. _Backstage: https://backstage.openedx.org/catalog/default/component/openedx-events

Reporting Security Issues
*************************

Please do not report security issues in public. Please email security@openedx.org.

.. |pypi-badge| image:: https://img.shields.io/pypi/v/openedx-events.svg
    :target: https://pypi.python.org/pypi/openedx-events/
    :alt: PyPI

.. |ci-badge| image:: https://github.com/openedx/openedx-events/actions/workflows/ci.yml/badge.svg?branch=main
    :target: https://github.com/openedx/openedx-events/actions/workflows/ci.yml
    :alt: CI

.. |codecov-badge| image:: https://codecov.io/github/openedx/openedx-events/coverage.svg?branch=main
    :target: https://codecov.io/github/openedx/openedx-events?branch=main
    :alt: Codecov

.. |doc-badge| image:: https://readthedocs.org/projects/openedx-events/badge/?version=latest
    :target: https://openedx-events.readthedocs.io/en/latest/
    :alt: Documentation

.. |pyversions-badge| image:: https://img.shields.io/pypi/pyversions/openedx-events.svg
    :target: https://pypi.python.org/pypi/openedx-events/
    :alt: Supported Python versions

.. |license-badge| image:: https://img.shields.io/github/license/openedx/openedx-events.svg
    :target: https://github.com/openedx/openedx-events/blob/main/LICENSE.txt
    :alt: License

.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen


Change Log
==========

..
   All enhancements and patches to openedx_events will be documented
   in this file.  It adheres to the structure of https://keepachangelog.com/ ,
   but in reStructuredText instead of Markdown (for ease of incorporation into
   Sphinx documentation and the PyPI description).

   This project adheres to Semantic Versioning (https://semver.org/).

.. There should always be an "Unreleased" section for changes pending release.



Unreleased
__________

[10.5.0] - 2025-08-19
---------------------

Added
~~~~~

* Added new ``COURSE_RERUN_COMPLETED`` event in authoring.


[10.4.0] - 2025-07-21
---------------------

Added
~~~~~

* Added new ``ENTERPRISE_GROUP_DELETED`` event in enterprise.


[10.3.0] - 2025-05-23
---------------------

Added
~~~~~

* Added new ``LTI_PROVIDER_LAUNCH_SUCCESS`` event in learning.


[10.2.1] - 2025-05-13
---------------------

Added
~~~~~

* Adding django52 support.


[10.2.0] - 2024-05-08
---------------------

Added
~~~~~

* Added new ``LIBRARY_BLOCK_PUBLISHED`` event in authoring.
* Added new ``LIBRARY_CONTAINER_PUBLISHED`` event in authoring.

Changed
~~~~~~~
* Deprecated the ``update_blocks`` and ``background`` attributes of various
  content library events in authoring.
* Clarified the use case of various content library events in authoring.

[10.1.0] - 2024-05-01
---------------------

Added
~~~~~

* Added new ``EXTERNAL_GRADER_SCORE_SUBMITTED`` event in learning.
* Add ``ExternalGraderScoreData`` to support this event

[10.0.0] - 2024-04-04
---------------------
Changed
~~~~~~~
* **Breaking change**: LibraryCollectionData now takes only a LibraryCollectionLocator.
* **Breaking change**: LibraryContainerData now takes only a LibraryContainerLocator.

[9.20.0] - 2025-03-15
---------------------

Added
~~~~~

* Added new ``LIBRARY_CONTAINER_CREATED``, ``LIBRARY_CONTAINER_UPDATED`` and ``LIBRARY_CONTAINER_DELETED`` events in content_authoring.
* Adds ``LibraryContainerData`` to support these events

[9.19.0] - 2025-03-14
---------------------

Changed
~~~~~~~

* When ``EVENT_BUS_CONSUMER`` setting is missing or unusable, calling ``consume_indefinitely`` will raise an exception instead of silently exiting.

[9.18.2] - 2025-02-18
---------------------

Changed
~~~~~~~

* Added linkcode Sphinx extension to the documentation.
* Added common_refs.rst file to reuse common references in the documentation.

[9.18.1] - 2025-02-13
---------------------

Changed
~~~~~~~

* Added support for Python 3.12

[9.18.0] - 2025-02-06
---------------------

Added
~~~~~

* Added new course_authoring signal: ``COURSE_IMPORT_COMPLETED``.

[9.17.0] - 2025-01-30
---------------------

Added
~~~~~

* Use edx-lint linter for Open edX Events instances in-line code annotations validation.

[9.16.0] - 2025-01-30
---------------------

Added
~~~~~

* Added support for annotated Python dictionaries as Avro Map type.

[9.15.2] - 2025-01-16
---------------------

Added
~~~~~

* Added new inline code annotation to include triggering information about events.

[9.15.1] - 2024-12-20
---------------------

Changed
~~~~~~~

* Fixed ``event_type`` field in ``FORUM_THREAD_CREATED``, ``FORUM_THREAD_RESPONSE_CREATED``, and ``FORUM_RESPONSE_COMMENT_CREATED`` events in learning.

[9.15.0] - 2024-10-10
---------------------

Changed
~~~~~~~

* Added ``background`` field to ``LibraryCollectionData`` so that senders can specify if handlers can run asynchrounously.

[9.14.1] - 2024-09-17
---------------------

Changed
~~~~~~~

* Fixed event ``LEARNER_CREDIT_COURSE_ENROLLMENT_REVOKED`` so that its serializer can tolerate null nullable fields.

[9.14.0] - 2024-09-12
---------------------

Added
~~~~~

* Adds event ``CONTENT_OBJECT_ASSOCIATIONS_CHANGED``
* Added new ``LIBRARY_COLLECTION_CREATED``, ``LIBRARY_COLLECTION_UPDATED`` and ``LIBRARY_COLLECTION_DELETED`` events in content_authoring.
* Adds ``ContentObjectChangedData``, which inherits from ContentObjectData and adds an optional list of string ``changes``.

Deprecated
~~~~~~~~~~

* Deprecated event ``CONTENT_OBJECT_TAGS_CHANGED`` in favor of ``CONTENT_OBJECT_ASSOCIATIONS_CHANGED``
  Plan to remove after Sumac.

[9.13.0] - 2024-09-05
---------------------

Added
~~~~~~~

* Added new IDV events ``LEARNER_CREDIT_COURSE_ENROLLMENT_REVOKED``, ``IDV_ATTEMPT_CREATED``, ``IDV_ATTEMPT_PENDING``, ``IDV_ATTEMPT_APPROVED``, and ``IDV_ATTEMPT_DENIED`` in learning.

[9.12.0] - 2024-07-31
---------------------

Added
~~~~~~~

* Added new enterprise signal ``LEARNER_CREDIT_COURSE_ENROLLMENT_REVOKED``.

[9.11.0] - 2024-05-15
---------------------

Added
~~~~~~~

* Added new enterprise signals ``LEDGER_TRANSACTION_CREATED``, ``LEDGER_TRANSACTION_COMMITTED``,
  ``LEDGER_TRANSACTION_FAILED``, and ``LEDGER_TRANSACTION_REVERSED``.
* Added a ``UuidAvroSerializer`` to serialize uuid fields.
* Added ``isort`` make target.

[9.10.0] - 2024-05-08
---------------------

Added
~~~~~~~

* Added new ``COURSE_PASSING_STATUS_UPDATED``, ``COURSE_PASSING_STATUS_UPDATED``, ``CCX_COURSE_PASSING_STATUS_UPDATED``, ``CCX_COURSE_PASSING_STATUS_UPDATED``, ``BADGE_AWARDED`` and ``BADGE_REVOKED`` events in learning.

[9.9.2] - 2024-04-18
--------------------

Changed
~~~~~~~

* Updated ``ORASubmissionData`` class.

[9.9.1] - 2024-04-12
--------------------

Changed
~~~~~~~

* Updated Python classifiers to include Python 3.11.

[9.9.0] - 2024-04-11
--------------------
Added
~~~~~~~
* Added new ``ORA_SUBMISSION_CREATED`` event in learning.

[9.8.0] - 2024-04-11
--------------------
Added
~~~~~
* Added support for Python 3.11

[9.7.0] - 2024-04-04
--------------------
Added
~~~~~~~
* Added new ``SUBSIDY_REDEEMED`` and ``SUBSIDY_REDEMPTION_REVERSED`` events in enterprise.

[9.6.0] - 2024-04-01
--------------------
Added
~~~~~~~
* Added new ``CONTENT_OBJECT_TAGGED`` events in content_authoring.

[9.5.2] - 2024-02-13
--------------------
Removed
~~~~~~~
* Remove unused ``MANAGE_STUDENTS_PERMISSION_ADDED`` and ``MANAGE_STUDENTS_PERMISSION_REMOVED`` events in learning

[9.5.1] - 2024-02-12
--------------------
Changed
~~~~~~~
* Fixed recursion error when consuming events on the same service that produced them.

[9.5.0] - 2024-02-07
--------------------
Added
~~~~~
* Adds utility function to reset application state similar to setup/teardown in Django request/response cycle.

[9.4.0] - 2024-01-29
--------------------
Added
~~~~~
* Added new ``COURSE_ACCESS_ROLE_ADDED`` and ``COURSE_ACCESS_ROLE_REMOVED`` events in learning

[9.3.0] - 2024-01-24
--------------------
Changed
~~~~~~~
* Allow new EVENTS_SERVICE_NAME setting to override SERVICE_VARIANT for data source.

[9.2.0] - 2023-11-16
--------------------
Added
~~~~~~~
* Added new COURSE_NOTIFICATION_REQUESTED event in learning

[9.1.0] - 2023-11-07
--------------------
Added
~~~~~~~
* Added new event TRACKING_EVENT_EMITTED.

[9.0.1] - 2023-10-31
--------------------
Changed
~~~~~~~
* Fixed key error in merging event producer configs. Previously, setting only one of `enabled` or `event_key_field` would result in a KeyError being thrown

[9.0.0] - 2023-10-04
--------------------
Changed
~~~~~~~
* Re-licensed this repository from AGPL 3.0 to Apache 2.0
* **Breaking change**: Restructured EVENT_BUS_PRODUCER_CONFIG

[8.9.0] - 2023-10-04
--------------------
Added
~~~~~
* Added new ``FORUM_THREAD_CREATED``, ``FORUM_THREAD_RESPONSE_CREATED``, ``FORUM_RESPONSE_COMMENT_CREATED`` events in learning subdomain

[8.8.0] - 2023-10-02
--------------------
Added
~~~~~
* Added new ``MANAGE_STUDENTS_PERMISSION_ADDED`` and ``MANAGE_STUDENTS_PERMISSION_REMOVED`` events in learning

[8.7.0] - 2023-09-29
--------------------
Added
~~~~~
* Added new ``EXAM_ATTEMPT_SUBMITTED``, ``EXAM_ATTEMPT_REJECTED``, ``EXAM_ATTEMPT_VERIFIED``, ``EXAM_ATTEMPT_RESET``, and ``EXAM_ATTEMPT_ERRORED`` events in learning.

[8.6.0] - 2023-08-28
--------------------
Added
~~~~~
* Added generic handler to allow producing to event bus via django settings.

[8.5.0] - 2023-08-08
--------------------
Changed
~~~~~~~
* Added json de/serialization for EventsMetadata

[8.4.0] - 2023-07-20
--------------------
Added
~~~~~
* Added new ``PROGRAM_CERTIFICATE_AWARDED`` and ``PROGRAM_CERTIFICATE_REVOKED`` events in learning subdomain
* Added new ``ProgramCertificateData`` and ``ProgramData`` data classes supporting the new program certificate events

[8.3.0] - 2023-07-10
--------------------
Added
~~~~~
* Added new XBLOCK_CREATED and XBLOCK_UPDATED events in content_authoring.
* Added new COURSE_CREATED event in content_authoring.
* Added new CONTENT_LIBRARY_CREATED, CONTENT_LIBRARY_UPDATED and CONTENT_LIBRARY_DELETED events in content_authoring.
* Added new LIBRARY_BLOCK_CREATED, LIBRARY_BLOCK_UPDATED and LIBRARY_BLOCK_DELETED events in content_authoring.

[8.2.0] - 2023-06-08
--------------------
Changed
~~~~~~~
* Added new USER_NOTIFICATION_REQUESTED event.

[8.1.0] - 2023-06-06
--------------------
Added
~~~~~
* Store current versions of Avro schemas and add test to ensure valid evolution

[8.0.1] - 2023-05-16
--------------------
Changed
~~~~~~~
* Fixed event_type of XBLOCK_SKILL_VERIFIED signal

[8.0.0] - 2023-05-16
--------------------
Changed
~~~~~~~
* **Breaking change**: Remove ``signal`` argument from consume_events and make_single_consumer

[7.3.0] - 2023-05-15
--------------------
Changed
~~~~~~~
* Made `signal` argument optional in consume_events in preparation for removal

[7.2.0] - 2023-05-03
--------------------
Changed
~~~~~~~
* Added event type as namespace to generated Avro schemas


[7.1.0] - 2023-05-03
--------------------
Added
~~~~~
* Configurable loader for consumer side of Event Bus in ``openedx_events.event_bus``.
* Added management command to load configured consumer and start worker.

Changed
~~~~~~~
* Switch from ``edx-sphinx-theme`` to ``sphinx-book-theme`` since the former is
  deprecated.  See https://github.com/openedx/edx-sphinx-theme/issues/184 for
  more details.

[7.0.0] - 2023-03-07
---------------------
Changed
~~~~~~~
* **Breaking change**: Moved serialize_event_data_to_bytes from openedx_events.event_bus.avro.tests.test_utilities to openedx_events.event_bus.avro.serializer
* **Breaking change**: Moved deserialize_bytes_to_event_data from openedx_events.event_bus.avro.tests.test_utilities to openedx_events.event_bus.avro.deserializer

[6.0.0] - 2023-02-23
---------------------
Changed
~~~~~~~
* **Breaking change**: Moved load_all_events() from openedx_events.tests.utils to openedx_events.tooling

[5.1.0] - 2023-02-07
---------------------
Added
~~~~~~~
* Added support for array type.
* Added new XBLOCK_SKILL_VERIFIED event.
* Added XBlockSkillVerificationData classes.

[5.0.0] - 2023-02-03
--------------------
Changed
~~~~~~~
* **Breaking change**: ``send_event_with_custom_metadata`` changes to accept a single EventsMetadata object rather than all of the fields that go into one. This only directly affects event bus consumer libraries.

Added
~~~~~
* Added ``COURSE_CERTIFICATE_CONFIG_CHANGED`` and ``COURSE_CERTIFICATE_CONFIG_DELETED`` signals for when a course's certificate configuration is updated or deleted

[4.2.0] - 2023-01-24
--------------------
Added
~~~~~
* Added ``send_event_with_custom_metadata``. This will enable event bus consumers to send the event signal with the same metadata fields that were used when the event was produced.

Fixed
~~~~~
* Updated time metadata to include UTC timezone. The original implementation used utcnow(), which could give different results if the time were ever interpreted to be local time. See https://docs.python.org/3/library/datetime.html#datetime.datetime.utcnow
* EventsMetadata minorversion is now fully optional, and doesn't need to be supplied when initializing to get the default of 0.

Changed
~~~~~~~
* Updated send_event with an optional time argument to be used as metadata.

[4.1.1] - 2023-01-23
---------------------
Changed
~~~~~~~
* Use collections.abc import to use with python 3.8 and 3.10.

[4.1.0] - 2023-01-03
---------------------
Added
~~~~~
* Added new XBLOCK_PUBLISHED, XBLOCK_DUPLICATED and XBLOCK_DELETED signals in content_authoring.
* Added XBlockData and DuplicatedXBlockData classes
* Added custom UsageKeyAvroSerializer for opaque_keys UsageKey.

[4.0.0] - 2022-12-01
--------------------
Changed
~~~~~~~
* **Breaking change** Make event_metadata parameter in EventBusProducer send API required

[3.2.0] - 2022-11-30
--------------------
Changed
~~~~~~~
* Add event_metadata parameter to EventBusProducer send API.  **Note:** Calling this method with the new argument will throw an exception with older versions of this library that don't yet support the parameter.

[3.1.0] - 2022-11-22
--------------------
Added
~~~~~
* Configurable loader for producer side of Event Bus in ``openedx_events.event_bus``.

[3.0.1] - 2022-10-31
--------------------
Fixed
~~~~~
* Fix default value for optional fields from "null" to None

[3.0.0] - 2022-10-19
--------------------
* **Breaking change**: Removed (optional) field ``effort`` from ``CourseCatalogData.`` Nothing should be relying on this field as it is not used by Course Discovery in Publisher-enabled setups.

[2.0.0] - 2022-10-18
--------------------
* **Breaking change**: Removed signal ``SUBSCRIPTION_LICENSE_MODIFIED`` and corresponding data class ``SubscriptionLicenseData``. This should only affect experimental event-bus code (which should also have been deleted by now).

[1.0.0] - 2022-09-27
--------------------
* **Breaking Change**: Updated from ``Django 2.0`` to ``Django 3.0``.
* Bump version to 1.x to acknowledge that this is in use in production

[0.14.0] - 2022-09-21
---------------------
Changed
~~~~~~~
* **Breaking change**: Removed ``short_description`` from ``CourseCatalogData``

[0.13.0] - 2022-09-16
---------------------
Added
~~~~~
* Added new event PERSISTENT_GRADE_SUMMARY_CHANGED.

* Improvements in make upgrade command and requirements files.
* Manually update requirements files to fix requirements bot issue with pip/setup tools.
* Change GitHub workflow to community maintained repository health file.

[0.12.0] - 2022-08-16
---------------------
Changed
~~~~~~~
* **Breaking change**: Removed ``org`` and ``number`` fields from ``CourseCatalogData``
  (should only affect unreleased event-bus code, though)

[0.11.1] - 2022-07-28
---------------------
Fixed
~~~~~
* Handle optional (None) values for custom serializers

[0.11.0] - 2022-07-21
---------------------
Added
~~~~~
* Added new content_authoring module with new COURSE_CATALOG_INFO_CHANGED signal

[0.10.0] - 2022-05-20
---------------------
Changed
~~~~~~~
* BREAKING CHANGE: Split AvroAttrsBridge into schema, serialization, and deserialization phases

[0.9.1] - 2022-05-20
--------------------
Changed
~~~~~~~
* Remove assigned_email from SubscriptionLicenseData

[0.9.0] - 2022-04-28
--------------------
Changed
~~~~~~~
* Updated AvroAttrsBridge to handle optional/nullable fields

[0.8.3] - 2022-04-26
--------------------
Changed
~~~~~~~
* Updated AvroAttrsBridge to create schemas from signal data dict rather than individual attrs classes

[0.8.2] - 2022-04-13
--------------------
Changed
~~~~~~~
* Changed openedx_events.learning.data.DiscussionTopicContext to make the group id optional
* Changed DiscussionTopicContext to add a `context` attribute

[0.8.1] - 2022-03-03
--------------------

Added
~~~~~
* Added missing field for event COURSE_DISCUSSIONS_CHANGED

[0.8.0] - 2022-02-25
--------------------
Added
~~~~~
* Added COURSE_DISCUSSIONS_CHANGED for discussion event

Changed
~~~~~~~
* Changed openedx_events/enterprise/LicenseLifecycle class to openedx_events/enterprise/SubscriptionLicenseData
* Changed LicenseCreated signal class to SUBSCRIPTION_LICENSE_MODIFIED signal class

[0.7.1] - 2022-01-13
--------------------
Added
~~~~~
* Added data definition for enterprise/LicenseLifecycle
* Added LicenseCreated signal definition

[0.7.0] - 2022-01-06
--------------------
Added
~~~~~
* Added AvroAttrsBridge class to convert between avro standard and attrs classes

[0.6.0] - 2021-09-15
--------------------
Added
~~~~~
* Add custom formatting class for events responses.
* Add a way to use send method instead of send_robust while testing.

Changed
~~~~~~~
* Remove unnecessary InstantiationError exception.
* Default is send_robust instead of send unless specified otherwise.

[0.5.1] - 2021-08-26
--------------------
Changed
~~~~~~~
* Remove TestCase inheritance from OpenEdxTestMixin.

[0.5.0] - 2021-08-24
--------------------
Added
~~~~~
* Utilities to use while testing in other platforms.

[0.4.1] - 2021-08-18
--------------------
Changed
~~~~~~~
* Remove raise_exception assignment in events metadata.

[0.4.0] - 2021-08-18
--------------------
Added
~~~~~
* Preliminary Open edX events definitions.

[0.3.0] - 2021-08-18
--------------------
Added
~~~~~
* Add tooling needed to create and trigger events in Open edX platform.
* Add Data Attribute classes used as arguments by Open edX Events.


[0.2.0] - 2021-07-28
--------------------
Changed
~~~~~~~

* Update repository purpose.
* Changed max-doc-length from 79 to 120 following community recommendation.

[0.1.3] - 2021-07-01
--------------------
Changed
~~~~~~~

* Update setup.cfg with complete bumpversion configuration.

[0.1.2] - 2021-06-29
--------------------
Changed
~~~~~~~

* Update documentation with current organization info.

[0.1.1] - 2021-06-29
--------------------
Added
~~~~~

* Add Django testing configuration.

[0.1.0] - 2021-04-07
--------------------

Added
~~~~~

* First release on PyPI.