Isoler le contenu principal d’une page web

"""
Garder l'article et jeter tout ce qui l'entoure.

Niveau N0. Séparer le corps d'une page de ses menus, de son pied, de son
bandeau de cookies et de son « vous aimerez aussi » est un problème résolu
qui porte un nom — le retrait du texte de remplissage — et qui a deux mises
en œuvre mûres : `trafilatura` ici, le `Readability` de Mozilla en JavaScript. Les deux travaillent sur
l'arbre des balises, en pesant la densité de texte contre la densité de
liens, et les deux tournent hors ligne en quelques millisecondes.

Ce ne sont pas le même algorithme et ils ne rendent pas les mêmes caractères.
Les titres diffèrent, les retours à la ligne diffèrent, et l'un garde le
titre dans le corps quand l'autre le met à part. Ce sur quoi ils s'accordent
est la part qui compte, et le test de cette fiche le dit ainsi : les phrases
de l'article sont dedans, la navigation et le pied de page sont dehors.

Deux choses que ce fichier ajoute. La première est le refus de rendre une
chaîne vide comme si c'était une réponse, et de confondre deux situations en
le faisant. Une page dont le corps est construit par son propre JavaScript
arrive ici en coquille vide, et ce n'est pas la même chose qu'une brève de
presse de cent vingt-cinq caractères sortie entière. Les deux ont deux
raisons : l'une dit que rien n'est sorti, l'autre dit combien ce qui est
sorti est court, et ne dit rien de pourquoi.

La seconde tranche un désaccord entre les deux bibliothèques. Sur une page de
catégorie — quarante liens et rien d'autre —, `trafilatura` ne rend rien et
`Readability` rend le texte des liens comme si c'était un article. La part du
texte de la page qui se trouve à l'intérieur de liens est donc mesurée ici,
dans les deux langages, et au-delà de la moitié la page n'est pas un article,
quoi qu'en ait dit l'extracteur.
"""

from __future__ import annotations

import trafilatura

# The length under which the report says so, in characters. It is a line of
# information handed to the caller, not a verdict: a press brief and the
# documentation of one function are both genuinely below it, and both come
# back whole, with their text and their title. Nothing is dropped and nothing
# is diagnosed because of it.
MIN_CHARACTERS = 200

# Above this share of the page's text inside links, the page is a list of
# links — a category, an index, a tag page — and not an article. Measured
# rather than guessed, because the two extractors do not agree on their own.
MAX_LINK_SHARE = 0.5


def read_article(html, *, min_characters: int = MIN_CHARACTERS) -> dict:
    """
    The body of the page, its title, and whether it is worth reading.

    `reason` tells a caller that came back empty-handed which of the two
    happened. Nothing at all came out — the page is a shell, and that calls
    for another tool, not for a better extractor. Or something came out and it
    is short, in which case the reason says how short, and nothing else: a
    short page is a short page, not a broken one.
    """
    if not isinstance(html, str):
        return _report(None, "", f"expected HTML, not {type(html).__name__}")
    try:
        text = trafilatura.extract(html, output_format="txt", include_comments=False,
                                   include_tables=False, favor_precision=True) or ""
        metadata = trafilatura.extract_metadata(html)
        share = _link_share(html)
    except Exception:  # noqa: BLE001 - a page that cannot be parsed is an answer too
        return _report(None, "", "this page could not be parsed")

    title = getattr(metadata, "title", None) if metadata else None
    if share > MAX_LINK_SHARE:
        return _report(title, "", "this page is a list of links, not an article")
    text = text.strip()
    if not text:
        return _report(title, "", "nothing was extracted: this page may be built by its own JavaScript")
    if len(text) < min_characters:
        return _report(title, text, f"this page is short: {len(text)} characters")
    return _report(title, text, None)


def _link_share(html: str) -> float:
    """
    What share of the page's text sits inside a link.

    Both sides are stripped, and the result is capped at one: a link nested
    inside another — which a permissive parser produces on malformed markup —
    is counted twice, and a share above one is not a share.
    """
    from lxml import html as lxml_html

    tree = lxml_html.fromstring(html)
    for element in tree.iter("script", "style"):
        element.text = None
    total = len("".join(tree.itertext()).strip())
    inside = sum(len("".join(link.itertext()).strip()) for link in tree.iter("a"))
    return min(inside / total, 1.0) if total else 0.0


def _report(title, text: str, reason: str | None) -> dict:
    return {"title": title, "text": text, "characters": len(text), "reason": reason}

/**
 * Garder l'article et jeter tout ce qui l'entoure.
 *
 * Niveau N0. Séparer le corps d'une page de ses menus, de son pied, de son
 * bandeau de cookies et de son « vous aimerez aussi » est un problème résolu
 * qui porte un nom — le retrait du texte de remplissage — et qui a deux mises
 * en œuvre mûres : le `Readability` de Mozilla ici, `trafilatura` en Python. Les deux travaillent sur
 * l'arbre des balises, en pesant la densité de texte contre la densité de
 * liens, et les deux tournent hors ligne en quelques millisecondes.
 *
 * Ce ne sont pas le même algorithme et ils ne rendent pas les mêmes caractères.
 * Les titres diffèrent, les retours à la ligne diffèrent, et l'un garde le
 * titre dans le corps quand l'autre le met à part. Ce sur quoi ils s'accordent
 * est la part qui compte, et le test de cette fiche le dit ainsi : les phrases
 * de l'article sont dedans, la navigation et le pied de page sont dehors.
 *
 * Deux choses que ce fichier ajoute. La première est le refus de rendre une
 * chaîne vide comme si c'était une réponse, et de confondre deux situations en
 * le faisant. Une page dont le corps est construit par son propre JavaScript
 * arrive ici en coquille vide, et ce n'est pas la même chose qu'une brève de
 * presse de cent vingt-cinq caractères sortie entière. Les deux ont deux
 * raisons : l'une dit que rien n'est sorti, l'autre dit combien ce qui est
 * sorti est court, et ne dit rien de pourquoi.
 *
 * La seconde tranche un désaccord entre les deux bibliothèques. Sur une page de
 * catégorie — quarante liens et rien d'autre —, `trafilatura` ne rend rien et
 * `Readability` rend le texte des liens comme si c'était un article. La part du
 * texte de la page qui se trouve à l'intérieur de liens est donc mesurée ici,
 * dans les deux langages, et au-delà de la moitié la page n'est pas un article,
 * quoi qu'en ait dit l'extracteur.
 */

import { Readability } from '@mozilla/readability';
// `Readability` needs a document, and Node has none. `linkedom` builds one
// without a browser engine; `jsdom` would do as well and costs more to start.
import { parseHTML } from 'linkedom';

// The length under which the report says so, in characters. It is a line of
// information handed to the caller, not a verdict: a press brief and the
// documentation of one function are both genuinely below it, and both come
// back whole, with their text and their title. Nothing is dropped and nothing
// is diagnosed because of it.
export const MIN_CHARACTERS = 200;

// Above this share of the page's text inside links, the page is a list of
// links — a category, an index, a tag page — and not an article. Measured
// rather than guessed, because the two extractors do not agree on their own.
export const MAX_LINK_SHARE = 0.5;

/**
 * The body of the page, its title, and whether it is worth reading.
 *
 * `reason` tells a caller that came back empty-handed which of the two
 * happened. Nothing at all came out — the page is a shell, and that calls for
 * another tool, not for a better extractor. Or something came out and it is
 * short, in which case the reason says how short, and nothing else: a short
 * page is a short page, not a broken one.
 *
 * @param {string} html
 * @param {{minCharacters?: number}} [options]
 */
export function readArticle(html, { minCharacters = MIN_CHARACTERS } = {}) {
  if (typeof html !== 'string') {
    return report(null, '', `expected HTML, not ${kindOf(html)}`);
  }
  let article;
  let fallbackTitle = null;
  let share = 0;
  try {
    const { document } = parseHTML(html);
    // Both kept before parsing: `Readability` empties the document as it works.
    fallbackTitle = document.title || null;
    share = linkShare(document);
    article = new Readability(document).parse();
  } catch {
    return report(null, '', 'this page could not be parsed');
  }

  const title = article?.title || fallbackTitle;
  if (share > MAX_LINK_SHARE) {
    return report(title, '', 'this page is a list of links, not an article');
  }
  const text = (article?.textContent ?? '').trim();
  if (text.length === 0) {
    return report(title, '', 'nothing was extracted: this page may be built by its own JavaScript');
  }
  if (text.length < minCharacters) {
    return report(title, text, `this page is short: ${text.length} characters`);
  }
  return report(title, text, null);
}

/**
 * What share of the page's text sits inside a link.
 *
 * Both sides are stripped, and the result is capped at one: a link nested
 * inside another — which a permissive parser produces on malformed markup —
 * is counted twice, and a share above one is not a share.
 */
function linkShare(document) {
  for (const element of document.querySelectorAll('script, style')) element.textContent = '';
  const total = (document.documentElement?.textContent ?? '').trim().length;
  const inside = [...document.querySelectorAll('a')]
    .reduce((n, link) => n + (link.textContent ?? '').trim().length, 0);
  return total ? Math.min(inside / total, 1) : 0;
}

const kindOf = (value) => (value === null ? 'null' : typeof value);

const report = (title, text, reason) => ({
  title, text, characters: text.length, reason,
});