[Python-Dev] API bloat

[Antoine Pitrou]

On Wed, 09 Feb 2011 10:37:11 +0000
Mark Shannon <marks at dcs.gla.ac.uk> wrote:
> > 
> > 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.

It's not exactly the same thing, still. PyObject_GetAttr()
will do a full blown attribute access, while I guess (I didn't check) 
PyUnicodeDecodeError_GetStart() accesses the C struct member directly.

Also, the latter gives you a Py_ssize_t object, which relieves you from
having to do a conversion explicitly.

I do agree that it doesn't seem widely used, according to Google Code
Search :)

> >> 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.

True. But if they were added to the documentation, it's certainly
because they were *intended* to be part of the API from the start.
(after all, core CPython code can just access the C struct fields
directly rather than go through a function call)

Take it as acknowledging that it has *always* been part of the intended
API.

These days, we try to follow a stricter naming convention: when we want
an API to remain explicitly private, we often prefix it with an
underscore. But that has not been the case in the past, I admit.

> > 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.

How so? Can you give an example?

Regards

Antoine.