classification
Title: Curses.wrapper: documentation/implementation error
Type: Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.1, Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Radiant, akuchling, docs@python, july, python-dev, steve21
Priority: normal Keywords: patch

Created on 2009-08-24 07:33 by steve21, last changed 2011-06-19 00:22 by r.david.murray. This issue is now closed.

Files
File name Uploaded Description Edit
curses-wrapper-doc.patch july, 2010-05-31 17:14
Messages (6)
msg91903 - (view) Author: Steve (steve21) Date: 2009-08-24 07:33
The documentation and implementation disagree.

Documentation:
"Module curses.wrapper
    Convenience function to ensure proper terminal setup and resetting
on application entry and exit.
...

15.10. curses.wrapper — Terminal handler for curses programs

This module supplies one function, wrapper() ...

curses.wrapper.wrapper(func, ...)
    Wrapper function that initializes curses ..
"

Implementation:
$ python3.1
Python 3.1.1 (r311:74480, Aug 24 2009, 14:50:57)
[GCC 4.4.0 20090506 (Red Hat 4.4.0-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import curses.wrapper as cw
>>> cw.wrapper
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'function' object has no attribute 'wrapper'


The 'curses.wrapper.wrapper' function no longer exists.
The 'curses.wrapper' module no longer exists, the module is now a function.

The problem is the line
  from curses.wrapper import wrapper
in curses/__init__.py - curses has clobbered its own namespace and made
the curses.wrapper module inaccessible.

Instead of this tortuous sequence of module hiding and namespace
clobbering it would be simpler to just place the curses.wrapper.wrapper
function in curses/__init__.py and do away with the need for the
curses.wrapper single-function-module.
And update the docs so:
  references to the curses.wrapper module are removed
  the function curses.wrapper.wrapper(func, ...) becomes
               curses.wrapper.(func, ...)
msg99767 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2010-02-22 16:05
Yes, it seems like a sensible change to just get rid of the curses/wrapper.py module; the code's not that big, and we're importing it anyway.
msg106796 - (view) Author: July Tikhonov (july) * Date: 2010-05-31 17:14
I think, since curses.wrapper is actually a function (and module named curses.wrapper cannot be trivially accessed), we can just modify docs, stripping out any mentions of module, instead documenting the function.

We can leave the module 'curses.wrapper' and line 'from curses.wrapper import wrapper' in its current state, as implementation detail.

Also, this is not backward incompatible in any case.

Patch added.
msg126305 - (view) Author: Radiant (Radiant) Date: 2011-01-14 23:46
Adding version=3.2 and component=Documentation.
msg138621 - (view) Author: Roundup Robot (python-dev) Date: 2011-06-18 23:42
New changeset dc78ab3f7bc5 by R David Murray in branch '2.7':
#6771: fix docs: curses.wrapper is exposed as a function, not a module
http://hg.python.org/cpython/rev/dc78ab3f7bc5

New changeset f9b4cfc19264 by R David Murray in branch '3.2':
#6771: fix docs: curses.wrapper is exposed as a function, not a module
http://hg.python.org/cpython/rev/f9b4cfc19264

New changeset bb5e950ebb04 by R David Murray in branch 'default':
merge #6771: fix docs: curses.wrapper is exposed as a function, not a module
http://hg.python.org/cpython/rev/bb5e950ebb04
msg138622 - (view) Author: Roundup Robot (python-dev) Date: 2011-06-19 00:21
New changeset 9c96c3adbcd1 by R David Murray in branch 'default':
#6771: Move wrapper function into __init__ and eliminate wrapper module
http://hg.python.org/cpython/rev/9c96c3adbcd1
History
Date User Action Args
2011-06-19 00:22:09r.david.murraysetstatus: open -> closed
resolution: fixed
stage: resolved
2011-06-19 00:21:30python-devsetmessages: + msg138622
2011-06-18 23:42:46python-devsetnosy: + python-dev
messages: + msg138621
2011-01-14 23:46:46Radiantsetversions: + Python 3.2
nosy: + docs@python, Radiant

messages: + msg126305

assignee: docs@python
components: + Documentation
2010-05-31 17:14:54julysetfiles: + curses-wrapper-doc.patch

nosy: + july
messages: + msg106796

keywords: + patch
2010-02-22 16:05:47akuchlingsetnosy: + akuchling
messages: + msg99767
2009-08-28 20:15:08terry.reedysettitle: documentation/implementation error -> Curses.wrapper: documentation/implementation error
2009-08-24 07:33:54steve21create