psf / psf/requests

Documentation for stream parameter is ambiguous

Open Beginner friendly
#7,599 3 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.