On Tue, Feb 21, 2012 at 1:55 AM, �<martin@v.loewis.de> wrote:
>> Basically, if something is just documented as being callable without
>> subclassing or instance checks being mentioned as supported in the
>> docs, it can be implemented as either a type or an ordinary function,
>> or pretty much any other kind of callable without being deemed an API
>> change
>
>
> So what would be your evaluation of
>
> http://docs.python.org/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element
>
> in that respect?

Completely different from the functools.partial case - with that, the
docs are very careful to *never* call functools.partial a class
(instead saying "returns a callable object").

The ElementTree docs unambiguously call Element a class (several
times), so a conforming implementation must provide it as a class
(i.e. supporting use in isinstance() checks. inheritance, etc) rather
than as just a callable. A factory function is not a backwards
compatible replacement (sorry Eli - given those docs, I'm definitely
with Martin on this one).

No need to be sorry :-) I don't think my view differs from Martin's here, by the way. My point is just that this isn't a regression, since "use cElementTree" is ubiquitous advice, and the C implementation has Element as a factory function and not a class, so the documentation wasn't correct to begin with. So the documentation isn't correct for previous versions any way you look at it. There's a conflict in that it says Element is a class and also that cElementTree implements the same API.
">

(original) (raw)



On Tue, Feb 21, 2012 at 00:51, Nick Coghlan <ncoghlan@gmail.com> wrote:

On Tue, Feb 21, 2012 at 1:55 AM, �<martin@v.loewis.de> wrote:
>> Basically, if something is just documented as being callable without
>> subclassing or instance checks being mentioned as supported in the
>> docs, it can be implemented as either a type or an ordinary function,
>> or pretty much any other kind of callable without being deemed an API
>> change
>
>
> So what would be your evaluation of
>
> http://docs.python.org/library/xml.etree.elementtree.html#xml.etree.ElementTree.Element
>
> in that respect?

Completely different from the functools.partial case - with that, the
docs are very careful to \*never\* call functools.partial a class
(instead saying "returns a callable object").

The ElementTree docs unambiguously call Element a class (several
times), so a conforming implementation must provide it as a class
(i.e. supporting use in isinstance() checks. inheritance, etc) rather
than as just a callable. A factory function is not a backwards
compatible replacement (sorry Eli - given those docs, I'm definitely
with Martin on this one).

No need to be sorry :-) I don't think my view differs from Martin's here, by the way. My point is just that this isn't a regression, since "use cElementTree" is ubiquitous advice, and the C implementation has Element as a factory function and not a class, so the documentation wasn't correct to begin with. So the documentation isn't correct for previous versions any way you look at it. There's a conflict in that it says Element is a class and also that cElementTree implements the same API.


So the two choices here are either change the documentation or the C implementation to actually make Element a class. The first is of course simpler. However, someone somewhere may have written code that knowingly forces the Python implementation to be used and subclasses Element. Such code will break in 3.3, so it probably makes sense to invest in making Element a class in the C implementation as well.


Eli