CA-certs bundles and requests.certs.where - Improved documentation

[velle]

I initially thought requests.certs.where (as well as certifi.where) returned the location of the cacert file actually being used, and I could use it to verify that the correct file was loaded. I am not the only one to make this mistake: https://stackoverflow.com/a/42982144/735070.

I have realized though, that it simply return the path of the bundled cacert file that comes included with the library.

Demonstration of this behavior:

#test.py
import requests, certifi,os
print('os.environ.get("REQUESTS_CA_BUNDLE") -> ',repr(os.environ.get("REQUESTS_CA_BUNDLE")))
print('os.environ.get("CURL_CA_BUNDLE")     -> ',repr(os.environ.get("CURL_CA_BUNDLE")))
print('requests.cert.where())               -> ',repr(requests.certs.where()))
print('certifi.where())                     -> ',repr(certifi.where()))

Running test.py in shell with REQUESTS_CA_BUNDLE set:

$ REQUESTS_CA_BUNDLE=/home/jdoe/catest/my_cacert.pem python test.py
os.environ.get("REQUESTS_CA_BUNDLE") ->  '/home/jdoe/catest/my_cacert.pem'
os.environ.get("CURL_CA_BUNDLE")     ->  None
requests.cert.where())               ->  '/home/jdoe/.local/lib/python3.10/site-packages/certifi/cacert.pem'
certifi.where())                     ->  '/home/jdoe/.local/lib/python3.10/site-packages/certifi/cacert.pem'

Improve documentation - requests.certs.where-function

Currently requests.certs.where.__doc__ returns null. How about

returns the path of the CA-certs bundle that is included with the requests package, ie not necessarily the bundle actually being used.

Improve documentation - How is CA-bundle chosen

Maybe the simplest way of making this clear is to add a section with a list or decision tree that shows which file (if any) will be used as CA-certs bundle.

Add some way of getting the bundle actually being used

In my case a static function, requests.cacerts_loaded(). I realize this may return a file different from the one being used, if the user specifies verify (and maybe its possible to change in other ways too).

Demonstration run on

• certifi version: 2023.05.07
• requests version: 2.25.1
• Python 3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0] on linux

[kevinlinxc]

I was so confused when I set REQUEST_CA_BUNDLE and the where() functions didn't change.