Merge pull request #216 from canonical/discourse-community-portal-improvements

Feature branch - Discourse community portal improvements

Author: petesfrench

CHANGELOG.md

@@ -1,24 +1,47 @@
+### 7.0.0 [01-07-2025]
+**Added** Events class
+- Created a new class to handle events from 'Discourse Calender (and events)' API
+**Added** EventsParser class
+- Created a new parser to process the events retrieve by the Events class
+**Updated** check_for_category_updates & check_for_topic_updates
+- Moved from Category into DiscourseAPI 
+**Updated** Category class
+- The function `get_topics_in_category` now returns an array of objects
+
+### 6.5.0 [12-06-2025]
+**Updated** Discourse API
+- Created a new API to query upcoming events in a category
+**Updated** Category class
+- Exposes the events API on the Category class
+
+### 6.4.0 [10-06-2025]
+**Updated** CategoryParser
+- Will split a link found in metadata tables into its href ('url') and text content ('text'), as properties on the table row item.
+- Handles tables positioned below the string [details=NAME] and nested in a `<details>` element.
+**Updated** test_parser.py
+- Added tests for the Category parser
+
 ### 6.3.0 [02-07-2025]
 **Updated** EngagePages class
-Remove duplicated tags from the list of tags returned from `get_engage_pages_tags`
+- Remove duplicated tags from the list of tags returned from `get_engage_pages_tags`
 
 ### 6.2.0 [28-04-2025]
 **Added** _inject_custom_css def
-A function that finds css directives (`[style=CLASSNAME]`) in the soup and applies to them to the next found element.
+- A function that finds css directives (`[style=CLASSNAME]`) in the soup and applies to them to the next found element.
 
 ### 6.1.1 [12-03-2025]
 **Updated** EngagePages class
-Pass values for the provided keys, even if the values are empty or null, as they can be a filter themselves.
+- Pass values for the provided keys, even if the values are empty or null, as they can be a filter themselves.
 
 ### 6.1.0 [25-01-2025]
 **Updated** Category class
-Check for additions or deletions of topics within a category and update cached data if needed
+- Check for additions or deletions of topics within a category and update cached data if needed
 
 ### 6.0.0 [28-01-2025]
 **Updated** Category class 
-Removed to template handling from within the Category class.
-Bump to 6.0.0, as the previous update was a major
+- Removed to template handling from within the Category class.
+- Bump to 6.0.0, as the previous update was a major
 
 ### 5.8.0 [28-01-2025]
 **Added** Category class 
-A generic class for processing discourse categories and the topics they contain
+- A generic class for processing discourse categories and the topics they contain

README.md

@@ -98,3 +98,54 @@ Similarly for takeovers, you just need to pass `page_type="takeovers"`.
 - `get_index` provides two additional arguments `limit` and `offset`, to provide pagination functionality. They default to 50 and 0 respectively.
 - If you want to get all engage pages, which in the case of some sites like jp.ubuntu.com there are not that many, you can pass `limit=-1`
 - Use `MaxLimitError` in the `exceptions.py` to handle excessive limit. By default, it will raise an error when it surpasses 500
+
+
+## Instructions for Category class usage
+
+This works similar to the other class but exposes some specific functions that can be run on the index topic and the category as a whole.
+
+It exposes a some APIs that can then be called from within a view func for processing.
+
+Here is an example of the implementation:
+
+```
+security_vulnerabilities = Category(
+    parser=CategoryParser(
+        api=discourse_api,
+        index_topic_id=53193,
+        url_prefix="/security/vulnerabilities",
+    ),
+    category_id=308,
+)
+```
+
+The `security_vulnerabilities` object exposes the following APIs:
+
+- get_topic(path): Fetches a single topic using its URL (path).
+- get_category_index_metadata(data_name): Retrieves metadata for the category index. You can optionally specify a data_name to get data for just one table.
+- get_topics_in_category(): Retrieves all topics within the currently active category.
+- get_category_events(limit=100, offset=0): Retrieves all future events in a category. Requires the Discourse Events plugin to be installed on the instance.
+
+## Instructions for Events class usage
+
+This class provides functionality for managing and parsing events from Discourse topics, particularly useful for event-driven websites that need to display upcoming events, featured events, and event categories. It relies on the plugin, [Discourse Calendar](https://meta.discourse.org/t/discourse-calendar-and-event/97376).
+
+It exposes APIs that can be called from within a view function for processing event data.
+
+Here is an example of the implementation:
+
+```python
+events = Events(
+    parser=EventsParser(
+        api=discourse_api,
+        index_topic_id=12345,
+        url_prefix="/events",
+    ),
+    category_id=25,
+)
+```
+
+The `events` object exposes the following APIs:
+
+- get_events(): Fetches all future events from the target Discourse instance.
+- get_featured_events(target_tag="featured-event"): Retrieves all events with a given tagrte tag, defaults to "featured-event"

canonicalwebteam/discourse/__init__.py

@@ -3,10 +3,12 @@
     EngagePages,  # noqa
     Tutorials,  # noqa
     Category,  # noqa
+    Events,  # noqa
 )
 from canonicalwebteam.discourse.models import DiscourseAPI  # noqa
 from canonicalwebteam.discourse.parsers import (  # noqa
     DocParser,  # noqa
     TutorialParser,  # noqa
     CategoryParser,  # noqa
+    EventsParser,  # noqa
 )

canonicalwebteam/discourse/app.py

@@ -306,7 +306,6 @@ def __init__(
         self.page_type = page_type
         self.exclude_topics = exclude_topics
         self.additional_metadata_validation = additional_metadata_validation
-        pass
 
     def get_index(
         self,
@@ -729,15 +728,18 @@ def __init__(
         self.index_last_updated = None
         self.category_last_updated = None
         self.category_index_metadata = None
+        self.events = None
         pass
 
-    def get_topic(self, path=""):
+    def get_topic(self, path="/"):
         """
         A Flask view function to serve topics from a Discourse category
         """
-        path = "/" + path
+        if path != "/" and not path.startswith("/"):
+            path = "/" + path
+
         if path == "/":
-            document = self.parser.parse_topic(self.parser.index_topic)
+            topic = self.parser.api.get_topic(self.parser.index_topic_id)
         else:
             try:
                 topic_id = self._get_topic_id_from_path(path)
@@ -749,15 +751,28 @@ def get_topic(self, path=""):
             except HTTPError as http_error:
                 return flask.abort(http_error.response.status_code)
 
-            document = self.parser.parse_topic(topic)
+        document = self.parser.parse_topic(topic)
+
+        return document
+
+    def get_topic_by_id(self, topic_id):
+        """
+        A Flask view function to serve a topic by its ID
+        """
+        try:
+            topic = self.parser.api.get_topic(topic_id)
+        except HTTPError as http_error:
+            return flask.abort(http_error.response.status_code)
+
+        document = self.parser.parse_topic(topic)
 
         return document
 
     def _get_topic_id_from_path(self, path):
         path = path.lstrip("/")
-        for topic in self.get_topics_in_category().items():
-            if topic[1] == path:
-                return topic[0]
+        for topic in self.get_topics_in_category():
+            if topic["slug"] == path:
+                return topic["id"]
         return None
 
     def get_category_index_metadata(self, data_name=""):
@@ -769,8 +784,8 @@ def get_category_index_metadata(self, data_name=""):
         :param data_name: Name of the data table
         """
         try:
-            updated, updated_at = self._check_for_topic_updates(
-                self.parser.index_topic_id
+            updated, updated_at = self.parser.api.check_for_topic_updates(
+                self.parser.index_topic_id, self.index_last_updated
             )
 
             if self.category_index_metadata is None or updated:
@@ -791,50 +806,73 @@ def get_topics_in_category(self):
         Exposes an API to query all topics in a category
         """
         try:
-            updated, updated_at = self._check_for_category_updates(
-                self.category_id
+            updated, updated_at = self.parser.api.check_for_category_updates(
+                self.category_id, self.category_last_updated
             )
 
             if self.category_topics is None or updated:
-                self.category_topics = (
-                    self.parser.api.get_topic_list_by_category(
-                        self.category_id
-                    )
+                all_topics = self.parser.api.get_topic_list_by_category(
+                    self.category_id
                 )
+                # Filter out excluded topics
+                self.category_topics = [
+                    topic
+                    for topic in all_topics
+                    if topic.get("id") not in self.exclude_topics
+                ]
                 self.category_last_updated = updated_at
 
         except Exception:
             if self.category_topics is None:
                 return {}
 
-        return {str(topic[0]): topic[2] for topic in self.category_topics}
+        return self.category_topics
+
+
+class Events:
+    """
+    A class to handle events in a Discourse category.
+    It intergrates with the Discourse Events plugin.
+
+    :param parser: A data parser class
+    :param category_id: ID of a Discourse category
+    """
+
+    def __init__(self, parser, category_id):
+        self.parser = parser
+        self.category_id = category_id
+        self.all_events = None
+        self.events_last_updated = None
+        self.featured_events = None
+        pass
 
-    def _check_for_topic_updates(self, topic_id):
+    def get_events(self) -> list:
         """
-        Check if the index topic has been updated
+        Fetches all future events from the target Discourse instance.
         """
-        most_recent_update = self.parser.api.get_topics_last_activity_time(
-            topic_id
-        )[0][1]
-        if (
-            self.index_last_updated
-            and most_recent_update > self.index_last_updated
-        ):
-            return True, most_recent_update
-        else:
-            return False, most_recent_update
+        updated, updated_at = self.parser.api.check_for_category_updates(
+            self.category_id, self.events_last_updated
+        )
 
-    def _check_for_category_updates(self, category_id):
+        if self.all_events is None or updated:
+            self.all_events = self.parser.api.get_events()["events"]
+            self.events_last_updated = updated_at
+
+        return self.all_events
+
+    def get_featured_events(self, target_tag="featured-event") -> list:
         """
-        Check if the category has had topics added or removed
+        Fetches events that are marked with a specific tag.
+
+        :param target_tag: Tag to filter featured events by.
         """
-        most_recent_update = self.parser.api.get_categories_last_activity_time(
-            category_id
-        )[0][1]
-        if (
-            self.category_last_updated
-            and most_recent_update > self.category_last_updated
-        ):
-            return True, most_recent_update
-        else:
-            return False, most_recent_update
+        featured_events_ids = self.parser.api.get_topics_by_tag(target_tag)[
+            "grouped_search_result"
+        ]["post_ids"]
+        all_events = self.get_events()
+
+        self.featured_events = self.parser.parse_featured_events(
+            all_events, featured_events_ids
+        )
+
+        return self.featured_events

canonicalwebteam/discourse/exceptions.py

@@ -77,6 +77,21 @@ def __init__(self, *args: object) -> None:
         pass
 
 
+class DiscourseEventsError(Exception):
+    """
+    Error for the Discourse Events plugin.
+
+    Will be sent to Sentry
+    """
+
+    def __init__(self, *args: object) -> None:
+        error_message = args[0]
+        flask.current_app.extensions["sentry"].captureMessage(
+            f"Discourse event plugin error {error_message}"
+        )
+        pass
+
+
 class MaxLimitError(Exception):
     """
     Error raised when limit/offset is too high