What this thread has shown is that there is no consensus on what public names are and what rules should be followed when changing names that can be imported from a module. I have opened an issue at http://bugs.python.org/issue10434 to address this. My vote is to adopt the definition spelled out in the language reference, copy it to the library manual and add some discussion of the deprecation policies.
I also have a similar question about C API. Here, in absence of __all__, the answer should be clear: all symbols in public header files should start with either _Py_ or Py_ and those that start with Py_ are public. The question is what should be done with names that start with Py_, but are not documented? Can we add an underscore to those names? If so, should a (deprecated) alias be made available? Should they be documented as deprecated? I think these questions can only be answered on a case by case bases which choices being: 1. Document. 2. Document as deprecated. 3. Document as deprecated, add underscore prefix and retain a deprecated alias. 4. Add an underscore prefix. The specific set of names that I would like to consider is the following from unicode.h. I am marking with (*) the names that I think should be documented and with (D) those that should be deprecated: PyUnicode_GetMax PyUnicode_Resize (*) PyUnicode_InternImmortal PyUnicode_FromOrdinal (*) PyUnicode_GetDefaultEncoding (D) PyUnicode_AsDecodedObject PyUnicode_AsDecodedUnicode PyUnicode_AsEncodedObject PyUnicode_AsEncodedUnicode PyUnicode_BuildEncodingMap PyUnicode_EncodeDecimal (*) PyUnicode_Append (*) PyUnicode_AppendAndDel (*) PyUnicode_Partition (*) PyUnicode_RPartition (*) PyUnicode_RSplit (*) PyUnicode_IsIdentifier (*) Py_UNICODE_strlen Py_UNICODE_strcpy Py_UNICODE_strcat Py_UNICODE_strncpy Py_UNICODE_strcmp Py_UNICODE_strncmp Py_UNICODE_strchr Py_UNICODE_strrchr On Sat, Nov 13, 2010 at 7:12 AM, Giampaolo Rodolà <g.rod...@gmail.com> wrote: > +1 on everything. > > 2010/11/11 Alexander Belopolsky <alexander.belopol...@gmail.com>: >> 2010/11/11 Michael Foord <fuzzy...@voidspace.org.uk>: >> .. >>>> You mean runtime automation, e.g. creating __all__ on the fly omitting >>>> underscored names? >>>> >>> Writing code to generate a __all__ that duplicates the default behaviour >>> seems redundant to me. >>> >> >> FWIW, I like having __all__ at the top of the module. It feels like a >> table of contents at the start of a chapter. In some cases it may >> also serve as an optimization when len(__all__) is much smaller than >> len(__dict__). I also don't like _ prefix to become an exclusive >> means to express privateness. >> >> I think the current definition of "public names" is a good one and >> just needs to be made more visible in the docs. If the module defines >> __all__, that should be the ultimate answer to what is public in that >> module. (Users should learn to use help(module) instead of >> dir(module) for API discovery.) If __all__ is not defined in the >> module, I think it is good to introduce it after a careful review of >> what it should contain. And __all__ should never contain names that >> start with _. >> _______________________________________________ >> 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/g.rodola%40gmail.com >> > _______________________________________________ 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