[Python-Dev] API bloat

[Mark Shannon]

<snip>
>> And the following were added to 3.2,
>> of which only 2 are documented:
>>
>> PyArg_ValidateKeywordArguments
>> PyAST_CompileEx
>> Py_CompileString
>> Py_CompileStringExFlags
>> PyErr_NewExceptionWithDoc    (documented)
>> PyErr_SyntaxLocationEx
>> PyErr_WarnFormat
>> PyFrame_GetLineNumber
>> PyImport_ExecCodeModuleWithPathnames
>> PyImport_GetMagicTag
>> PyLong_AsLongLongAndOverflow    (documented)
>> PyModule_GetFilenameObject
>> Py_SetPath
>> PyStructSequence_GetItem
>> PyStructSequence_NewType
>> PyStructSequence_SetItem
>> PySys_AddWarnOptionUnicode
>> PySys_AddXOption
>> PySys_FormatStderr
>> PySys_FormatStdout
>> PySys_GetXOptions
>> PyThread_acquire_lock_timed
>> PyType_FromSpec
>> PyUnicode_AsUnicodeCopy
>> PyUnicode_AsWideCharString
>> PyUnicode_EncodeFSDefault
>> PyUnicode_FSDecoder
>> Py_UNICODE_strcat
>> Py_UNICODE_strncmp
>> Py_UNICODE_strrchr
>> PyUnicode_TransformDecimalToASCII
>>
>> For added confusion PySys_SetArgvEx is documented as
>> new in 3.2, but exists in 3.1.3
>>
>> That should keep someone busy ;)
>>
>> Note that this only include functions.
>> The API also includes a number of macros such as
>> Py_False and Py_RETURN_FALSE, types ,
>> and data like PyBool_Type.
>>
>> I've not tried to analyse any of these.
> 
> Thanks.
> 
> I opened http://bugs.python.org/issue11173 for this.
> 

Please, don't just document all these.
Don't add them to the API, unless they are really needed.

For example,
PySys_FormatStdout and PySys_FormatStderr
get exactly zero hits between them on google code search.
PySys_FormatStdout doesn't even get used in the 3.2 source.

I'm not picking on PySys_FormatStderr, or its author here,
I'm just using it as an example, it seems fairly typical.

According to http://bugs.python.org/issue9599
"I only need PySys_FormatStderr(), but I added also PySys_FormatStdout() 
just to be consistent with PySys_Write*() and because it only costs a 
few line of code."

This seems a little cavalier to me.
That little PyAPI_FUNC() macro carries a lot of obligation in terms of
documentation, future support, and the cost to other implementations.

Cheers,
Mark.