[Python-Dev] Breaking undocumented API

[Michael Foord]

On 16/11/2010 15:16, Alexander Belopolsky wrote:
> 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.
>

Whilst the definition in the reference manual is fine it only covers 
module level public APIs (which I realise is your particular concern) it 
doesn't cover whether a module in a package is public and doesn't cover 
class members. The rules for these follow as a natural extension, but if 
we are going to bother codifying the rules (which I think is good given 
the confusion) then it is worth covering these cases.

I posted a suggested wording in an earlier message:

http://mail.python.org/pipermail/python-dev/2010-November/105476.html

We could also note that existing modules that don't follow these rules 
will generally follow the deprecation rules for "accidentally public" 
names, but that this will be decided on a case-by-case basis and that 
names *obviously* never intended to be public may be changed if it is 
believed that they aren't (or really shouldn't be) in use.

All the best,

Michael Foord

> 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
>>>


-- 

http://www.voidspace.org.uk/

READ CAREFULLY. By accepting and reading this email you agree,
on behalf of your employer, to release me from all obligations
and waivers arising from any and all NON-NEGOTIATED agreements,
licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use
policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in
perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me
from any BOGUS AGREEMENTS on behalf of your employer.