normalize_citation_url

documenteer.citations.normalize_citation_url(value, *, field='url')

Normalize a citation’s landing-page URL, rejecting one that could not be linked.

Parameters:

• value (str) – The landing page, as a source wrote it. Surrounding whitespace is stripped.

• field (str, default: 'url') – The name of the field the value came from, so that the error names the field a reader has to fix. It defaults to url, which is what both [[project.citations]] and CITATION.cff call it.

Returns:

The URL with its surrounding whitespace removed.

Return type:

str

Raises:

ValueError – Raised if the value is blank, or is not an absolute http or https URL.

Notes

This is validation rather than repair, because there is no spelling to repair into: a scheme-less github.com/lsst/daf_butler could mean either scheme, and guessing would publish a landing page the configuration never stated. Left alone it is worse than rejected: Citation.location hands it to a template verbatim, where it becomes a link relative to the page being rendered and a relative IRI as a JSON-LD node’s @id.

Blankness is checked first and separately because a blank value is the one that otherwise passes silently: it is truthy, so it satisfies every “is a URL set?” test a caller makes, and only reduces to nothing at the point where a citation is composed (see _clean) — yielding a citation with no location at all rather than an error.

Each of the three ways a value can fail names that failure, rather than sharing one message: ftp://example.org/dp1.tar is a perfectly absolute URL, and telling its author it “is not an absolute URL” sends them looking for a missing scheme instead of at the scheme they wrote.