[Python-Dev] r84430 - in python/branches/py3k: Include/unicodeobject.h Objects/unicodeobject.c

[M.-A. Lemburg]

Victor Stinner wrote:
> Hi,
> 
> Le jeudi 02 septembre 2010 11:13:22, vous avez écrit :
>>> 1. This function and PyUnicode_strcat are missing documentation.
> 
> It's Py_UNICODE_strcat(), not PyUnicode_strcat(). But yes, Py_UNICODE_strcat() 
> is not documented. But I didn't found any doc for other Py_UNICODE_str*() 
> functions in Doc/c-api/*.rst. Does it mean that we should write a document for 
> all these functions? They mimic the str*() C API.
> 
> If PyUnicode_strdup() is kept public, it should be documented, yes.

As for naming, I think Py_UNICODE_strdup() is fine, since these
functions work directly on Py_UNICODE buffers and they mimic
the C functions.

They should be documented, though, even if the documentation is
terse and refers to the C API of a similar name.

> --
> 
>> If you want to make this a public API function, it also needs to be
>> renamed to fit the rest of the API.
> 
> PyUnicode_strdup(): I don't like this name. In my first patch, it was called 
> Py_UNICODE_strdup() but all Py_UNICODE_*() functions take Py_UNICODE* 
> arguments, no PyUnicodeObject* argument.

See above: the current naming is fine.

>> I'd suggest PyUnicode_AsUnicodeCopy() which then corresponds
>> to PyUnicode_FromUnicode(), but I'm not sure whether we should
>> have such a public API in the first place.
> 
> PyUnicode_AsUnicodeCopy() is maybe a better name, I like it.

For APIs that work on PyUnicodeObjects, we should stick to the
naming convention used by the Unicode and string/bytes API.
It's a little more verbose, but also provides more clarity
than the C API function names.

> --
> 
>> What are they going to be used for?
> 
> I am not able to merge my huge work on unicode import (see #8611, #9425 and 
> the "import_unicode" svn branch) at once, so I'm splitting it into atomic 
> commits. PyUnicode_strdup() and Py_UNICODE_strcat() are not used yet, but I 
> plan to use them for the import machinery (Python/import.c) to replace char* 
> by Py_UNICODE*.
> 
>>> 2. Are you sure they need to be public APIs?
> 
> About Py_UNICODE_strcat(): yes, why not? Other Py_UNICODE_str*() functions are 
> pratical but also required to manipulate Py_UNICODE* strings.
>
> About PyUnicode_strdup() (PyUnicode_AsUnicodeCopy): I don't know. It is 
> possible to rewrite it in few lines. Why don't you want to add them to the 
> public API? For my work, it doesn't matter if it's public or not. This 
> function uses PyMem_xxx API, I don't know if a third part library would like 
> to rely on PyMem_xxx.

This will have to be documented (see PEP 384 for some reasoning on
malloc() use in DLLs).

Other than that, ok, let's have them. They do provide some use to
other tools working on Py_UNICODE, just like the macros we
have for these.

-- 
Marc-Andre Lemburg
eGenix.com

Professional Python Services directly from the Source  (#1, Sep 03 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/
________________________________________________________________________
2010-08-19: Released mxODBC 3.1.0              http://python.egenix.com/
2010-09-15: DZUG Tagung, Dresden, Germany                  11 days to go

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