Merge branch 'main' into jenkins/zshkoor/setup-py-updated-56cf018

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: setup python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 

.github/workflows/pypi-publish.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - name: setup python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.8
 

CHANGELOG.rst

@@ -13,9 +13,49 @@ Change Log
 
 Unreleased
 ----------
+
+[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
 --------------------

README.rst

@@ -14,60 +14,13 @@ 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
-***************
+Getting Started with Development
+********************************
 
-Developing
-==========
-
-One Time Setup
---------------
-.. code-block::
-
-  # Clone the repository
-  git clone [email protected]:openedx/openedx-events.git
-  cd openedx-events
-
-  # Set up a virtualenv using virtualenvwrapper with the same name as the repo and activate it
-  mkvirtualenv -p python3.8 openedx-events
-
-Every time you develop something in this repo
----------------------------------------------
-.. code-block::
-
-  # Activate the virtualenv
-  workon openedx-events
-
-  # Grab the latest code
-  git checkout main
-  git pull
-
-  # Install/update the dev requirements
-  make requirements
-
-  # Run the tests and quality checks (to verify the status before you make any changes)
-  make validate
-
-  # Make a new branch for your changes
-  git checkout -b <your_github_username>/<short_description>
-
-  # Using your favorite editor, edit the code to make your change.
-  vim …
-
-  # Run your new tests
-  pytest ./path/to/new/tests
-
-  # Run all the tests and quality checks
-  make validate
-
-  # Commit all your changes
-  git commit …
-  git push
-
-  # Open a PR and ask for review.
+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,

docs/decisions/0012-producing-to-event-bus-via-settings.rst

@@ -1,4 +1,4 @@
-11. Enable producing to event bus via settings
+12. Enable producing to event bus via settings
 ##############################################
 
 Status

docs/decisions/0013-special-exam-submission-and-review-events.rst

@@ -0,0 +1,51 @@
+13. Event definitions for special exam post-submission and review
+#################################################################
+
+Status
+******
+
+**Draft** 2023-10-02
+
+Context
+*******
+
+About Special Exams:
+====================
+* Course subsections that have an `exam_type` have additional logic that governs completion, grading, credit requirements, and more based on the `exam_type` value (e.g. timed, proctored, etc).
+* These subsections are also known as **Special Exams**.
+    * NOTE: The events described in this document will only be produced/consumed in the context of **Special Exams**.
+* Course subsections that do not have an `exam_type` configured may still have a grading policy named 'Exam'. This type of content does not have the exam user experience and is not governed by any exam specific logic.
+
+The New Exams IDA:
+==================
+* A new backend for exams called `edx-exams` is being developed (See the `exams IDA ADR <https://github.com/openedx/edx-proctoring/blob/master/docs/decisions/0004-exam-ida.rst>`_ for more info).
+* We are currently working to use the event bus to trigger the downstream effects whenever an exam attempt is submitted or reviewed.
+    * For example, when an exam attempt is submitted, we will want to make sure `edx-platform` knows to mark the exam subsection as completed.
+
+
+Decision
+********
+
+Where these events will be produced/consumed:
+=============================================
+
+* `edx-exams` will produce these events.
+    * NOTE: There is no plan to have the legacy exams backend, `edx-proctoring`, produce these events.
+* `edx-platform` will consume these events in order to handle all behavior as it pertains to the state of an exam subsection.
+
+Event Definitions:
+==================
+* We will define the events that as planned in `the ADR for events in edx-exams <https://github.com/edx/edx-exams/blob/main/docs/decisions/0004-downstream-effect-events.rst>`_.
+
+Note on the Event Data/Signal Names:
+====================================
+We are using the prefix "Exam" as opposed to the prefix "Special_Exam" for these events because **Special Exams** will likely be the only type of exam that will be of concern to developers in the context of events for the forseeable future.
+
+
+Consequences
+************
+
+* `edx-exams` will emit events via the event bus to send information without needing a response.
+* Since, `edx-exams` already recieves and responds to REST requests, we will avoid creating circular dependencies because `edx-exams` will not need to send REST requests itself.
+* These events are dynamic, in that they can also be consumed by other services/applications as needed in the future.
+

docs/decisions/0014-new-event-bus-producer-config.rst

@@ -0,0 +1,65 @@
+13. Change event producer config settings
+#########################################
+
+Status
+******
+
+**Accepted**
+
+Context
+*******
+
+In a previous ADR, we set the structure for the event bus producing configuration to a dictionary like the following:
+
+.. code-block:: python
+
+    { 'org.openedx.content_authoring.xblock.published.v1': [
+           {'topic': 'content-authoring-xblock-lifecycle', 'event_key_field': 'xblock_info.usage_key', 'enabled': True},
+           {'topic': 'content-authoring-xblock-published', 'event_key_field': 'xblock_info.usage_key', 'enabled': False},
+       ],
+       'org.openedx.content_authoring.xblock.deleted.v1': [
+           {'topic': 'content-authoring-xblock-lifecycle', 'event_key_field': 'xblock_info.usage_key', 'enabled': True},
+       ],
+   }
+
+While attempting to implement this for edx-platform, we came across some problems with using this structure. In particular, it results in ambiguity
+because maintainers can accidentally add something like
+``{'topic': 'content-authoring-xblock-lifecycle', 'event_key_field': 'xblock_info.usage_key', 'enabled': True}`` and
+``{'topic': 'content-authoring-xblock-lifecycle', 'event_key_field': 'xblock_info.usage_key', 'enabled': False}`` to the same event_type.
+Moreover, enabling/disabling an existing event/topic pair requires reaching into the structure, searching for the dictionary with the correct topic, and modifying
+the existing object, which is awkward.
+
+This ADR aims to propose a new structure that will provide greater flexibility in using this configuration.
+
+Decision
+********
+
+The new EVENT_BUS_PRODUCER_CONFIG will have the following configuration format:
+
+.. code-block:: python
+
+   # .. setting_name: EVENT_BUS_PRODUCER_CONFIG
+   # .. setting_default: {}
+   # .. setting_description: Dictionary of event_types to dictionaries for topic related configuration.
+   #    Each topic configuration dictionary uses the topic as a key and contains a flag called `enabled`
+   #    denoting whether the event will be and `event_key_field` which is a period-delimited string path
+   #    to event data field to use as event key.
+   #    Note: The topic names should not include environment prefix as it will be dynamically added based on
+   #    EVENT_BUS_TOPIC_PREFIX setting.
+   EVENT_BUS_PRODUCER_CONFIG = {
+       'org.openedx.content_authoring.xblock.published.v1': {
+           'content-authoring-xblock-lifecycle': {'event_key_field': 'xblock_info.usage_key', 'enabled': False},
+           'content-authoring-xblock-published': {'event_key_field': 'xblock_info.usage_key', 'enabled': True}
+       },
+       'org.openedx.content_authoring.xblock.deleted.v1': {
+           'content-authoring-xblock-lifecycle': {'event_key_field': 'xblock_info.usage_key', 'enabled': True},
+       },
+   }
+
+A new ``merge_producer_configs`` method will be added to openedx-events.event_bus to make it easier to correctly determine the config map from multiple sources.
+
+Consequences
+************
+
+* As long as the implementing IDA calls ``merge_producer_configs``, maintainers can add existing topics to new event_types without having to recreate the whole dictionary
+* There is no ambiguity about whether an event/topic pair is enabled or disabled

docs/decisions/index.rst

@@ -17,3 +17,5 @@ Architectural Decision Records (ADRs)
    0010-multiple-event-types-per-topic
    0011-depending-on-multiple-event-bus-implementations
    0012-producing-to-event-bus-via-settings
+   0013-special-exam-submission-and-review-events
+   0014-new-event-bus-producer-config

openedx_events/__init__.py

@@ -5,4 +5,4 @@
 more information about the project.
 """
 
-__version__ = "8.6.0"
+__version__ = "9.2.0"

openedx_events/analytics/__init__.py

@@ -0,0 +1,6 @@
+"""
+Package where events related to the analytics subdomain are implemented.
+
+The analytics subdomain corresponds to {Architecture Subdomain} defined in
+the OEP-41.
+"""

openedx_events/analytics/data.py

@@ -0,0 +1,30 @@
+"""
+Data attributes for events within the architecture subdomain ``analytics``.
+
+These attributes follow the form of attr objects specified in OEP-49 data
+pattern.
+"""
+
+from datetime import datetime
+
+import attr
+
+
+@attr.s(frozen=True)
+class TrackingLogData:
+    """
+    Data describing tracking events.
+
+    Arguments:
+        name (str): event name
+        timestamp (datetime): timestamp of the event
+        data (str): json string representation of a dictionary with extra data (optional),
+                    e.g. {"course_id": "course-v1:edX+DemoX+Demo_Course"}
+        context (dict): json string representation of a dictionary of context data
+            defined in https://edx.readthedocs.io/projects/devdata/en/latest/internal_data_formats/tracking_logs/
+    """
+
+    name = attr.ib(type=str)
+    timestamp = attr.ib(type=datetime)
+    data = attr.ib(type=str)
+    context = attr.ib(type=str)

openedx_events/analytics/signals.py

@@ -0,0 +1,23 @@
+"""
+Standardized signals definitions for events within the architecture subdomain ``analytics``.
+
+All signals defined in this module must follow the name and versioning
+conventions specified in OEP-41.
+
+They also must comply with the payload definition specified in
+docs/decisions/0003-events-payload.rst
+"""
+
+from openedx_events.analytics.data import TrackingLogData
+from openedx_events.tooling import OpenEdxPublicSignal
+
+# .. event_type: org.openedx.analytics.tracking.event.emitted.v1
+# .. event_name: TRACKING_EVENT_EMITTED
+# .. event_description: emitted when a tracking log is created.
+# .. event_data: TrackingLogData
+TRACKING_EVENT_EMITTED = OpenEdxPublicSignal(
+    event_type="org.openedx.analytics.tracking.event.emitted.v1",
+    data={
+        "tracking_log": TrackingLogData,
+    }
+)