[Python-Dev] cpython: Document PyUnicode_Copy() and PyUnicode_EncodeCodePage()

["Martin v. Löwis"]

Am 09.12.2011 10:12, schrieb Nick Coghlan:
> On Fri, Dec 9, 2011 at 6:44 PM, "Martin v. Löwis" <martin at v.loewis.de> wrote:
>> Am 09.12.2011 01:35, schrieb Antoine Pitrou:
>>> On Fri, 09 Dec 2011 00:16:02 +0100
>>> victor.stinner <python-checkins at python.org> wrote:
>>>>
>>>> +.. c:function:: PyObject* PyUnicode_Copy(PyObject *unicode)
>>>> +
>>>> +   Get a new copy of a Unicode object.
>>>> +
>>>> +   .. versionadded:: 3.3
>>>
>>> I'm not sure I understand. Why would you make a copy of an immutable
>>> object?
>>
>> It can convert a unicode subtype object into a an exact unicode
>> object.
>>
>> I'd rename it to _PyUnicode_AsExactUnicode, and undocument it.
> 
> Isn't it basically just exposing a C level version of the unicode()
> builtin's behaviour?

No. To call the unicode() builtin, do

  PyObject_CallFunction(&PyUnicode_Type, "O", param)

or some such. PyUnicode_Copy doesn't correspond to any Python-level
API.

> While I agree the name could be better (and
> PyUnicode_AsExactUnicode would certainly work), why make it private?

I suggest to be minimalistic in extensions to the API. There should
be a demonstrated need for an API before adding it, which I don't
see in this case.

In general, it will be difficult to find a demonstrable need for new
APIs, since the majority (more than 99%) of API use cases is already
covered by the abstract object API (i.e. what ceval uses).

The unicode type in particular has a bad tradition of adding tons
of function to the C API, only so we find out a few releases later
that the API is obsolete (e.g. needs additional/different parameters),
so we carry unused functions around just because some extension module
may use them.

Regards,
Martin