Docutils: Documentation Utilities

[David Goodger]
> Should we leave a "set_class" method in place, for compatibility?
> It could simply do "self.attributes['classes'].append(...)".
>
> Similarly, the removal of docutils.utils.Reporter.set_conditions
> caused EpyDoc's reST support to break.  Should we put that
> back in, perhaps with a deprecation warning?

Done.

--
David Goodger <http://python.net/~goodger>

David Goodger wrote:

> [From Docutils-checkins:]
>
>> -    node.set_class('handout')
>> +    node['classes'].append('handout')
>
> Should we leave a "set_class" method in place, for compatibility?

Yes, why not.  But I'd like to see it as "deprecated" (print a warning
to STDERR, or just in the docstring?) because otherwise people won't
change their code.

This is necessary (IMO) because the class logic in Docutils has *really*
changed (not just the interface).  3rd-party code that is using
set_class *may* happen to work with the compatibility-set_class method,
but it might be passing multiple classes in one string or it might check
if the old 'class' attribute is set, which will both lead to subtle
bugs.

Using the set_class method in current code (as in r3221) is just adding
unnecessary redirection, IMO.

(I currently have a bunch of unread mails from the mailing lists; I'll
catch up in a few days.)

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

http://www.ososo.de/

[Felix Wiemann]
 > David Goodger wrote:
 >> Should we leave a "set_class" method in place, for compatibility?
 >
 > Yes, why not.  But I'd like to see it as "deprecated" (print a
 > warning to STDERR, or just in the docstring?) because otherwise
 > people won't change their code.

OK, deprecation warning it is.  Done.

 > This is necessary (IMO) because the class logic in Docutils has
 > *really* changed (not just the interface).  3rd-party code that is
 > using set_class *may* happen to work with the
 > compatibility-set_class method, but it might be passing multiple
 > classes in one string or it might check if the old 'class' attribute
 > is set, which will both lead to subtle bugs.

I think you may be worrying too much.  After all, we can't prevent
client code from doing "Element.attributes['classes'].append('text
with multiple space-sparated words')", can we?  Even the "assert ' '
not in name" you added seems like overkill to me.

 > Using the set_class method in current code (as in r3221) is just
 > adding unnecessary redirection, IMO.

I removed set_class, only to put it back.  It was probably there to
begin with because Chris wrote it to work with the released code,
version 0.3.7, instead of bleeding-edge SVN.  This got me thinking
about the issue -- what API changes should we be making, and how?

Leaving obsolete methods behind for a while (how long?), but adding
deprecation warnings, seems like a good general policy.  It's much
kinder to end-users than the alternative.

--
David Goodger <http://python.net/~goodger>

David Goodger wrote:

> Felix Wiemann wrote:
>
>> This is necessary (IMO) because the class logic in Docutils has
>> *really* changed (not just the interface).  [...]
>
> I think you may be worrying too much.  After all, we can't prevent
> client code from doing "Element.attributes['classes'].append('text
> with multiple space-sparated words')", can we?

Yeah, but then it's just an "ordinary" bug.  I think it's bad if
assumptions invisibly change "behind the 3rd-party code's back."  This
way the maintainer gets notified that he has to change things.

> I removed set_class, only to put it back.  It was probably there to
> begin with because Chris wrote it to work with the released code,
> version 0.3.7, instead of bleeding-edge SVN.

That's true.

> This got me thinking about the issue -- what API changes should we be
> making,

Any, IMO.  The API isn't stable yet (it's under active development, in
fact), and sticking to a design just in order to maintain compatibility
is really bad for a project.

> and how?

Transitionally maintaining compatibility when it's possible seems like a
good thing.

> Leaving obsolete methods behind for a while (how long?), but adding
> deprecation warnings, seems like a good general policy.

Yes.  Regarding how long, I'd say one release (so we could remove
set_class somewhere between release 0.3.9 and the following release).
3rd-party code occasionally has to be updated anyway.

> It's much kinder to end-users than the alternative.

Yup.

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

http://www.ososo.de/