(<type 'int'>, '0755')
(<type 'int'>, '0644')
Traceback (most recent call last):
  File "./tools/bootstrap.py", line 185, in extract_zip
    os.fchmod(outfile, unixperm)
TypeError: an integer is required


Here the integer that is required is not `unixperm`, but `outfile`.

os.chmod is implemented in posixmodule.c and the argument parsing code can be found at http://hg.python.org/cpython/file/3acbb23c73bc/Modules/posixmodule.c#l2605 . You will notice that the argument parsing is specified as "O&i|$O&p". That means the first argument is parsed as a Python object which is passed through a converter function and the second argument is required to be an integer. That converter function can be found at http://hg.python.org/cpython/file/3acbb23c73bc/Modules/posixmodule.c#l681. Looking at that code doesn't suggest that TypeError is raised with that message.

What were the exact arguments you passed into os.chmod() that triggered the exception?

>>> v = open("VERSION")
>>> import os
>>> os.fchmod(v, 0664)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: an integer is required

That's expected with that kind of argument. os.fchmod() and os.chmod() only accept a path as a string or a file descriptor as an integer as specified in the docs: http://docs.python.org/3/library/os.html#os.chmod

Right. This report is about improving error message. It doesn't say what is expected where. If you have a call like:

    os.fchmod(outfile, unixperm)

it is easy to assume that unixperm is not integer, while in fact the problem is in outfile. This could not be actual for Python 3, but it seems that there is bug with it as well.

>>> v = open("VERSION")
>>> import os
>>> os.fchmod(v, 0664)
  File "<stdin>", line 1
    os.fchmod(v, 0664)
                    ^
SyntaxError: invalid token
>>>

That is not a documentation bug (i.e. a problem with what is written at docs.python.org), this is a feature request to try to improve the exception message. That would require adding a new parameter format (http://docs.python.org/3/c-api/arg.html?highlight=pyarg_parse#other-objects) which allows for a converter function which also takes the positional number and/or keyword argument that the converter function was called for.

This is more sophisticated that I thought. Thank for the explanation.

I don't think that a new parameter format is sufficient. For the message in this call the new parameter isn't even needed, you'd "just" have to ensure that enough information is available in convertsimple to create a more useful message.

That said, that is far from a trivial change, more so because the PyArg_Parse family of functions can parse fairly complicated argument structures in one go (such as using ``PyArg_Parse(args, "(si)", &host, port)`` to unpack the tuple in the first (and only) argument).