[Python-Dev] Breaking undocumented API

[Alexander Belopolsky]

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.rodola at gmail.com> wrote:
> +1 on everything.
>
> 2010/11/11 Alexander Belopolsky <alexander.belopolsky at gmail.com>:
>> 2010/11/11 Michael Foord <fuzzyman at 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 at python.org
>> http://mail.python.org/mailman/listinfo/python-dev
>> Unsubscribe: http://mail.python.org/mailman/options/python-dev/g.rodola%40gmail.com
>>
>