Documentation for stream parameter is ambiguous
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 54.3k
- Forks
- 10.4k
- Avg merge
- 16h 43m
- Merged PRs (30d)
- 3
Description
Old docs suggest to me that if False, it won't be immediately be downloaded: https://github.com/psf/requests/blob/1f6589ec3a1ee910f9a65cc3ceac60b26677bc0e/src/requests/sessions.py#L605
: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
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 in src/requests/sessions.py at the stream parameter docstring around line 605, then compare its wording with the Body Content Workflow documentation. Clarify the relationship between stream=True and immediate downloading, keeping the proposed default behavior unambiguous. Run pre-commit afterward and confirm the documentation formatting passes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100