Python2 documentation of the open() built-in function

[jannkruse]

BPO	12642
Nosy	@ezio-melotti, @bitdancer

^{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 2011-07-27.05:50:30.896>
created_at = <Date 2011-07-26.21:20:19.232>
labels = ['type-bug', 'docs']
title = 'Python2 documentation of the  open()  built-in function'
updated_at = <Date 2011-07-27.05:50:30.880>
user = 'https://bugs.python.org/jannkruse'

bugs.python.org fields:

activity = <Date 2011-07-27.05:50:30.880>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-07-27.05:50:30.896>
closer = 'ezio.melotti'
components = ['Documentation']
creation = <Date 2011-07-26.21:20:19.232>
creator = 'jannkruse'
dependencies = []
files = []
hgrepos = []
issue_num = 12642
keywords = []
message_count = 4.0
messages = ['141183', '141188', '141207', '141208']
nosy_count = 6.0
nosy_names = ['ezio.melotti', 'r.david.murray', 'eli.bendersky', 'docs@python', 'python-dev', 'jannkruse']
pr_nums = []
priority = 'low'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue12642'
versions = ['Python 2.7']

[jannkruse]

The documentation page

http://docs.python.org/release/2.6.6/library/functions.html?highlight=open#open

describes the open() built-in function as

  open(filename[, mode[, bufsize]])

but the Python interpreter complains:

  Python 2.6.6 (r266:84292, Dec 27 2010, 00:02:40) 
  [GCC 4.4.5] on linux2 
  Type "help", "copyright", "credits" or "license" for more information.
  >>> 
  >>> 
  >>> file_descriptor = open(filename='/spam')
  Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
  TypeError: Required argument 'name' (pos 1) not found
  >>> 
  >>> 
  >>> file_descriptor = open(name='/spam', bufsize=-1)
  Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
  TypeError: 'bufsize' is an invalid keyword argument for this function
  >>> 
  >>> 
  >>> file_descriptor = open(name='/spam', buffering=-1)
  Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
  IOError: [Errno 2] No such file or directory: '/spam'
  >>> _
  

So the documentation page should read

  open(name[, mode[, buffering]])
       ----          

---

instead, note 'name' not 'filename' and 'buffering' not 'bufsize'.

Maybe it's relevant, because Debian/stable still ships with
Python 2.6.6 and I guess the Python 2.7.x documentation has
the same bug.

The """docstring""" does already reflect that correctly.

PS:
This is my first bug report. I hope I did this right.
Mercy, please! ;)

[bitdancer]

The docs are correct in Python3.

The docs for Python2 are not *wrong*, since they indicate only positional parameters and if you use positional parameters it works as documented. (I'm surprised that using keyword arguments works, but I haven't looked at the code.) Fixing the names in the 2.7 docs would still be helpful (2.6 docs don't get updated any more).

[python-dev]

New changeset 5da7924c4775 by Ezio Melotti in branch '2.7':
bpo-12642: fix args names in open() doc.
http://hg.python.org/cpython/rev/5da7924c4775

[ezio-melotti]

Fixed, thanks for the report!