Add specific exceptions for authentication issues

[PLPeeters]

What do these changes do?

They add more specific exceptions for authentication issues to avoid getting a blanket UnicodeEncodeError when authentication credentials cannot be encoded.

Are there changes in behavior for the user?

Yes, but for the better as they will get clearer exceptions. Instead of getting a UnicodeEncodeError in such cases, users will be met with one of the following:

• an InvalidAuthClientError if it's the authentication passed via the auth parameter that cannot be encoded
• an InvalidUrlAuthClientError (subclass of InvalidURL) if it's the authentication that is present in the input URL that cannot be encoded
• an InvalidRedirectUrlAuthClientError (subclass of InvalidUrlRedirectClientError) if it's the authentication that is present in a redirect URL that cannot be encoded

I initially was going to go with a single exception, but I believe differentiating them makes sense, as:

• the first one is due to user error
• the second one can be due to user error or input error (in the context of a crawler crawling arbitrary URLs for instance)
• the third one is due to an issue with the website being accessed

Each of these could warrant a different response from the user depending on their need, but at the same time the ones for which the user is potentially not responsible can still be caught by a blanket except InvalidURL block.

For a bit more context, in my implementation I currently would need to catch UnicodeEncodeError on a block that does way more than just do the GET call via aiohttp, and it could very well be that at some point unrelated code in this block raises a UnicodeEncodeError, which I would need to know about. There are of course ways around that, but having a more specific exception is just cleaner overall.

Is it a substantial burden for the maintainers to support this?

No.

Related issue number

N/A

Checklist

• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes => waiting for a go-ahead first since this is not linked to an open issue
• If you provide code modification, please add yourself to CONTRIBUTORS.txt
  • The format is <Name> <Surname>.
  • Please keep alphabetical order, the file is sorted by names.
• Add a new news fragment into the CHANGES/ folder => waiting for a go-ahead first since this is not linked to an open issue

  • name it <issue_or_pr_num>.<type>.rst (e.g. 588.bugfix.rst)

  • if you don't have an issue number, change it to the pull request
    number after creating the PR

    • .bugfix: A bug fix for something the maintainers deemed an
      improper undesired behavior that got corrected to match
      pre-agreed expectations.
    • .feature: A new behavior, public APIs. That sort of stuff.
    • .deprecation: A declaration of future API removals and breaking
      changes in behavior.
    • .breaking: When something public is removed in a breaking way.
      Could be deprecated in an earlier release.
    • .doc: Notable updates to the documentation structure or build
      process.
    • .packaging: Notes for downstreams about unobvious side effects
      and tooling. Changes in the test invocation considerations and
      runtime assumptions.
    • .contrib: Stuff that affects the contributor experience. e.g.
      Running tests, building the docs, setting up the development
      environment.
    • .misc: Changes that are hard to assign to any of the above
      categories.

  • Make sure to use full sentences with correct case and punctuation,
    for example:

    Fixed issue with non-ascii contents in doctest text files
    -- by :user:`contributor-gh-handle`.

    Use the past tense or the present tense a non-imperative mood,
    referring to what's changed compared to the last released version
    of this project.

[codspeed-hq]

CodSpeed Performance Report

Merging #10633 will not alter performance

_{Comparing PLPeeters:feature/invalid-auth-exceptions (cdaeb38) with master (c8e14b1)}

Summary

✅ 47 untouched benchmarks

[bdraco]

This looks like a breaking change for anyone trapping UnicodeEncodeError currently since the new exceptions don't include it in the inheritance.

[bdraco]

We could avoid the breaking change by making the new exceptions also derived from UnicodeEncodeError

[PLPeeters]

Good point, but hypothetically a case could be added later where these exceptions no longer stem from a UnicodeEncodeError so that would also make it weird.

If we don't want to make the exceptions as generic as possible now, I'd include UnicodeEncodeError in the exception names in addition to the inheritance to avoid someone reusing it for some other root error down the line.

[bdraco]

Maybe we could use InvalidRedirectUrlAuthClientUnicodeEncodeError and InvalidUrlAuthClientUnicodeEncodeError, which inherit from both.
I know, they're a bit of a mouthful 😉

or maybe just InvalidRedirectUrlAuthClientUnicodeError and InvalidUrlAuthClientUnicodeError

[PLPeeters]

What about a shorter [Redirect]UrlAuthUnicodeEncodingError?