On 11/08/2010 01:58 PM, Brett Cannon wrote:
On Mon, Nov 8, 2010 at 09:20, Alexander Belopolsky
<belopol...@users.sourceforge.net> wrote:
Was: [issue2001] Pydoc interactive browsing enhancement
On Sun, Nov 7, 2010 at 9:17 AM, Nick Coghlan<rep...@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__.)
I think we need to, as a group, decide how to handle undocumented APIs
that don't have a leading underscore: they get treated just the same
as the documented APIs, or are they private regardless and thus we can
change them at our whim?
My understanding is that anything with an actual docstring is part of the
public API. Any thing with a leading underscore is private.
And to a lesser extent, objects with out docstrings, but have comments
instead or nothing, may change, so don't depend on them. Thankfully most
things do have docstrings.
I freely admit that I have more questions than answers, so I would
like to hear from a wider audience.
The main reason I have said that non-underscore names should be
properly deprecated (assuming they are not contained in an
underscored-named module) is that dir() and help() do not distinguish.
If you are perusing a module from the interpreter prompt you have no
way to know whether something is public or private if it lacks an
underscore. Is it reasonable to assume that any API found through
dir() or help() must be checked with the official docs before you can
consider using it, even if you have no explicit need to read the
official docs?
I (unfortunately) say no, which is why I have argued that
non-underscored names need to be properly deprecated. This obviously
places a nasty burden on us, though, so I don't like taking this
position. Unless we can make it clearly known through help() or
something that the official docs must be checked to know what can and
cannot be reliably used I don't think it is reasonable to force users
to not be able to rely on help() (we should probably change help() to
print a big disclaimer for anything with a leading underscore,
though).
+1 on the help disclaimer for objects with leading underscores.
Currently help() does not see comments when they are used in place of a
docstring. I think it would be easy to have help notate things with no
docstrings as "Warning: Undocumented <object>. Use at your own risk."
At first, it would probably have a nice side effect of getting any public
API's documented with doc strings. (if they aren't already.)
But that doesn't mean we can't go through, fix up our names, and
deprecate the old public names; that's fair game in my book.
I agree.
It may also be useful to clarify that importing some "utility" modules is
not recommended because they may be changed more often and may not follow
the standard process. Would something like the following work, but still
allow for importing if the exception is caught with a try except?
if __name__ == "__main__":
main()
else:
raise ImportWarning("This is utility module and may be changed.")
Cheers,
Ron
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
