[Python-Dev] API bloat

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

(Not sure if your message went to python-dev too.)

Am 09.02.2011 11:04, schrieb Mark Shannon:
> Georg Brandl wrote:
>> Am 09.02.2011 10:09, schrieb Mark Shannon:
>>> At sometime between versions 3.1 and the current version, 3.1.3,
>>> the API  grew considerably.
>>> See
>>> http://docs.python.org/release/3.1/c-api/exceptions.html#exception-handling
>>> and
>>> http://docs.python.org/py3k/c-api/exceptions.html#exception-handling
>>>
>>> The Unicode Exception Objects section is new and seemingly redundant:
>> 
>> Why redundant?
> 
> Because they are all attribute getter and setters. For example:
> 
> PyUnicodeDecodeError_GetStart(exc, x) <=>
> PyObject_GetAttr(exc, "start", x)
> 
> This sort of redundancy seems sensible for list, tuple and such.
> It just seems like bloat for classes like UnicodeDecodeError.

Have you looked at the implementation?  They do some more, e.g. make sure the
returned value is within the boundaries of the offending string.  (Yes, that
probably should be in the docs too.)

>>> http://docs.python.org/py3k/c-api/exceptions.html#unicode-exception-objects
>>> Should this be in the public API?
>> 
>> While this question is valid, it *should* have been asked 8 years ago, when
>> the functions were actually added.
> 
> The functions may have been add to CPython 8 years ago, but they were 
> added to the API when they appeared in the docs, between 3.1 and 3.1.3.
>
> How is the API defined, if not by the documentation?
> The header files do not specify what is API and what is implementation 
> specific.

The API is defined by all functions (and macros, and types) defined by the
headers starting with a "Py" prefix.  Implementation specific functions have
a "_Py" prefix.

- From 3.2, we also have a "Limited API" (see PEP 384) that defines a set of
API that will not change, and is guaranteed to have a consistent ABI between
Python minor versions.

>>> Could the API be reverted to the 3.1 version plus any *necessary* 
>>> changes in time for the 3.2 release?
>> 
>> Any changes in API are definitely forbidden before 3.2.
> 
> If that is the case then the API, as defined by
> http://docs.python.org/py3k/c-api/index.html
> should be same for 3.2 as for 3.1, plus a few functions,
> that are explicitly marked as "New in version 3.2".
> 
> Unfortunately, that is not currently the case.

In any case, these are doc bugs.  In the past, many additions to the C API
were made without proper documentation changes, and we are still working
to clean this up.

So, yes: modulo doc bugs, any function that newly appears in the 3.2 docs
either has a "New in version 3.2" tag, or has been present in 3.1 already.

Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iEYEARECAAYFAk1ScT4ACgkQN9GcIYhpnLDEjwCggMLnpWoeL7Vpg3SiZlfJvJ0H
2isAn0hhBmbUelr4Of+kAqPopWc5s5ro
=xYhv
-----END PGP SIGNATURE-----