From d6708ed663b6579ea9ec5c18d06614f1c2479a37 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 16 Jan 2024 15:25:51 +0200 Subject: [PATCH 1/5] gh-114115: Update documentation of array.array --- Doc/library/array.rst | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/Doc/library/array.rst b/Doc/library/array.rst index ad622627724217..a93732b7f52e5a 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -79,14 +79,16 @@ The module defines the following type: .. class:: array(typecode[, initializer]) A new array whose items are restricted by *typecode*, and initialized - from the optional *initializer* value, which must be a list, a - :term:`bytes-like object`, or iterable over elements of the - appropriate type. + from the optional *initializer* value, which must be a :class:`bytes` + or :class:`bytearray` object, a unicode string, or iterable over elements + of the appropriate type. - If given a list or string, the initializer is passed to the new array's - :meth:`fromlist`, :meth:`frombytes`, or :meth:`fromunicode` method (see below) - to add initial items to the array. Otherwise, the iterable initializer is - passed to the :meth:`extend` method. + If given a :class:`bytes` or :class:`bytearray` object, the initializer + is passed to the new array's :meth:`frombytes` method; + if given a unicode string, the initializer is passed to the + :meth:`fromunicode` method; + otherwise, the initializer's iterator is passed to the :meth:`extend` method + to add initial items to the array. Array objects support the ordinary sequence operations of indexing, slicing, concatenation, and multiplication. When using slice assignment, the assigned @@ -152,10 +154,11 @@ The module defines the following type: must be the right type to be appended to the array. - .. method:: frombytes(s) + .. method:: frombytes(buffer) - Appends items from the string, interpreting the string as an array of machine - values (as if it had been read from a file using the :meth:`fromfile` method). + Appends items from the :term:`bytes-like object`, interpreting + it's content as an array of machine values (as if it had been read + from a file using the :meth:`fromfile` method). .. versionadded:: 3.2 :meth:`!fromstring` is renamed to :meth:`frombytes` for clarity. @@ -244,7 +247,7 @@ The module defines the following type: obtain a unicode string from an array of some other type. -When an array object is printed or converted to a string, it is represented as +When an array object is converted to a string, it is represented as ``array(typecode, initializer)``. The *initializer* is omitted if the array is empty, otherwise it is a string if the *typecode* is ``'u'`` or ``'w'``, otherwise it is a list of numbers. From 2fc72471e376edcb491008583b456365a3013096 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 16 Jan 2024 21:40:47 +0200 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/array.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/array.rst b/Doc/library/array.rst index a93732b7f52e5a..789f57d2937385 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -85,7 +85,7 @@ The module defines the following type: If given a :class:`bytes` or :class:`bytearray` object, the initializer is passed to the new array's :meth:`frombytes` method; - if given a unicode string, the initializer is passed to the + if given a Unicode string, the initializer is passed to the :meth:`fromunicode` method; otherwise, the initializer's iterator is passed to the :meth:`extend` method to add initial items to the array. @@ -157,7 +157,7 @@ The module defines the following type: .. method:: frombytes(buffer) Appends items from the :term:`bytes-like object`, interpreting - it's content as an array of machine values (as if it had been read + its content as an array of machine values (as if it had been read from a file using the :meth:`fromfile` method). .. versionadded:: 3.2 From 3b48388580138bc23c04e1f7b0035835a11529ba Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 18 Jan 2024 13:33:07 +0200 Subject: [PATCH 3/5] Capitalize Unicode. --- Doc/library/array.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/array.rst b/Doc/library/array.rst index 789f57d2937385..3b28cc00a62c8d 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -80,7 +80,7 @@ The module defines the following type: A new array whose items are restricted by *typecode*, and initialized from the optional *initializer* value, which must be a :class:`bytes` - or :class:`bytearray` object, a unicode string, or iterable over elements + or :class:`bytearray` object, a Unicode string, or iterable over elements of the appropriate type. If given a :class:`bytes` or :class:`bytearray` object, the initializer @@ -180,7 +180,7 @@ The module defines the following type: .. method:: fromunicode(s) - Extends this array with data from the given unicode string. + Extends this array with data from the given Unicode string. The array must have type code ``'u'`` or ``'w'``; otherwise a :exc:`ValueError` is raised. Use ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an array of some other type. @@ -242,9 +242,9 @@ The module defines the following type: .. method:: tounicode() - Convert the array to a unicode string. The array must have a type ``'u'`` or ``'w'``; + Convert the array to a Unicode string. The array must have a type ``'u'`` or ``'w'``; otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to - obtain a unicode string from an array of some other type. + obtain a Unicode string from an array of some other type. When an array object is converted to a string, it is represented as From 487a439a2434e33d7840f03d3381ce1d18aa814a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Thu, 18 Jan 2024 17:39:03 +0200 Subject: [PATCH 4/5] Update the description of the string representation. --- Doc/library/array.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/Doc/library/array.rst b/Doc/library/array.rst index 3b28cc00a62c8d..00ce34a4412460 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -247,19 +247,22 @@ The module defines the following type: obtain a Unicode string from an array of some other type. -When an array object is converted to a string, it is represented as -``array(typecode, initializer)``. The *initializer* is omitted if the array is -empty, otherwise it is a string if the *typecode* is ``'u'`` or ``'w'``, -otherwise it is a list of numbers. -The string is guaranteed to be able to be converted back to an +The string representation of array objects has a form +``array(typecode, initializer)``. +The *initializer* is omitted if the array is empty, otherwise it is +a Unicode string if the *typecode* is ``'u'`` or ``'w'``, otherwise it is +a list of numbers. +The string representation is guaranteed to be able to be converted back to an array with the same type and value using :func:`eval`, so long as the :class:`~array.array` class has been imported using ``from array import array``. +Variables ``inf`` and ``nan`` must also be defined if it contains +corresponding floating point values. Examples:: array('l') array('w', 'hello \u2641') array('l', [1, 2, 3, 4, 5]) - array('d', [1.0, 2.0, 3.14]) + array('d', [1.0, 2.0, 3.14, -inf, nan]) .. seealso:: From d6dd00a05015447e96a4aeec4d70a63476409dda Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 22 Jan 2024 10:35:38 +0200 Subject: [PATCH 5/5] Update Doc/library/array.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/array.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/array.rst b/Doc/library/array.rst index 00ce34a4412460..a0e8bb20a098fd 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -247,7 +247,7 @@ The module defines the following type: obtain a Unicode string from an array of some other type. -The string representation of array objects has a form +The string representation of array objects has the form ``array(typecode, initializer)``. The *initializer* is omitted if the array is empty, otherwise it is a Unicode string if the *typecode* is ``'u'`` or ``'w'``, otherwise it is