classification
Title: memoryview() constructor documentation error
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, demian.brecht, docs@python, georg.brandl, larry, skrah
Priority: low Keywords: easy, patch

Created on 2014-01-27 11:53 by larry, last changed 2016-06-03 09:11 by skrah.

Files
File name Uploaded Description Edit
issue20408.patch demian.brecht, 2015-02-26 07:44 review
Messages (7)
msg209436 - (view) Author: Larry Hastings (larry) * (Python committer) Date: 2014-01-27 11:53
The documentation for the memoryview constructor says it takes memoryview(obj).  Oddly, memoryview accepts keyword arguments (for its one required value), and the name of the argument is "object", not "obj".
msg236641 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2015-02-26 01:42
I think it's plain daft having "object" as a keyword argument.  Is it too late to do anything about this, or could we go through a deprecation period, or what?
msg236653 - (view) Author: Demian Brecht (demian.brecht) * (Python triager) Date: 2015-02-26 07:44
> Oddly, memoryview accepts keyword arguments (for its one required value), and the name of the argument is "object", not "obj".

Positional parameters can also be treated as named arguments.

> I think it's plain daft having "object" as a keyword argument.

True, it's not best practice to override builtins with parameter names. In this case because memoryview is implemented in C, it doesn't suffer the same consequences as a Python implementation can. However at the very least, I do agree that it does seem a little odd from a user's standpoint. Also, the docs currently use "obj" rather than "object": https://docs.python.org/3/library/stdtypes.html#memoryview.

I've attached a patch that just changes the name of the parameter. Scanning through Github (primarily numpy and scipy), I wasn't able to find anyone making use of the parameter name.

As this does break backwards compatibility and is more of a cosmetic enhancement than a bug, it should only go into 3.5+.

The other option here, other than to just leave it as is, is to simply use Py_ParseTuple rather than PyArg_ParseTupleAndKeywords, but I'm not sure what the general consensus is on that (it seems to me that the preferred approach is the latter).
msg236973 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2015-03-01 19:13
I agree that "obj" would be nicer.  On the other hand we explicitly
test for "object" in the tests, help(memoryview) says "object" and pypy
accepts "object".

Also, I think there may be other instances in the tree where reserved
names are used for parameters.
msg267041 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-06-03 05:17
I think the safest solution is to change 'obj' to 'object' in memoryview documentation.
msg267082 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-06-03 09:10
Or pretend in the documentation that it's a positional arg and make it one later. There is a slight performance difference.

I agree with Damien that probably no one uses the keyword arg.
msg267083 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-06-03 09:11
Sorry, I meant *Demian*.
History
Date User Action Args
2016-06-03 09:11:04skrahsetmessages: + msg267083
2016-06-03 09:10:12skrahsetmessages: + msg267082
2016-06-03 08:55:49BreamoreBoysetnosy: - BreamoreBoy
2016-06-03 05:17:12berker.peksagsetassignee: docs@python
components: + Documentation, - Interpreter Core
versions: + Python 3.6
keywords: + easy
nosy: + berker.peksag, docs@python

messages: + msg267041
stage: patch review -> needs patch
2015-03-01 19:13:55skrahsetnosy: + skrah
messages: + msg236973
2015-02-26 07:44:20demian.brechtsetfiles: + issue20408.patch

components: + Interpreter Core
versions: - Python 3.4
keywords: + patch
nosy: + demian.brecht

messages: + msg236653
stage: needs patch -> patch review
2015-02-26 01:42:50BreamoreBoysetnosy: + BreamoreBoy

messages: + msg236641
versions: + Python 3.5, - Python 3.3
2014-01-27 11:53:11larrycreate