This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: clarify functions docs in IO modules and Bytes Objects
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Windson Yang, docs@python, methane, terry.reedy
Priority: normal Keywords: patch

Created on 2019-05-28 07:18 by Windson Yang, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 13713 closed Windson Yang, 2019-06-01 04:26
PR 13715 closed Windson Yang, 2019-06-01 04:34
Messages (4)
msg343741 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-05-28 07:18
> PyBytes_FromStringAndSize(const char *v, Py_ssize_t len): 
> Return a new bytes object with a copy of the string v as value and length len on success, and NULL on failure. If v is NULL, the contents of the bytes object are uninitialized.

The function actually copies `len` bytes from string v instead of the whole string. (link 1) I suggested we can change to 

> Return a new bytes object with a copy of the first len bytes of string v as value and length len on success...

> readinto(b)
> Read bytes into a pre-allocated, writable bytes-like object b and return the number of bytes read. For example, b might be a bytearray.

The function will call _bufferediobase_readinto_generic(link 2) which may return NULL. Maybe we can change to 

> and return the number of bytes that read succeed (it may be smaller than b or NULL if failed)...

1. https://github.com/python/cpython/blob/master/Objects/bytesobject.c#L126

2. https://github.com/python/cpython/blob/master/Modules/_io/bufferedio.c#L962
msg344126 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-05-31 21:22
Can you prepare a PR?
msg344147 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-06-01 04:17
Sure. Feel free to edit my PR.
msg357359 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2019-11-23 03:25
> The function actually copies `len` bytes from string v instead of the whole string. 

"and length *len*" means it.  So it is not a bug.

If you want to rewrite it to "the first *len* bytes of", you should remove "and length *len*".

But please note that every small change will break translations.
Unless you are sure it is better than the current version, please don't change it.

> _bufferediobase_readinto_generic(link 2) which may return NULL.

It doesn't return NULL.  NULL in C means it raises the error.
And we don't document it usually.  Otherwise, almost all document has "it may raise an exception when an error happens."
History
Date User Action Args
2022-04-11 14:59:15adminsetgithub: 81254
2019-11-23 03:25:51methanesetstatus: open -> closed
resolution: rejected
stage: patch review -> resolved
2019-11-23 03:25:39methanesetnosy: + methane
messages: + msg357359
2019-06-01 04:34:23Windson Yangsetpull_requests: + pull_request13602
2019-06-01 04:26:41Windson Yangsetkeywords: + patch
stage: patch review
pull_requests: + pull_request13600
2019-06-01 04:17:03Windson Yangsetmessages: + msg344147
2019-05-31 21:22:42terry.reedysetnosy: + terry.reedy
messages: + msg344126
2019-05-28 07:18:04Windson Yangcreate