openedx-events 11.1.1__py3-none-any.whl

openedx_events/__init__.py

@@ -0,0 +1,8 @@
+"""
+Package where Open edX Events and the necessary tooling are implemented.
+
+These definitions are part of the Hooks Extension Framework, see OEP-50 for
+more information about the project.
+"""
+
+__version__ = "11.1.1"

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 related to tracking events.
+
+    Attributes:
+        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://docs.openedx.org/en/latest/developers/references/internal_data_formats/index.html
+    """
+
+    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,25 @@
+"""
+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_key_field: tracking_log.name
+# .. event_description: Emitted when a tracking log event is emitted.
+# .. event_data: TrackingLogData
+# .. event_trigger_repository: openedx/event-tracking
+TRACKING_EVENT_EMITTED = OpenEdxPublicSignal(
+    event_type="org.openedx.analytics.tracking.event.emitted.v1",
+    data={
+        "tracking_log": TrackingLogData,
+    }
+)

openedx_events/apps.py

@@ -0,0 +1,124 @@
+"""
+openedx_events Django application initialization.
+"""
+import logging
+
+from django.apps import AppConfig
+from django.conf import settings
+
+from openedx_events.event_bus import get_producer
+from openedx_events.exceptions import ProducerConfigurationError
+from openedx_events.tooling import SIGNAL_PROCESSED_FROM_EVENT_BUS, OpenEdxPublicSignal, load_all_signals
+
+logger = logging.getLogger(__name__)
+
+
+def general_signal_handler(sender, signal, **kwargs):  # pylint: disable=unused-argument
+    """
+    Signal handler for producing events to configured event bus.
+    """
+    event_type_producer_configs = getattr(settings, "EVENT_BUS_PRODUCER_CONFIG", {}).get(signal.event_type, {})
+    # event_type_producer_configs should look something like
+    # {
+    #        "topic_a": { "event_key_field": "my.key.field", "enabled": True },
+    #        "topic_b": { "event_key_field": "my.key.field", "enabled": False }
+    # }"
+    if kwargs.get(SIGNAL_PROCESSED_FROM_EVENT_BUS) is True:
+        logger.debug(
+            "Declining to send signal to the Event Bus since that's "
+            f"where it was sent from: {signal.event_type} (preventing recursion)"
+        )
+        return
+
+    event_data = {key: kwargs.get(key) for key in signal.init_data}
+
+    for topic in event_type_producer_configs.keys():
+        if event_type_producer_configs[topic]["enabled"] is True:
+            get_producer().send(
+                signal=signal,
+                topic=topic,
+                event_key_field=event_type_producer_configs[topic]["event_key_field"],
+                event_data=event_data,
+                event_metadata=kwargs["metadata"],
+            )
+
+
+class OpenedxEventsConfig(AppConfig):
+    """
+    Configuration for the openedx_events Django application.
+    """
+
+    name = "openedx_events"
+
+    def _get_validated_signal_config(self, event_type, configuration):
+        """
+        Validate signal configuration format.
+
+        Example expected signal configuration:
+        {
+            "topic_a": { "event_key_field": "my.key.field", "enabled": True },
+            "topic_b": { "event_key_field": "my.key.field", "enabled": False }
+        }
+
+        Raises:
+            ProducerConfigurationError: If configuration is not valid.
+        """
+        if not isinstance(configuration, dict):
+            raise ProducerConfigurationError(
+                event_type=event_type,
+                message="Configuration for event_types should be a dict"
+            )
+        try:
+            signal = OpenEdxPublicSignal.get_signal_by_type(event_type)
+        except KeyError as exc:
+            raise ProducerConfigurationError(message=f"No OpenEdxPublicSignal of type: '{event_type}'.") from exc
+        for _, topic_configuration in configuration.items():
+            if not isinstance(topic_configuration, dict):
+                raise ProducerConfigurationError(
+                    event_type=event_type,
+                    message="One of the configuration objects is not a dictionary"
+                )
+            expected_keys = {"event_key_field": str, "enabled": bool}
+            for expected_key, expected_type in expected_keys.items():
+                if expected_key not in topic_configuration.keys():
+                    raise ProducerConfigurationError(
+                        event_type=event_type,
+                        message=f"One of the configuration object is missing '{expected_key}' key."
+                    )
+                if not isinstance(topic_configuration[expected_key], expected_type):
+                    raise ProducerConfigurationError(
+                        event_type=event_type,
+                        message=(f"Expected type: {expected_type} for '{expected_key}', "
+                                 f"found: {type(topic_configuration[expected_key])}")
+                    )
+        return signal
+
+    def ready(self):
+        """
+        Read `EVENT_BUS_PRODUCER_CONFIG` setting and connects appropriate handlers to the events based on it.
+
+        Example expected configuration:
+        {
+            "org.openedx.content_authoring.xblock.deleted.v1" : {
+                "topic_a": { "event_key_field": "xblock_info.usage_key", "enabled": True },
+                "topic_b": { "event_key_field": "xblock_info.usage_key", "enabled": False }
+            },
+            "org.openedx.content_authoring.course.catalog_info.changed.v1" : {
+                "topic_c": {"event_key_field": "course_info.course_key", "enabled": True }
+            }
+        }
+
+        Raises:
+            ProducerConfigurationError: If `EVENT_BUS_PRODUCER_CONFIG` is not valid.
+        """
+        load_all_signals()
+        signals_config = getattr(settings, "EVENT_BUS_PRODUCER_CONFIG", {})
+        if not isinstance(signals_config, dict):
+            raise ProducerConfigurationError(
+                message=("Setting 'EVENT_BUS_PRODUCER_CONFIG' should be a dictionary with event_type as"
+                         " key and list or tuple of config dictionaries as values")
+            )
+        for event_type, configurations in signals_config.items():
+            signal = self._get_validated_signal_config(event_type, configurations)
+            signal.connect(general_signal_handler)
+        return super().ready()

openedx_events/content_authoring/__init__.py

@@ -0,0 +1,7 @@
+"""
+Package where events related to the ``content_authoring`` subdomain are implemented.
+"""
+# Comment broken up to deal with line-length issues with the long URL
+
+# The ``content_authoring`` subdomain corresponds to {Architecture Subdomain} defined in OEP-41.
+# https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html

openedx_events/content_authoring/data.py

@@ -0,0 +1,250 @@
+"""
+Data attributes for events within the architecture subdomain ``content_authoring``.
+
+These attributes follow the form of attr objects specified in OEP-49 data
+pattern.
+
+The attributes for the events come from the CourseDetailView in the LMS, with some unused fields removed
+(see deprecation proposal at https://github.com/openedx/public-engineering/issues/160)
+"""
+from datetime import datetime
+from typing import BinaryIO, List
+
+import attr
+from opaque_keys.edx.keys import CourseKey, UsageKey
+from opaque_keys.edx.locator import (
+    LibraryCollectionLocator,
+    LibraryContainerLocator,
+    LibraryLocatorV2,
+    LibraryUsageLocatorV2,
+)
+
+
+@attr.s(frozen=True)
+class CourseData:
+    """
+    Data related to a course object.
+
+    Attributes:
+        course_key (CourseKey): identifier of the Course object.
+    """
+
+    course_key = attr.ib(type=CourseKey)
+
+
+@attr.s(frozen=True)
+class CourseScheduleData:
+    """
+    Data related to a course schedule.
+
+    Attributes:
+        start (datetime): course start date.
+        pacing (str): 'instructor' or 'self'.
+        end (datetime): course end date (optional).
+        enrollment_start (datetime): start of course enrollment (optional).
+        enrollment_end (datetime): end of course enrollment (optional).
+    """
+
+    start = attr.ib(type=datetime)
+    pacing = attr.ib(type=str)
+    end = attr.ib(type=datetime, default=None)
+    enrollment_start = attr.ib(type=datetime, default=None)
+    enrollment_end = attr.ib(type=datetime, default=None)
+
+
+@attr.s(frozen=True)
+class CourseCatalogData:
+    """
+    Data related to a course catalog entry.
+
+    Attributes:
+        course_key (CourseKey): identifier of the Course object.
+        name (str): course name.
+        schedule_data (CourseScheduleData): scheduling information for the course.
+        hidden (bool): whether the course is hidden from search (optional).
+        invitation_only (bool): whether the course requires an invitation to enroll.
+    """
+
+    # basic identifiers
+    course_key = attr.ib(type=CourseKey)
+    name = attr.ib(type=str)
+
+    # additional marketing information
+    schedule_data = attr.ib(type=CourseScheduleData)
+    hidden = attr.ib(type=bool, default=False)
+    invitation_only = attr.ib(type=bool, default=False)
+
+
+@attr.s(frozen=True)
+class XBlockData:
+    """
+    Data related to an XBlock object.
+
+    Attributes:
+        usage_key (UsageKey): identifier of the XBlock object.
+        block_type (str): type of block.
+        version (UsageKey): identifier of the XBlock object with branch and version data (optional). This
+           could be used to get the exact version of the XBlock object.
+    """
+
+    usage_key = attr.ib(type=UsageKey)
+    block_type = attr.ib(type=str)
+    version = attr.ib(type=UsageKey, default=None, kw_only=True)
+
+
+@attr.s(frozen=True)
+class DuplicatedXBlockData(XBlockData):
+    """
+    Data related to an XBlock object that has been duplicated.
+
+    This class extends XBlockData to include source_usage_key.
+
+    Attributes:
+        source_usage_key (UsageKey): identifier of the source XBlock object.
+    """
+
+    source_usage_key = attr.ib(type=UsageKey)
+
+
+@attr.s(frozen=True)
+class CertificateSignatoryData:
+    """
+    Data related to a certificate signatory. Subset of CertificateSignatory object from the LMS.
+
+    Attributes:
+        image (BinaryIO): certificate signature image. Take care that the image field is BinaryIO.
+        name (str): name of signatory.
+        organization (str): organization that signatory belongs to.
+        title (str): signatory title.
+    """
+
+    # Note: Please take care that the image field is BinaryIO, which means
+    # that a file can be passed as an array of bytes. Watch the size of this file.
+    # It can potentially be large, making it difficult to pass this data structure through the Event Bus
+    # (CloudEvent messages, which should be 64K or less) and store it on disk space.
+    # We suggest referring to MAX_ASSET_UPLOAD_FILE_SIZE_IN_MB, i.e. restriction in the Studio for such cases.
+    image = attr.ib(type=BinaryIO)
+    # end Note
+    name = attr.ib(type=str)
+    organization = attr.ib(type=str)
+    title = attr.ib(type=str)
+
+
+@attr.s(frozen=True)
+class CertificateConfigData:
+    """
+    Data related to a certificate configuration. Subset of CertificateConfig object from the LMS.
+
+    Attributes:
+        certificate_type (str): certificate type. Possible types are certificate relevant course modes:
+           - credit,
+           - verified,
+           - professional,
+           - no-id-professional,
+           - executive-education,
+           - paid-executive-education,
+           - paid-bootcamp,
+           - masters.
+        course_key (CourseKey): identifier of the Course object.
+        title (str): certificate title.
+        signatories (List[CertificateSignatoryData]): contains a collection of signatures
+           that belong to the certificate configuration.
+        is_active (bool): indicates whether the certifivate configuration is active.
+    """
+
+    certificate_type = attr.ib(type=str)
+    course_key = attr.ib(type=CourseKey)
+    title = attr.ib(type=str)
+    signatories = attr.ib(type=List[CertificateSignatoryData], factory=list)
+    is_active = attr.ib(type=bool, default=False)
+
+
+@attr.s(frozen=True)
+class ContentLibraryData:
+    """
+    Data related to a content library that has changed.
+
+    Attributes:
+        library_key (LibraryLocatorV2): a key that represents a v2 content library.
+        update_blocks (bool): DEPRECATED flag to indicate whether the content library blocks indexes should be updated.
+            Now we send individual events for each updated item instead.
+    """
+
+    library_key = attr.ib(type=LibraryLocatorV2)
+    update_blocks = attr.ib(type=bool, default=False)
+
+
+@attr.s(frozen=True)
+class LibraryBlockData:
+    """
+    Data related to a library block that has changed.
+
+    Attributes:
+        library_key (LibraryLocatorV2): a key that represents a v2 content library.
+        usage_key (LibraryUsageLocatorV2): a key that represents a XBlock in a Blockstore-based content library.
+    """
+
+    library_key = attr.ib(type=LibraryLocatorV2)
+    usage_key = attr.ib(type=LibraryUsageLocatorV2)
+
+
+@attr.s(frozen=True)
+class ContentObjectData:
+    """
+    Data related to a content object.
+
+    Attributes:
+        object_id (str): identifier of the Content object. This represents the id of the course or library block
+           as a string. For example:
+           >>> block-v1:SampleTaxonomyOrg2+STC1+2023_1+type@vertical+block@f8de78f0897049ce997777a3a31b6ea0
+    """
+
+    object_id = attr.ib(type=str)
+
+
+@attr.s(frozen=True)
+class ContentObjectChangedData(ContentObjectData):
+    """
+    Data related to a content object that has changed.
+
+    Attributes:
+        object_id (str): identifier of the Content object. This represents the id of the course or library block
+           as a string. For example:
+           >>> block-v1:SampleTaxonomyOrg2+STC1+2023_1+type@vertical+block@f8de78f0897049ce997777a3a31b6ea0
+        changes: list of changes made to this ContentObject, e.g. "tags", "collections". If list is empty,
+           assume everything has changed.
+    """
+
+    changes = attr.ib(type=List[str], factory=list)
+
+
+@attr.s(frozen=True)
+class LibraryCollectionData:
+    """
+    Data related to a library collection that has changed.
+
+    Attributes:
+        collection_key (LibraryCollectionLocator): identifies the collection within the library's learning package
+        background (bool): **DEPRECATED** field. Indicated the sender doesn't want to wait for handler to finish
+           execution. Now instead we recommend that simple handlers are synchronous and the _sender_ of the event should
+           send the event(s) from an async celery task if it is expected to result in a lot of handlers being called.
+    """
+
+    collection_key = attr.ib(type=LibraryCollectionLocator)
+    background = attr.ib(type=bool, default=False)
+
+
+@attr.s(frozen=True)
+class LibraryContainerData:
+    """
+    Data related to a library container that has changed.
+
+    Attributes:
+        container_key (LibraryContainerLocator): identifies the container (e.g.  unit, section)
+        background (bool): **DEPRECATED** field. Indicated the sender doesn't want to wait for handler to finish
+           execution. Now instead we recommend that simple handlers are synchronous and the _sender_ of the event should
+           send the event(s) from an async celery task if it is expected to result in a lot of handlers being called.
+    """
+
+    container_key = attr.ib(type=LibraryContainerLocator)
+    background = attr.ib(type=bool, default=False)