linkcheck: add a distinct 'timeout' reporting status

[jayaddison]

Feature or Bugfix

• Feature

Purpose

• Provides a distinction between broken links (fairly high confidence that the URI/resource does not currently exist) and timeouts (no response was received for the URI within the alloted time).

Detail

• Adds an additional case-handler for Timeout exceptions from the requests library when checking hyperlinks.
• Maintains a non-zero exit code when timeouts are encountered - the rationale here is that there was an unexpected problem that could require investigation (in other words: not all links were filtered/ignored/found-successfully).

Relates

• Resolves linkcheck builder: add a distinct reporting status code for timeouts #11868.

[jayaddison]

Todo: consider the interaction between these changes and the low-level Python socket timeout, because we configure a value for that.

[jayaddison]

Todo: consider the interaction between these changes and the low-level Python socket timeout, because we configure a value for that.

Generally I think that because we provide a timeout= argument when making HTTP requests via requests (that in turn configures timeouts via urllib3), the socket.setdefaulttimeout call should -- in theory -- be redundant.

However: I think we should wait until urllib3>=2.0.0 is our baseline before considering removing the configuration of a 5s socket timeout there. That's because there were some bugs relating to timeout handling that are addressed in v2.0.0 of urllib3.

As a result, I don't think we should remove the setdefaulttimeout call before we declare requests>=2.30.0 as a baseline, at the very earliest. In practice we should wait longer, because just because requests 2.30.0 added support for urllib3 v2.0.0 doesn't mean that everyone using it will upgrade immediately.