Build has FAILED

Link to build: https://jenkins.softwareheritage.org/job/DCIDX/job/tox/558/
See console output for more information: https://jenkins.softwareheritage.org/job/DCIDX/job/tox/558/console

Ok, that one is a nasty example of a docstring.

While this is indeed a docstring, it contains code that gets executed (this is denoted by >>> and ... at the beginning of lines). This is also known as a doctest.

What happens here is that some code gets executed, eg:

>>> pprint(NpmMapping().normalize_author({
...     'name': 'John Doe',
...     'email': 'john.doe@example.org',
...     'url': 'https://example.org/~john.doe',
... }))

And Python compares the result of this code, with the expected result, eg:

{'@list': [{'@type': 'http://schema.org/Person',
            'http://schema.org/email': 'john.doe@example.org',
            'http://schema.org/name': 'John Doe',
            'http://schema.org/url': {'@id': 'https://example.org/~john.doe'}}]}

So if one changes the expected result, the test fails, because the actual result no longer matches what we wrote was the expected result.

In conclusion, doctests are an exception to the formatting rules.

Then swh-indexer does not require any changes I will close this diff. Wow, I never new docstrings could be evaluated. Why is this required though?

A docstring is just some text. It's evaluated by doctest, an external tool, that makes sure that code we write in the docstring actually works.

This way, we are alerted when the documentation becomes out of date, because it makes the doctest fail.

I get it now, that's an ingenious way of keeping documentation up to date. However if this is evaluated why is adding whitespace changing the output, the dictionary and list should still have valid items.

It could in theory, but in practice it converts both items to strings, and compares the string character-per-character

I'll close this revision.