aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/source_parser.py
diff options
context:
space:
mode:
Diffstat (limited to 'webmentions_ssg/tasks/source_parser.py')
-rw-r--r--webmentions_ssg/tasks/source_parser.py40
1 files changed, 22 insertions, 18 deletions
diff --git a/webmentions_ssg/tasks/source_parser.py b/webmentions_ssg/tasks/source_parser.py
index 294402c..31d0c98 100644
--- a/webmentions_ssg/tasks/source_parser.py
+++ b/webmentions_ssg/tasks/source_parser.py
@@ -76,7 +76,7 @@ def source_url_for_path(relative_path: Path, base_url: str) -> str:
:param relative_path: Path of the source document relative to the source root.
:param base_url: Base URL under which source documents are published.
- :return: Public URL corresponding to the source document.
+ :returns: Public URL corresponding to the source document.
"""
directory = relative_path.parent.as_posix()
@@ -93,9 +93,9 @@ def canonical_url(
:param document: Parsed HTML source document.
:param relative_path: Path of the source document relative to the source root.
:param base_url: Configured source base URL, if available.
- :return: Canonical URL, or ``None`` if none is declared.
- :raises SourceScanError: If the canonical URL is empty, cannot be resolved,
- or does not resolve to an HTTP or HTTPS URL.
+ :returns: Canonical URL, or ``None`` if none is declared.
+ :raises SourceScanError: If the canonical URL is empty, cannot be resolved, or does
+ not resolve to an HTTP or HTTPS URL.
"""
if (link := document.select_one('link[rel~="canonical"][href]')) is None:
return None
@@ -129,7 +129,7 @@ def property_urls(entry: dict[str, Any], property_name: str) -> Iterator[str]:
:param entry: Parsed microformats entry.
:param property_name: Name of the property to inspect.
- :return: Iterator over string values of the property.
+ :returns: Iterator over string values of the property.
"""
properties = entry.get("properties")
@@ -149,7 +149,7 @@ def parse_entry(element: Tag, base_url: str) -> dict[str, Any]:
:param element: HTML element containing the h-entry.
:param base_url: Base URL used when parsing the microformats data.
- :return: Parsed h-entry.
+ :returns: Parsed h-entry.
:raises SourceScanError: If parsing does not produce exactly one valid h-entry.
"""
parsed = mf2py.parse(doc=str(element), url=base_url)
@@ -185,9 +185,9 @@ def primary_entry(
:param document: Parsed HTML source document.
:param source_url: Public URL of the source document.
- :return: h-entry element and its parsed microformats representation.
- :raises SourceScanError: If the document does not contain exactly one h-entry
- or its ``u-url`` does not match the source URL.
+ :returns: h-entry element and its parsed microformats representation.
+ :raises SourceScanError: If the document does not contain exactly one h-entry or its
+ ``u-url`` does not match the source URL.
"""
entries = document.find_all(class_="h-entry")
@@ -211,9 +211,9 @@ def content_element(entry: Tag) -> Tag:
"""Return the e-content element of an h-entry.
:param entry: HTML element containing the h-entry.
- :return: The h-entry's e-content element.
- :raises SourceScanError: If the h-entry does not contain exactly one
- e-content element.
+ :returns: The h-entry's e-content element.
+ :raises SourceScanError: If the h-entry does not contain exactly one e-content
+ element.
"""
contents = entry.find_all(class_="e-content")
@@ -232,8 +232,8 @@ def normalize_target(value: str, *, base_url: str, source_url: str) -> str | Non
:param value: URL reference to normalize.
:param base_url: Base URL against which relative references are resolved.
:param source_url: URL of the source document.
- :return: Normalized target URL, or ``None`` if the value is not a valid
- Webmention target.
+ :returns: Normalized target URL, or ``None`` if the value is not a valid Webmention
+ target.
"""
if not (value := value.strip()):
return None
@@ -268,7 +268,7 @@ def iter_targets(
:param base_url: Base URL against which relative targets are resolved.
:param source_url: URL of the source document.
:param ignored_hostnames: Hostname patterns whose targets should be ignored.
- :return: Iterator over outgoing Webmention target URLs.
+ :returns: Iterator over outgoing Webmention target URLs.
"""
hrefs = (
href
@@ -289,7 +289,11 @@ def iter_targets(
def normalized_content(content: Tag) -> str:
- """Extract stable reader-facing content without generated HTML attributes."""
+ """Extract stable reader-facing content without generated HTML attributes.
+
+ :param content: Parsed e-content element to normalize.
+ :returns: Normalized text used to fingerprint reader-facing content.
+ """
def extract(node: PageElement) -> str:
if isinstance(node, NavigableString):
@@ -326,9 +330,9 @@ def scan_source_file(
:param root: Root directory containing generated source documents.
:param base_url: Configured source base URL, if available.
:param ignored_hostnames: Hostname patterns whose targets should be ignored.
- :return: Scanned source metadata and discovered targets.
+ :returns: Scanned source metadata and discovered targets.
:raises SourceScanError: If the document cannot be safely interpreted as a
- Webmention source.
+ Webmention source.
:raises OSError: If the source document cannot be read.
"""
# Use the path as published for its URL, but read only files whose