Deprecate the SecureTransport TLS implementation

[sethmlarson]

The SecureTransport implementation was added to support OpenSSL versions that didn't support TLS 1.2 and later on macOS. Python on macOS has been improved greatly over time that we're now in a place to force OpenSSL 1.1.1+ in Python and urllib3.

Now that there's little upside to using SecureTransport it's hard to justify the maintenance burden.

My proposal for now is:

• Create documentation for SecureTransport's deprecation in the docs. We'll be targetting a "future 2.x release" with the actual removal.
• Begin unconditionally emitting a DeprecationWarning when urllib3.contrib.securetransport.inject_into_urllib3 is called and point to the documentation.
• Find projects using urllib3.contrib.securetransport and help them remove support.

In a future 2.x version:

• Make the inject_into_urllib3 function raise an exception with a URL to the documentation.

In a version after that:

• Remove the inject_into_urllib3 function and urllib3.contrib.securetransport contrib module.

[fyunusa]

Hi @sethmlarson i've added the deprecation warning to the inject_into_urllib3() method in the securetransport module. Just a quick questions:

1. Hope it's fine to reference the warning to the https://urllib3.readthedocs.io/en/stable/reference/contrib/securetransport.html section of the doc as the deprecation notice will also be in this section of the doc.

def inject_into_urllib3() -> None:
    
    warnings.warn(
        "'urllib3.contrib.securetransport.inject_into_urllib3()' is deprecated and will be removed "
        "in a future release of urllib3 2.x. Read more in the doc: "
        "https://urllib3.readthedocs.io/en/stable/reference/contrib/securetransport.html",
        category=DeprecationWarning,
        stacklevel=2,
    )
    .......
    .......
    .......

[pquentin]

Yes, links to the docs are one honking great idea -- let's do more of those!

[fyunusa]

OK nice @pquentin I'll try to work on the remaining task.