When using binascii.a2b_hex (or binascii.unhexlify) and the argument is invalid, the doc states that it should raise a TypeError for invalid arguments (e.g. passing an odd-length string).

However, it does raise binascii.Error instead of TypeError:

try:
    binascii.a2b_hex('a')
except Exception as exc:
    print(type(exc))

When using binascii.a2b_hex (or binascii.unhexlify) and the argument is invalid, the doc states that it should raise a TypeError for invalid arguments (e.g. passing an odd-length string).

However, it does raise binascii.Error instead of TypeError:

try:
    binascii.a2b_hex('a')
except Exception as exc:
    print(type(exc))

What surprised me even more was that it raises ValueError (although binascii.Error inherits ValueError) in case a unicode string has been passed as an argument:

try:
    binascii.a2b_hex('ä')
except binascii.Error:
    print('binascii.Error')
except ValueError:
    print('ValueError')

In Python 3.x, 'a' is just as much a Unicode string as 'ä'. I agree that binascii.a2b_hex should raise ValueError for argument 'ä', or ';' for that matter, as they are invalid values. There's an inconsistency in why some invalid characters raise ValueError and some raise binascii.Error. But since binascii.Error is a subclass of ValueError, it probably doesn't matter that much, so long as the documentation is clear.

binascii.Error is used throughout the module for most of the validations, with only a few of them using TypeError/ValueError. I guess it would make more sense to update these to raise binascii.Error (unless they were left on purpose) to make it consistent with the rest of the module, although changing from TypeError to binascii.Error might break existing code.

Anyway, since a2b_hex is currently raising binascii.Error for an odd-length input, the attached patch fixes the documentation to reflect it.

The TypeError → binascii.Error changeover was made in revision eb45f85c4c79, to this function, along with various decoding functions in the base64 module. The base64 documenation was only slowly updated in a series of bug fixes, and it looks like unhexlify() is the only one left.

At the top of the binascii documentation, it says that the decoding functions accept ASCII strings. The general check for non-ASCII code points (raising ValueError) would be done before the specific checks for hexadecimal digits and having the right length.

Luiz’s patch looks okay to me.

New changeset ef89ecb6debc by Martin Panter in branch '3.5':
Issue #27124: Fix documentation of exception raised by a2b_hex()
https://hg.python.org/cpython/rev/ef89ecb6debc

New changeset 85e6da63d73f by Martin Panter in branch 'default':
Issue #27124: Merge binascii doc from 3.5
https://hg.python.org/cpython/rev/85e6da63d73f