Why can't byte strings be used as Docstrings?

Question

Why is it that byte strings b'string' cannot be used as docstrings for classes or functions (and by extent I'm guessing modules)?

Case in point:

>>> class Foo:
...     b"""My Foo class for Fooing"""
>>> Foo.__doc__ is None
True

Similarly with functions.

For r'', u'' (expected) strings it works okay. I couldn't find anything in the documentation either. Any idea why this is?

Answer 1

As pointed out by @IgnacioVazquez-Abrams, b'string' is not text, or more specifically it is not a string, it is a bytes object, and I don't think you will see these referred to as "byte strings" anywhere in the Python documentation (though I could be wrong); in fact this sounds like a contradiction to me personally.

On the other hand, r'' and u'', and '' are strings (raw string literals, Unicode string literals, and string literals respectively). The first sentence for the spec for docstrings states:

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

It also specifies:

Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

This might not be a satisfying answer since it doesn't explain the internals of why __doc__ in one case will return a string and in the other return None, or how docstrings are formed/parsed. However, I think what is happening is that you are getting None because you just haven't defined a docstring, but only a bytes object which you have not assigned to any variable in your class. The same thing will happen if you do:

class Foo:
    1

1 is not being parsed as the docstring (or the __doc__ attribute) of the class since it is not a string, and I think the same happens with the bytes literal in your example. Regardless, I think the documentation makes it clear that only "strings" can be used as docstrings, so it seems logical that bytes objects would make just as poor docstrings as an int or a bool, or any other non-string datatype. I can understand your curiosity however, especially since the byte literals and string literals are so visually similar.

tl;dr:

Bytes objects are not strings, and only strings can be used for Python docstrings.