Message121321
On Tue, Nov 16, 2010 at 10:38 AM, M.-A. Lemburg <mal@egenix.com> 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. |
|
Date |
User |
Action |
Args |
2010-11-16 22:17:59 | belopolsky | set | recipients:
+ belopolsky |
2010-11-16 22:17:59 | belopolsky | set | messageid: <1289945879.38.0.0118044311053.issue10435@psf.upfronthosting.co.za> |
2010-11-16 22:17:57 | belopolsky | link | issue10435 messages |
2010-11-16 22:17:56 | belopolsky | create | |
|