issubclass() not as documented

[Skaperen]

classinfo may be a tuple of class objects, in which case every entry in classinfo will be checked. In any other case, a TypeError exception is raised.

What it's saying is that it raises TypeError when you pass it something other than a tuple.
It might not be perfectly clear from that that a single class is also allowed, but it doesn't say an exception is raised unless the condition is true.

i think there is a better way to explain it as what it says right now doesn't do it.

[stranac]

i think there is a better way to explain it as what it says right now doesn't do it.

If you're not happy with the current explanation and can come up with a better one, nothing is stopping you from contributing to the docs.

[perfringo]

This is example where type hints would improve understanding with very little effort:

issubclass(...) -> bool

[ndc85430]

You should also get into the habit of looking at the test cases. Tests are another form of documentation.

[Skaperen]

You should also get into the habit of looking at the test cases. Tests are another form of documentation.

the documentation (i have the PDF) has no reference to test cases from these methods.

[ndc85430]

I don't know why you'd look in a PDF for tests - by "tests", I mean code that executes the functions to make sure their behaviour is correct (in this case, those are unit tests). I haven't seen how the standard library code is organised, but it should be quite easy to find the tests in the repo.

[Skaperen]

I don't know why you'd look in a PDF for tests - by "tests", I mean code that executes the functions to make sure their behaviour is correct (in this case, those are unit tests). I haven't seen how the standard library code is organised, but it should be quite easy to find the tests in the repo.

so basically, this comes down to suggesting that i look a source code to see what it really does? then, what's the point of having documentation?

[nilamo]

I agree with Skaperen here. The docs clearly state that the only result of running issubclass() is either True, or an exception.

Looking at tests to see how internals to Python core work shouldn't (ever) be needed to understand how to use Python, or any library for that matter.

Looking at the source of Python could involve looking at C code, which isn't a viable option for everyone writing Python.

This is a very clear case of the documentation not matching current functionality. Since fixing the bug would involve breaking changes (and returning False to a function who's name clearly indicates it returns a bool), the docs should be updated to more clearly indicate what's actually returned.

Return True if class is a subclass (direct, indirect or virtual) of classinfo. A class is considered a subclass of itself. classinfo may be a tuple of class objects, in which case every entry in classinfo will be checked. In any other case, a TypeError exception is raised.

I don't even see this as a discussion. There's no argument about ambiguous docs, they're just incorrect. Either True is returned, or a TypeError is raised. Any other functionality (such as returning False) is undefined behavior.

[Skaperen]

it's probably just an oversight. i found it because i was spending some time with it, using it in a project (i ended up taking it back out). documentation writers probably would not catch a little thing like this unless there was a change of behavior which would need a rewrite (what they probably spend most of their time on to get the next release out.

[nilamo]

To be fair to Python, though, the interactive docs don't have this ambiguous phrasing, and indicate that it returns a bool (though, there's no mention of any exceptions ever being possible...)

>>> help(issubclass)
Help on built-in function issubclass in module builtins:

issubclass(cls, class_or_tuple, /)
    Return whether 'cls' is a derived from another class or is the same class.

    A tuple, as in ``issubclass(x, (A, B, ...))``, may be given as the target to
    check against. This is equivalent to ``issubclass(x, A) or issubclass(x, B)
    or ...`` etc.