Merge pull request #397 from networktocode/release-v2.11.0

Release v2.11.0

Author: jvanderaa

.cookiecutter.json

@@ -0,0 +1,19 @@
+{
+    "cookiecutter": {
+        "codeowner_github_usernames": "@chadell @glennmatthews @pke11y @scetron @jvanderaa",
+        "full_name": "Network to Code, LLC",
+        "email": "info@networktocode.com",
+        "github_org": "networktocode",
+        "description": "Python library to parse circuit maintenances from network service providers.",
+        "project_name": "circuit-maintenance-parser",
+        "project_slug": "circuit-maintenance-parser",
+        "repo_url": "https://github.com/networktocode/circuit-maintenance-parser",
+        "base_url": "circuit-maintenance-parser",
+        "project_python_name": "circuit_maintenance_parser",
+        "project_python_base_version": "3.10",
+        "project_with_config_settings": "no",
+        "generate_docs": "yes",
+        "version": "2.10.0",
+        "original_publish_year": "2021"
+    }
+}

.github/workflows/ci.yml

@@ -95,7 +95,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     env:
       PYTHON_VER: "${{ matrix.python-version }}"
     steps:
@@ -131,7 +131,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: "ubuntu-24.04"
     env:
       PYTHON_VER: "${{ matrix.python-version }}"

circuit_maintenance_parser/parser.py

@@ -208,9 +208,9 @@ def parse_html(
     def clean_line(line):
         """Clean up of undesired characters from Html."""
         try:
-            return line.text.strip()
+            return line.text.strip().replace("\r\n", "\n").replace("\r", "\n")
         except AttributeError:
-            return line.strip()
+            return line.strip().replace("\r\n", "\n").replace("\r", "\n")
 
 
 class EmailDateParser(Parser):

circuit_maintenance_parser/parsers/google.py

@@ -4,7 +4,7 @@
 import re
 from datetime import datetime
 
-from circuit_maintenance_parser.parser import CircuitImpact, Html, Impact, Status
+from circuit_maintenance_parser.parser import CircuitImpact, EmailSubjectParser, Html, Impact, Status
 
 # pylint: disable=too-many-nested-blocks, too-many-branches
 
@@ -18,7 +18,7 @@ def parse_html(self, soup):
         """Execute parsing."""
         data = {}
         data["circuits"] = []
-        data["status"] = Status.CONFIRMED
+        end_time_explicit = False
 
         for span in soup.find_all("span"):
             if span.string is None:
@@ -29,6 +29,7 @@ def parse_html(self, soup):
             elif span.string.strip() == "End Time:":
                 dt_str = span.next_sibling.string.strip()
                 data["end"] = self.dt2ts(datetime.strptime(dt_str, "%Y-%m-%d %H:%M:%S %z UTC"))
+                end_time_explicit = True
             elif span.string.strip() == "Peer ASN:":
                 data["account"] = span.parent.next_sibling.string.strip()
             elif span.string.strip() == "Google Neighbor Address(es):":
@@ -37,9 +38,42 @@ def parse_html(self, soup):
                 cid = googleaddr + "-" + span.parent.next_sibling.string.strip()
                 data["circuits"].append(CircuitImpact(circuit_id=cid, impact=Impact.OUTAGE))
 
-        summary = list(soup.find("div").find("div").strings)[-1].strip()
-        match = re.search(r" - Reference (.*)$", summary)
-        data["summary"] = summary
-        data["maintenance_id"] = match[1]
+        # Google sometimes send notifications without End Time specified
+        if not end_time_explicit and data["start"]:
+            # Since start and end times cannot be equal, manufacturing end date by adding 1hr to start date
+            end_time_delta = 3600
+            data["end"] = data["start"] + end_time_delta
+
+        return [data]
+
+
+class SubjectParserGoogle1(EmailSubjectParser):
+    """Subject Parser for Google notifications."""
+
+    def parse_subject(self, subject):
+        """Parse the subject line."""
+        data = {}
+
+        # Example subject format - "[Scheduled] Google Planned Network Maintenance Notification - Reference PCR/123456"
+        # Group 1: Status (e.g., Scheduled, Completed, Canceled)
+        # Group 2: Maintenance ID (e.g., PCR/123456)
+        match = re.search(r"(\[\S+\]).*Reference\s+(\S+)", subject, re.IGNORECASE | re.DOTALL)
+        match_2 = re.search(r"\[\S+\]\s+(.*)", subject, re.IGNORECASE | re.DOTALL)
+
+        if match:
+            status_str = match.group(1).upper()
+            data["maintenance_id"] = match.group(2).strip()
+            if "COMPLETED" in status_str:
+                data["status"] = Status.COMPLETED
+            # To handle both Cancelled and Canceled spelling options just in case
+            elif "CANCEL" in status_str:
+                data["status"] = Status.CANCELLED
+            elif "SCHEDULED" in status_str:
+                data["status"] = Status.CONFIRMED
+            # If unable to match, we fallback to default confirmed
+            else:
+                data["status"] = Status.CONFIRMED
+        if match_2:
+            data["summary"] = match_2.group(1)
 
         return [data]

circuit_maintenance_parser/parsers/lumen.py

@@ -60,11 +60,10 @@ def parse_spans(self, spans: ResultSet, data: Dict):
                     for sibling in line.next_siblings:
                         text_sibling = sibling.text.strip() if isinstance(sibling, bs4.element.Tag) else sibling.strip()
                         if text_sibling != "":
-                            if (
-                                "This maintenance is scheduled" in text_sibling
-                                or "The scheduled maintenance work has begun" in text_sibling
-                            ):
+                            if "The scheduled maintenance work has begun" in text_sibling:
                                 data["status"] = Status("IN-PROCESS")
+                            elif "This maintenance is scheduled" in text_sibling:
+                                data["status"] = Status("CONFIRMED")
                             if "GMT" in text_sibling:
                                 stamp = parser.parse(text_sibling.split(" GMT")[0])
                                 data["stamp"] = self.dt2ts(stamp)

circuit_maintenance_parser/provider.py

@@ -24,7 +24,7 @@
 from circuit_maintenance_parser.parsers.crowncastle import HtmlParserCrownCastle1
 from circuit_maintenance_parser.parsers.equinix import HtmlParserEquinix, SubjectParserEquinix
 from circuit_maintenance_parser.parsers.globalcloudxchange import HtmlParserGcx1, SubjectParserGcx1
-from circuit_maintenance_parser.parsers.google import HtmlParserGoogle1
+from circuit_maintenance_parser.parsers.google import HtmlParserGoogle1, SubjectParserGoogle1
 from circuit_maintenance_parser.parsers.gtt import HtmlParserGTT1
 from circuit_maintenance_parser.parsers.hgc import HtmlParserHGC1, HtmlParserHGC2, SubjectParserHGC1
 from circuit_maintenance_parser.parsers.lumen import HtmlParserLumen1
@@ -130,12 +130,6 @@ def get_maintenances(self, data: NotificationData) -> Iterable[Maintenance]:
             logger.debug("Skipping notification %s due filtering policy for %s.", data, self.__class__.__name__)
             return []
 
-        if os.getenv("PARSER_OPENAI_API_KEY"):
-            self._processors.append(CombinedProcessor(data_parsers=[EmailDateParser, OpenAIParser]))
-
-            # Add subject to all html or text/* data_parts if not already present.
-            self.add_subject_to_text(data)
-
         for processor in self._processors:
             try:
                 return processor.process(data, self.get_extended_data())
@@ -150,6 +144,22 @@ def get_maintenances(self, data: NotificationData) -> Iterable[Maintenance]:
                 related_exceptions.append(exc)
                 continue
 
+        # Use OpenAI parser as a last resort if all other processors failed.
+        if os.getenv("PARSER_OPENAI_API_KEY"):
+            self.add_subject_to_text(data)
+            openai_processor = CombinedProcessor(data_parsers=[EmailDateParser, OpenAIParser])
+            try:
+                return openai_processor.process(data, self.get_extended_data())
+            except ProcessorError as exc:
+                process_error_message = (
+                    f"- Processor {openai_processor.__class__.__name__} from {provider_name} failed due to: %s\n"
+                )
+                logger.debug(process_error_message, traceback.format_exc())
+
+                related_exc = rgetattr(exc, "__cause__")
+                error_message += process_error_message % related_exc
+                related_exceptions.append(exc)
+
         raise ProviderError(
             (f"Failed creating Maintenance notification for {provider_name}.\nDetails:\n{error_message}"),
             related_exceptions=related_exceptions,
@@ -165,7 +175,7 @@ def add_subject_to_text(self, data: NotificationData):
         if subject:
             new_data_parts = []
             for part in data.data_parts:
-                if part.type.startswith("text/") or part.type.startswith("html"):
+                if (part.type.startswith("text/") or part.type.startswith("html")) and part.type != "text/calendar":
                     content_str = part.content.decode(errors="ignore")
                     if subject not in content_str:
                         # Append subject and update content
@@ -364,7 +374,7 @@ class Google(GenericProvider):
 
     _processors: List[GenericProcessor] = PrivateAttr(
         [
-            CombinedProcessor(data_parsers=[EmailDateParser, HtmlParserGoogle1]),
+            CombinedProcessor(data_parsers=[EmailDateParser, HtmlParserGoogle1, SubjectParserGoogle1]),
         ]
     )
     _default_organizer = PrivateAttr("noc-noreply@google.com")

docs/release_notes.md

@@ -4,6 +4,37 @@ This document describes all new features and changes in the release. The format
 
 <!-- towncrier release notes start -->
 
+# v2.11 Release Notes
+
+This document describes all new features and changes in the release. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Release Overview
+
+- Major features or milestones
+- Changes to compatibility with Nautobot and/or other apps, libraries etc.
+
+## [v2.11.0 (2026-04-15)](https://github.com/networktocode/circuit-maintenance-parser/releases/tag/v2.11.0)
+
+### Added
+
+- [#375](https://github.com/networktocode/circuit-maintenance-parser/issues/375) - Added Google subject parser with support for multiple status types and notifications without end times.
+
+### Fixed
+
+- [#372](https://github.com/networktocode/circuit-maintenance-parser/issues/372) - Refactored OpenAI parser to be used as a fallback and fixed subject injection to skip text/calendar parts.
+- [#377](https://github.com/networktocode/circuit-maintenance-parser/issues/377) - Fixed Lumen parser incorrectly marking scheduled future maintenance events as IN-PROCESS instead of CONFIRMED. Bug introduced in commit 737aa4e9 (Aug 2021).
+
+### Dependencies
+
+- [#391](https://github.com/networktocode/circuit-maintenance-parser/issues/391) - Upgraded lxml to version 6.0.2 and normalized CRLF line endings in HTML parser output.
+- [#393](https://github.com/networktocode/circuit-maintenance-parser/issues/393) - Pinned lxml version to support >=4.6.2,<7.
+
+### Housekeeping
+
+- [#384](https://github.com/networktocode/circuit-maintenance-parser/issues/384) - Added Python 3.13 to supported versions and CI matrix.
+- Added required cookiecutter json file for drift management setup.
+- Fixed incorrectly set cookiecutter project_slug.
+
 ## [v2.10.0 (2026-01-27)](https://github.com/networktocode/circuit-maintenance-parser/releases/tag/v2.10.0)
 
 ### Added
@@ -14,7 +45,7 @@ This document describes all new features and changes in the release. The format
 
 - [#360](https://github.com/networktocode/circuit-maintenance-parser/issues/360) - Updated lxml to include version 6
 - [#361](https://github.com/networktocode/circuit-maintenance-parser/issues/361) - Updated timezonefinder to v8.2.0
-- [#345](https://github.com/networktocode/circuit_maintenance_parser/issues/345) - Updated minimum Python version to 3.10 and upgraded dependencies including pytest (9.0), pylint (4.0), towncrier (25.8), backoff (2.2), and type stubs
+- [#345](https://github.com/networktocode/circuit-maintenance-parser/issues/345) - Updated minimum Python version to 3.10 and upgraded dependencies including pytest (9.0), pylint (4.0), towncrier (25.8), backoff (2.2), and type stubs
 
 ### Housekeeping