memoryview methods and data members are missing docstrings

[abalkin]

BPO	15855
Nosy	@abalkin, @pitrou, @bitdancer, @skrah
Files	issue15855.diff

^{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 = None
closed_at = <Date 2014-10-04.22:05:07.214>
created_at = <Date 2012-09-03.13:25:50.241>
labels = ['type-bug']
title = 'memoryview methods and data members are missing docstrings'
updated_at = <Date 2014-10-04.22:05:07.181>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2014-10-04.22:05:07.181>
actor = 'r.david.murray'
assignee = 'none'
closed = True
closed_date = <Date 2014-10-04.22:05:07.214>
closer = 'r.david.murray'
components = []
creation = <Date 2012-09-03.13:25:50.241>
creator = 'belopolsky'
dependencies = []
files = ['27111']
hgrepos = []
issue_num = 15855
keywords = ['patch']
message_count = 14.0
messages = ['169762', '169769', '169772', '169773', '169783', '169791', '169794', '169802', '169803', '169804', '169805', '169807', '169808', '228500']
nosy_count = 6.0
nosy_names = ['belopolsky', 'pitrou', 'r.david.murray', 'skrah', 'Alexander.Belopolsky', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue15855'
versions = ['Python 3.2', 'Python 3.3']

[abalkin]

With attached patch python -mpydoc memoryview display looks as follows:

...
| cast(...)
| M.cast(format[, shape]) -> memoryview
|
| Cast a memoryview to a new format or shape.
|
| release(...)
| M.release() -> None
|
| Release the underlying buffer exposed by the memoryview object.
|
| tobytes(...)
| M.tobytes() -> bytes
|
| Return the data in the buffer as a bytestring.
|
| tolist(...)
| M.tobytes() -> list
|
| Return the data in the buffer as a list of elements.

[abalkin]

In the new patch, I added docstrings for the data members and now the list of memoryview data descriptors looks as follows in pydoc:

| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| c_contiguous
| A bool indicating whether the memory is C contiguous.
|
| contiguous
| A bool indicating whether the memory is contiguous.
|
| f_contiguous
| A bool indicating whether the memory is Fortran contiguous.
|
| format
| A string containing the format (in struct module style)
| for each element in the view.
|
| itemsize
| The size in bytes of each element of the memoryview.
|
| nbytes
| The amount of space in bytes that the array would use in
| a contiguous representation.
|
| ndim
| An integer indicating how many dimensions of a multi-dimensional
| array the memory represents.
|
| obj
| The underlying object of the memoryview.
|
| readonly
| A bool indicating whether the memory is read only.
|
| shape
| A tuple of ndim integers giving the shape of the memory
| as a N-dimensional array.
|
| strides
| A tuple of ndim integers giving the size in bytes to access
| each element for each dimension of the array or None for C
| contiguous.
|
| suboffsets
| A tuple of ndim integers used internally for PIL-style arrays
| or None.

[pitrou]

This should also be fixed in 3.2 (at least for those methods/members which are in 3.2).

[abalkin]

I am going to commit this tonight. Stefan, please let me know if you have any comments. I copied most of the descriptions from ReST manual with a few minor changes. See shape/strides/suboffsets.

[skrah]

I've left a couple of comments. -- Personally I'd also prefer if all
docstrings go into a separate section. I always perceive docstrings
as noise that takes up precious vertical space, so for _decimal I even
banned them into docstrings.h.

I don't know if there's any kind of convention for that though.

[AlexanderBelopolsky]

On Sep 3, 2012, at 1:22 PM, Stefan Krah <report@bugs.python.org> wrote:

Personally I'd also prefer if all
docstrings go into a separate section. I always perceive docstrings
as noise that takes up precious vertical space, so for _decimal I even
banned them into docstrings.h.

I don't know if there's any kind of convention for that though.

I've seen two types of convention: a docs trying before function definition and docstring after function body. I prefer the first because the docstring doubles as a short comment describing the function that follows. If we put docstrings in a separate section, we may see comments above functions diverge from docstrings over time.

On the other hand, this is not that important and consolidating the changes in one section will make 3.2 to 3.3 merge easier. I'll consolidate and wait for someone else to complain. :-)

[skrah]

On the other hand, this is not that important and consolidating the changes in one section will make 3.2 to 3.3 merge easier. I'll consolidate and wait for someone else to complain. :-)

Thanks! I'm certain someone will complain, probably on python-dev right after
you commit. :)

[python-dev]

New changeset c49f89261d65 by Alexander Belopolsky in branch '3.2':
Issue bpo-15855: added docstrings for memoryview methods and data descriptors.
http://hg.python.org/cpython/rev/c49f89261d65

[python-dev]

New changeset 16a69ccff5ce by Alexander Belopolsky in branch 'default':
Issue bpo-15855: added docstrings for memoryview methods and data descriptors (merge 3.2).
http://hg.python.org/cpython/rev/16a69ccff5ce

[python-dev]

New changeset ba2c1def3710 by Alexander Belopolsky in branch 'default':
Issue bpo-15855: added docstrings for memoryview methods and data descriptors new in 3.3.
http://hg.python.org/cpython/rev/ba2c1def3710

[abalkin]

A few remaining comments:

1. shape being None for 0-d views in 3.2 is probably a bug. I did not mention that behavior in docstring.

2. "a N-dimensional array" typo was copied from ReST. Fixing it does not deserve a separate tracker entry, but I would like to review the whole section and add new/changed in 3.3 as necessary once we resolve (1) above.

[skrah]

1. shape being None for 0-d views in 3.2 is probably a bug.

Probably. I don't know whether it's worth fixing. Several test cases in ctypes
as well as in NumPy rely on it. So I guess we should just leave it for 3.2.

2. "a N-dimensional array" typo was copied from ReST. Fixing it does
   not deserve a separate tracker entry, but I would like to review the
   whole section and add new/changed in 3.3 as necessary once we resolve
   (1) above.

There are definitely some places where new/changed could be added
(e.g. the empty tuple for 0-d views is not mentioned).

[python-dev]

New changeset 82ae284cd5f1 by Alexander Belopolsky in branch 'default':
Issue bpo-15855: updated related manual entries.
http://hg.python.org/cpython/rev/82ae284cd5f1