python / python/cpython

open() built in's doc does not say what the buffering default of -1 means

Open
#93,600 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs
Dominant language
Python
Stars
77.2k
Forks
36k
PR merge metrics
PR metrics pending

Description

On this page https://docs.python.org/3.10/library/functions.html#open the signature of the function is shown as:

open(file, mode='r', buffering=- 1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Notice the spurious space between the - and the 1.

But more importantly, the explanation of bufferings meaning is:

buffering is an optional integer used to set the buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size in bytes of a fixed-size chunk buffer.

In other words, it does not explain what the -1 default means. I assume it means "use the default buffering size for the given mode"; but it really ought to say.

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 with the open() documentation page at docs.python.org/3.10/library/functions.html#open and inspect the signature and buffering parameter description. Done means removing the spurious space in -1 and documenting what the default buffering value means.

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
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.