[Python-Dev] Breaking undocumented API (original) (raw)

Terry Reedy tjreedy at udel.edu
Mon Nov 8 19:12:18 CET 2010

On 11/8/2010 12:20 PM, Alexander Belopolsky wrote:

Was: [issue2001] Pydoc interactive browsing enhancement

On Sun, Nov 7, 2010 at 9:17 AM, Nick Coghlan<report at bugs.python.org> wrote: ..

I'd actually started typing out the command to commit this before it finally clicked that the patch changes public APIs of the pydoc module in incompatible ways. Sure, they aren't documented, but the fact they aren't protected by an underscore means I'm not comfortable with the idea of removing them or radically change their functionality without going through a deprecation period first. I have a similar issue with the trace module and would appreciate some guidance on this as well. The trace module documented API includes just the Trace class, but the module defines several helper functions and classes that do not start with a leading underscore and are not excluded from * imports by all. (There is no trace.all.)

The trace module appears to be an ancient module written at a time (fictional or actual) when there was no '_' and 'all' convention and only a loose 'public' == documented convention. The undocumented public-looking private stuff is a huge mess that Eli and I intentionally passed over in our July/August patch documenting (and fixing) the public stuff. I hope we included everything that should be public.

In order to warn about constants getting renamed or moved, is it possible to issue an off-by-default warning on module import, something like "Trace is an ancient module with public names for many undocumented private constants and functions. Use of these is deprecated. See lib doc for more."

-- Terry Jan Reedy

More information about the Python-Dev mailing list