aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/mentions.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-12 19:57:08 +0100
committerDennis Fink2026-11-12 19:57:08 +0100
commit4bd1d9e348918b2e55db47a1ac3489d035cf55e2 (patch)
treef7ed41a374a8a4136792039a262dc62aa8cf8c59 /webmentions_ssg/tasks/mentions.py
parent7035e9f9467684cccae2b7ff3faaa62e6a9f91aa (diff)
downloadwebmentions-ssg-4bd1d9e348918b2e55db47a1ac3489d035cf55e2.tar.gz
webmentions-ssg-4bd1d9e348918b2e55db47a1ac3489d035cf55e2.zip
refactor(core): split modules by responsibility
Break up monolithic views, task helpers, networking, CLI, and application extension setup so each module owns a focused concern. Reorganize the test suite around the new boundaries while preserving existing Webmention behavior and coverage.
Diffstat (limited to 'webmentions_ssg/tasks/mentions.py')
-rw-r--r--webmentions_ssg/tasks/mentions.py99
1 files changed, 99 insertions, 0 deletions
diff --git a/webmentions_ssg/tasks/mentions.py b/webmentions_ssg/tasks/mentions.py
new file mode 100644
index 0000000..4e5a5ca
--- /dev/null
+++ b/webmentions_ssg/tasks/mentions.py
@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Pure HTML and text matching for received Webmention targets."""
+
+from urllib.parse import urljoin
+
+import rfc3987
+from bs4 import BeautifulSoup
+
+IRI_PATTERN = rfc3987.get_compiled_pattern("IRI")
+TRAILING_IRI_PUNCTUATION = ".,;:!?"
+
+HTML_URL_ATTRIBUTES = {
+ "href": {"a", "area", "link"},
+ "src": {
+ "audio",
+ "embed",
+ "iframe",
+ "img",
+ 'input[type="image" i]',
+ "script",
+ "audio source",
+ "video source",
+ "track",
+ "video",
+ },
+ "cite": {"blockquote", "del", "ins", "q"},
+}
+
+
+def html_mentions_target(body: bytes, source_url: str, target_url: str) -> bool:
+ """
+ Check whether an HTML document mentions the target URL.
+
+ URL references are resolved against the document's ``base`` element when
+ present, or against the source URL otherwise.
+
+ :param body: HTML document body.
+ :param source_url: URL from which the document was retrieved.
+ :param target_url: Exact URL to look for.
+ :return: Whether a supported HTML URL attribute references the target URL.
+ """
+
+ document = BeautifulSoup(body, "html.parser")
+ base_url = source_url
+
+ if (base_element := document.select_one("base[href]")) is not None and isinstance(
+ base_href := base_element.get("href"), str
+ ):
+ base_url = urljoin(source_url, base_href.strip())
+
+ for attribute, selectors in HTML_URL_ATTRIBUTES.items():
+ selector = ", ".join(
+ [f"{selector_string}[{attribute}]" for selector_string in selectors]
+ )
+
+ for element in document.select(selector):
+ if not isinstance(reference := element.get(attribute), str):
+ continue
+
+ if urljoin(base_url, reference.strip()) == target_url:
+ return True
+
+ return False
+
+
+def text_mentions_target(body: str, target_url: str) -> bool:
+ """
+ Check whether plain text contains the target IRI, ignoring trailing prose
+ punctuation but not extra URL path or query characters.
+
+ :param body: Plain-text document body.
+ :param target_url: Exact IRI to look for.
+ :return: Whether the target IRI occurs in the document.
+ """
+ for match in IRI_PATTERN.finditer(body):
+ candidate = match.group()
+
+ # A URL in prose can be followed by punctuation that the IRI pattern
+ # consumes as part of its match. Only remove trailing punctuation,
+ # leaving longer URLs (e.g. ``target/more``) unmatched.
+ if not candidate.startswith(target_url):
+ continue
+
+ while candidate != target_url:
+ if candidate[-1] in TRAILING_IRI_PUNCTUATION:
+ candidate = candidate[:-1]
+ elif candidate[-1] == ")" and candidate.count(")") > candidate.count("("):
+ # Keep balanced parentheses that belong to the URL itself.
+ candidate = candidate[:-1]
+ else:
+ break
+
+ if candidate == target_url:
+ return True
+
+ return False