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

M.-A. Lemburg mal at egenix.com
Tue Nov 16 16:38:04 CET 2010

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.

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: PyUnicodeGetMax PyUnicodeResize (*) PyUnicodeInternImmortal PyUnicodeFromOrdinal (*) PyUnicodeGetDefaultEncoding (D) PyUnicodeAsDecodedObject PyUnicodeAsDecodedUnicode PyUnicodeAsEncodedObject PyUnicodeAsEncodedUnicode PyUnicodeBuildEncodingMap PyUnicodeEncodeDecimal (*) PyUnicodeAppend (*) PyUnicodeAppendAndDel (*) PyUnicodePartition (*) PyUnicodeRPartition (*) PyUnicodeRSplit (*) PyUnicodeIsIdentifier (*) PyUNICODEstrlen PyUNICODEstrcpy PyUNICODEstrcat PyUNICODEstrncpy PyUNICODEstrcmp PyUNICODEstrncmp PyUNICODEstrchr PyUNICODEstrrchr

For Unicode, unicodeobject.h defines which APIs are private or not. APIs which don't appear in the header file are either private or need to be added to the header file (but I don't think there are any in this category).

All APIs in the header that do not appear in the documentation, should be added there as well. unicodeobject.h already provides documentation for most of the APIs you've listed above (except some new ones that were added later on).

One API I'm not sure about is PyUnicode_AppendAndDel(). It's somewhat obscure and given that we already have PyUnicode_Concat(), I think it should be made private and eventually dropped.

-- Marc-Andre Lemburg eGenix.com

Professional Python Services directly from the Source (#1, Nov 16 2010)

Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/

::: Try our new mxODBC.Connect Python Database Interface for free ! ::::

eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611 http://www.egenix.com/company/contact/

More information about the Python-Dev mailing list