Documentation for stream parameter is ambiguous

[diederikvdv]

Old docs suggest to me that if False, it won't be immediately be downloaded:

requests/src/requests/sessions.py

Line 605 in 1f6589e

:param stream: (optional) whether to immediately download the response

        :param stream: (optional) whether to immediately download the response
            content. Defaults to ``False``.

Expected Result VS Actual result

whether to immediately download the response default anwer=False, so it won't immediately download the response. According to https://requests.readthedocs.io/en/latest/user/advanced/#body-content-workflow it is the other way around, so if stream==True, then it won't immediately download the response.

Proposed fix

        :param stream: (optional) Whether to use the streaming property. Defaults to ``False``.
            When set to ``False``, the response content will be immediately downloaded.

Removes the ambiguity from the docstring

Checks/ steps done

• I didn't see existing issues for this
• I didn't see existing PRs for this
• I tried to run it locally with pre-commit
  • Earlier I had 1 big line, but pre-commit didn't auto format it to a shorter line, so I did that manually
• I tried to fork and create a PR, but that was blocked, so I created this issue

[tokieashir17]

Hi @diederikvdv,

I prepared a documentation fix for this issue and pushed it to my fork:

https://github.com/tokieashir17/requests/tree/clarify-stream-docs

The change clarifies the stream parameter behavior in sessions.py.

I attempted to open a pull request, but GitHub is preventing me from creating one because the repository appears to restrict PR creation to collaborators.

If a maintainer is able to open a PR from my branch, or if there is another preferred way to submit the change, I would be happy to help.

Thanks!