[New-bugs-announce] [issue37073] clarify functions docs in IO modules and Bytes Objects

[Windson Yang]

New submission from Windson Yang <wiwindson at outlook.com>:

> 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

----------
assignee: docs at python
components: Documentation
messages: 343741
nosy: Windson Yang, docs at python
priority: normal
severity: normal
status: open
title: clarify functions docs in IO modules and Bytes Objects
type: enhancement
versions: Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37073>
_______________________________________