IO buffering behaviour not properly documented

[pakal]

BPO	7545
Nosy	@birkenfeld, @pitrou, @pakal
Files	io-open-doc.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/pitrou'
closed_at = <Date 2009-12-19.21:10:17.427>
created_at = <Date 2009-12-19.15:59:10.085>
labels = ['expert-IO', 'docs']
title = 'IO buffering behaviour not properly documented'
updated_at = <Date 2009-12-19.21:10:17.426>
user = 'https://github.com/pakal'

bugs.python.org fields:

activity = <Date 2009-12-19.21:10:17.426>
actor = 'pitrou'
assignee = 'pitrou'
closed = True
closed_date = <Date 2009-12-19.21:10:17.427>
closer = 'pitrou'
components = ['Documentation', 'IO']
creation = <Date 2009-12-19.15:59:10.085>
creator = 'pakal'
dependencies = []
files = ['15611']
hgrepos = []
issue_num = 7545
keywords = ['patch']
message_count = 7.0
messages = ['96607', '96608', '96616', '96630', '96640', '96644', '96647']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'pitrou', 'pakal']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue7545'
versions = ['Python 2.6', 'Python 2.7']

[pakal]

Hello,
It seems there is an important difference between the doc of the IO
module, and its implementation so far (until todcay trunk revision 76805)

"buffering is an optional integer used to set the buffering policy. By
default full buffering is on. Pass 0 to switch buffering off (only
allowed in binary mode), 1 to set line buffering, and an integer > 1 for
full buffering."
--> actually full buffering only occurs if a negative buffering
parameter is given, else it seems th current value i kept as the buffer
size - eg. if we give "3", buffering will be 3 bytes...
This seems a fine behaviour to me, so this implementation could just be
documented as is.

-----------

Only case of full buffering in the C iomodule :
    if (buffering < 0) {
        buffering = DEFAULT_BUFFER_SIZE;
#ifdef HAVE_STRUCT_STAT_ST_BLKSIZE
        {
            struct stat st;
            long fileno;
            PyObject *res = PyObject_CallMethod(raw, "fileno", NULL);
            if (res == NULL)
                goto error;

            fileno = PyInt_AsLong(res);
            Py_DECREF(res);
            if (fileno == -1 && PyErr_Occurred())
                goto error;

        if (fstat(fileno, &st) \>= 0)
            buffering = st.st_blksize;
    }

#endif
}

[pitrou]

"Full buffering" means exactly what you discovered it means - enable a
buffer of a given number of bytes (3, 4096 or anything else). I'm not
sure what you thought it meant? That the file was buffered in its
entirety, regardless of its size?

[birkenfeld]

The docs have a different wording, which I suggest copying to the docstring:

*buffering* is an optional integer used to set the buffering policy. By
default full buffering is on. Pass 0 to switch buffering off (only
allowed
in binary mode), 1 to set line buffering, and an integer > 1 to
indicate the
size of the buffer.

But now the question remains what the default is -- "full buffering" is
only meaningful with a specified buffer size. The implementation seems
to default to line buffering.

[pitrou]

But now the question remains what the default is -- "full buffering" is
only meaningful with a specified buffer size. The implementation seems
to default to line buffering.

"full" buffering actually uses a default or custom buffer size when you
don't specify it. 4096 or 8192 usually (yes there's a heuristic :-)).

"full" buffering is the default for binary streams, as well as for text
streams which aren't a tty. text streams which are tty default to line
buffering.

(I admit full buffering is a confusing name; what could we use instead?
fixed-size buffering? chunk buffering?)

[pitrou]

Here is a possible patch for the Doc. I suppose the docstrings need
updating too?

[pakal]

Yep, I knew "full buffering" didn't mean "fill my RAM until crash" :p
The only visible problem was the interpretation of positive/negative
buffering value, which wasn't the same in doc and in code. But the patch
seems to fix up the plot prettily well B-)
Thanks

[pitrou]

Thank you, fixed in a lot of revisions.