diff options
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/tasks/source_parser.py | 40 |
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 |
