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: memoryview methods and data members are missing docstrings
Type: behavior Stage: resolved
Components: Versions: Python 3.2, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Alexander.Belopolsky, belopolsky, pitrou, python-dev, r.david.murray, skrah
Priority: normal Keywords: patch

Created on 2012-09-03 13:25 by belopolsky, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue15855.diff belopolsky, 2012-09-03 16:04 review
Messages (14)
msg169762 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-09-03 13:25
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.
msg169769 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-09-03 16:04
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.
msg169772 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2012-09-03 16:34
This should also be fixed in 3.2 (at least for those methods/members which are in 3.2).
msg169773 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-09-03 16:47
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.
msg169783 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2012-09-03 17:22
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.
msg169791 - (view) Author: Alexander Belopolsky (Alexander.Belopolsky) Date: 2012-09-03 18:16
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. :-)
msg169794 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2012-09-03 18:42
> 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. :)
msg169802 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-03 20:29
New changeset c49f89261d65 by Alexander Belopolsky in branch '3.2':
Issue #15855: added docstrings for memoryview methods and data descriptors.
http://hg.python.org/cpython/rev/c49f89261d65
msg169803 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-03 20:44
New changeset 16a69ccff5ce by Alexander Belopolsky in branch 'default':
Issue #15855: added docstrings for memoryview methods and data descriptors (merge 3.2).
http://hg.python.org/cpython/rev/16a69ccff5ce
msg169804 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-03 20:51
New changeset ba2c1def3710 by Alexander Belopolsky in branch 'default':
Issue #15855: added docstrings for memoryview methods and data descriptors new in 3.3.
http://hg.python.org/cpython/rev/ba2c1def3710
msg169805 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2012-09-03 20:58
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.
msg169807 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2012-09-03 21:16
> 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).
msg169808 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-03 21:29
New changeset 82ae284cd5f1 by Alexander Belopolsky in branch 'default':
Issue #15855: updated related manual entries.
http://hg.python.org/cpython/rev/82ae284cd5f1
msg228500 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-04 22:05
It looks like there is nothing left to do here and the issue was left open by mistake.  If I'm wrong, someone can reopen it with a note as to what remains to be done (or open a new issue).
History
Date User Action Args
2022-04-11 14:57:35adminsetgithub: 60059
2014-10-04 22:05:07r.david.murraysetstatus: open -> closed

nosy: + r.david.murray
messages: + msg228500

resolution: fixed
stage: commit review -> resolved
2012-09-03 21:29:32python-devsetmessages: + msg169808
2012-09-03 21:16:12skrahsetmessages: + msg169807
2012-09-03 20:58:40belopolskysetmessages: + msg169805
2012-09-03 20:51:10python-devsetmessages: + msg169804
2012-09-03 20:44:08python-devsetmessages: + msg169803
2012-09-03 20:29:39python-devsetnosy: + python-dev
messages: + msg169802
2012-09-03 18:42:57skrahsetmessages: + msg169794
2012-09-03 18:16:49Alexander.Belopolskysetnosy: + Alexander.Belopolsky
messages: + msg169791
2012-09-03 17:22:27skrahsetmessages: + msg169783
2012-09-03 16:47:26belopolskysetmessages: + msg169773
stage: commit review
2012-09-03 16:34:15pitrousetnosy: + pitrou

messages: + msg169772
versions: + Python 3.2, Python 3.3, - Python 3.4
2012-09-03 16:04:50belopolskysetfiles: - memoryobject-docstrings.diff
2012-09-03 16:04:38belopolskysetfiles: + issue15855.diff

messages: + msg169769
title: memoryview methods are missing docstrings -> memoryview methods and data members are missing docstrings
2012-09-03 13:25:50belopolskycreate