Alexander Belopolsky <[email protected]> added the comment:
On Tue, Nov 16, 2010 at 10:38 AM, M.-A. Lemburg <[email protected]> wrote: > Alexander Belopolsky wrote: .. >> 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 > > 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. > I would also like to nominate PyUnicode_AsEncodedObject and PyUnicode_AsEncodedUnicode. The later is a particularly attractive candidate for removal because it appears to be broken: v = PyCodec_Encode(unicode, encoding, errors); if (v == NULL) goto onError; if (!PyUnicode_Check(v)) { PyErr_Format(PyExc_TypeError, "encoder did not return an str object (type=%.400s)", Py_TYPE(v)->tp_name); Since PyCodec_Encode() returns bytes in 3.x, the code above will always raise an error. ---------- _______________________________________ Python tracker <[email protected]> <http://bugs.python.org/issue10435> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
