Incorrect type names in docstrings for nested types

[jondreads]

Issue description

I have an inner enum. The type name for the enum in docstrings is not correct. I'm not sure if this is a bug in docstring generation, but I can't see any documentation on how to supply the correct name.

Reproducible example code

#include <pybind11/pybind11.h>
namespace py = pybind11;
struct Pet
{
  enum class Kind { Dog };
  Pet() : type(Kind::Dog) {}
  Kind type;
};
void foo(Pet::Kind) {}
PYBIND11_MODULE (hello, m)
{
  py::class_<Pet> pet(m, "Pet");
  pet.def(py::init())
    .def_readwrite("type", &Pet::type);
  py::enum_<Pet::Kind>(pet, "Kind")
    .value("Dog", Pet::Kind::Dog);
  m.def("foo", &foo);
}

In python

>>> import hello
>>> hello.foo.__doc__
'foo(arg0: hello.Kind) -> None\n'
>>> help(hello.Pet.Kind)
Help on class Kind in module hello:
class Kind(pybind11_builtins.pybind11_object)
...
 |  __eq__(...)
 |      __eq__(self: hello.Kind, arg0: hello.Kind) -> bool
...

I would expect to see "hello.Pet.Kind" in the docstrings not "hello.Kind"

[wjakob]

Which version of Python are you using? There are some differences here between 2.7 and 3.x

[jondreads]

Python 3.6

[jagerman]

Some thoughts:

For Python 3.3+, this is something we can (and should) address. It isn't specific to enums, though, but rather classes (this shows up for enum_ because it inherits from class_).

The fix is for us to use __qualname__ rather than tp_name when displaying the type in the docstring; that should get us the nested name, e.g. Pet.Kind.

That's an easy enough change, except it exposed something else that doesn't look right: our __qualname__ values contain the module name, which they shouldn't.

E.g. a Python module pymod.py:

def foo():
    pass

class C():
    pass

Python:

Python 3.6.3 (default, Oct  3 2017, 21:16:13) 
[GCC 7.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import pymod
>>> (pymod.foo.__name__, pymod.foo.__module__, pymod.foo.__qualname__)
('foo', 'pymod', 'foo')
>>> (pymod.C.__name__, pymod.C.__module__, pymod.C.__qualname__)
('C', 'pymod', 'C')
>>> (pymod.C.D.__name__, pymod.C.D.__module__, pymod.C.D.__qualname__)
('D', 'pymod', 'C.D')

while the equivalent using pybind11 is incorrectly tacking the module name into the __qualname__:

('D', 'mod', 'mod.C.D')

So this is going to take a bit more than just printing __qualname__ instead of tp_name.

[jagerman]

This should be fixed now on master via #1171.