Path: csiph.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: Peter Otten <__peter__@web.de>
Newsgroups: comp.lang.python
Subject: Re: Clean Singleton Docstrings
Date: Fri, 08 Jul 2016 09:38:29 +0200
Organization: None
Lines: 63
Message-ID: <mailman.137.1467963521.2295.python-list@python.org>
References: <nlmpl5$9l4$1@dont-email.me> <nlnl9m$j3b$1@ger.gmane.org>
Mime-Version: 1.0
Content-Type: text/plain; charset="ISO-8859-1"
Content-Transfer-Encoding: 7Bit
User-Agent: KNode/4.13.3
Precedence: list
Xref: csiph.com comp.lang.python:111202

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: ...