[keyring] add deprecation warning to master key providers

[mattsb42-aws]

With the introduction of keyrings, we are deprecating master key providers. We need to add deprecation notices and warnings.

[mattsb42-aws]

With this, we also need to update any examples in the API docs to use keyrings rather than master key providers.

[mattsb42-aws]

The route I ended up deciding on for this is:

In MasterKeyProvider.__new__, emit a DeprecationWarning.

https://docs.python.org/3/library/warnings.html

Why in MasterKeyProvider.__new__?

This logic runs every time any master key provider is created, whether one that we provide or any custom master key provider.

Why use warnings instead of logging.warn?

Because warnings inserts itself into the logging stream, but allows the log handler to independently control the visibility of warnings without affecting other logging.

warnings also gives log handlers information to avoid duplicate logging of warnings, which logging.warn does not.

Why use DeprecationWarning?

DeprecationWarning is ignored by default[1].

If a customer is actively looking for DeprecationWarnings then they will see them, but if they are not then they will not.

Given that we do not have a planned version when we will be removing master key providers, I think that this is the correct level of visibility. When we decide if/when we will remove master key providers, we should change this to UserWarning and communicate this upcoming breaking change as detailed in our versioning policy.

I breadcrumb to this effect is included in a comment in the code where we emit this warning.

[1] https://docs.python.org/3/library/warnings.html#warning-categories