documentation for requests.session.request(verify=...) duplicates requests.request() even where it is different
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 54.3k
- Forks
- 10.4k
- Avg merge
- 16h 43m
- Merged PRs (30d)
- 3
Description
Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True.
I suggest rewording both statements, because as they stand they make figuring what went wrong with setting the correct CA bundle way harder than it should be:
- Passing bool not only controls whether the certificate is verified, it also resets the root store to be verified against.
- The default for the method does not behave like True - leaving it unspecified simply defers to the session, as it should.. session in turn may very well have verify=False.
- (still incomplete because of
os.environprecedence, but I understand that one is currently #WONTFIX as per https://github.com/psf/requests/issues/3829)
Documentation appears to state
| s.verify=True | s.verify="/S" | s.verify=False | |
|---|---|---|---|
| s.request(verify=True) | True | ✅ "/S" | True |
| s.request(verify="/r") | "/r" | "/r" | "/r" |
| s.request(verify=False) | False | False | False |
| s.request() # i.e. s.request(verify=None) | True | ⚠️True | ⚠️True |
Actual Result
| s.verify=True | s.verify="/S" | s.verify=False | |
|---|---|---|---|
| s.request(verify=True) | True | ⚠️True | True |
| s.request(verify="/r") | "/r" | "/r" | "/r" |
| s.request(verify=False) | False | False | False |
| s.request() # i.e. s.request(verify=None) | True | ✅"/S" | ✅ False |
Reproduction Steps
>>> import certifi,requests,ssl,os
>>> certifi.__version__
'2026.04.22'
>>> certifi.where()
'/inaccessible/path'
>>> requests.__version__
'2.33.1'
>>> session = requests.session()
>>> session.verify = ssl.get_default_verify_paths().capath
>>> os.path.isdir(session.verify)
True
>>> session.request(url="https://example.com", method="HEAD")
<Response [200]>
>>> session.request(url="https://example.com", method="HEAD", verify=True)
Traceback (most recent call last):
[..]
File "/home/user/lib/python3.10/site-packages/requests/adapters.py", line 304, in cert_verify
raise OSError(
OSError: Could not find a suitable TLS CA certificate bundle, invalid path: /inaccessible/path
This result means that libraries that opt to use the supposedly-default parameter value of True are doing something meaningfully different from those that use the actual-default parameter of None (typically: by not mentioning the parameter).
System Information
$ python -m requests.help
{
"chardet": {
"version": "4.0.0"
},
"charset_normalizer": {
"version": "3.4.4"
},
"cryptography": {
"version": ""
},
"idna": {
"version": "3.3"
},
"implementation": {
"name": "CPython",
"version": "3.10.12"
},
"platform": {
"release": "6.8.0-110-generic",
"system": "Linux"
},
"pyOpenSSL": {
"openssl_version": "",
"version": null
},
"requests": {
"version": "2.33.1"
},
"system_ssl": {
"version": "30000020"
},
"urllib3": {
"version": "2.6.3"
},
"using_charset_normalizer": false,
"using_pyopenssl": false
}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Session.request API documentation linked in the issue and compare its verify description with the linked sessions.py behavior. Update the documentation to distinguish explicit boolean or CA-bundle values from an omitted or None verify argument, including session-level settings, then verify that the documented cases match the reproduction tables.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100