Clean Singleton Docstrings

[Peter Otten]

Rob Gaddi wrote:

> I've got a package that contains a global ensmartened dict that allows
> all the various parts of my program to share state.  Things like device
> handles, information about the application environment, etc. that are
> inherantly global (i.e. we're not having that debate).
> 
> Implementation is:
> 
>   class _Registry(UserDict):
>     """Docstring!"""
>     ...
>   Registry = _Registry()
> 
> So Registry is now a globally accessible mutable object; no reason to
> complicate things with singletons or borgs or whathave you. From
> within the interactive console, help(foobar.Registry) gives me the
> _Registry documentation as expected.
> 
> From the (Linux) command line though:
>   $ pydoc3 foobar._Registry
>     [lots of good documentation stuff]
>   $ pydoc3 foobar.Registry
>   no Python documentation found for 'foobar.Registry'
> 
> Is this a thing that can be fixed with a commensurate amount of effort?

There is a test

if not object:
    raise ImportError('no Python documentation found for %r' % thing)

in the pydoc module. So all you need is to ensure that your Registry 
evaluates to True in a boolean context, e. g. by putting something into it: 

$ cat foobar.py
from collections import UserDict

class _Registry(UserDict):
    """Docstring!"""

Registry = _Registry()
Registry["dummy"] = 42
$ pydoc3 foobar.Registry | head -n 10
Help on _Registry in foobar object:

foobar.Registry = class _Registry(collections.UserDict)
 |  Docstring!
 |  
 |  Method resolution order:
 |      _Registry
 |      collections.UserDict
 |      collections.abc.MutableMapping
 |      collections.abc.Mapping

You might also file a bug report asking to replace

if not object: ...

with 

if object is None: ...