Re: [Docutils-users] Migration docutils 0.12 to 0.13

[David G. <go...@py...>]

On Tue, Jan 3, 2017 at 3:13 AM, Guenter Milde <mi...@us...> wrote:
> Dear David,
>
> On 2017-01-02, David Goodger wrote:
>
>> Patch attached.
>
>>> You didn't do anything wrong that I can see. There was an internal
>>> change to Docutils in revision 7942 that refactored some code, and a
>>> side effect was to remove some attributes from the Inliner class (they
>>> became locals instead). Your code depends on these class attributes.
>
>>> Try applying the attached patch and let us know how it works. The
>>> missing class attributes will be present as instance attributes, which
>>> should be close enough.
>
>>> Günter, I think the attached patch should also be rolled into a 0.13.2
>>> bugfix release.
>
> Is the patch still "on the table"?

Yes, but I'm looking at making more extensive changes first. The patch
that implemented the changes to support
settings.character_level_inline_markup really made a mess of things:

1. Inliner.__init__ is currently a no-op (code: just "pass"). That
smells bad. Why even have the method if it does nothing? Prior to the
patch (in, say, r7640), it initialized self.implicit_dispatch. It
can't do that completely now, but it can initialize an empty
self.implicit_dispatch with a docstring.

2. My coding style is to initialize all instance attributes in the
__init__ method of a class, for easy reference, and include an
attribute docstring for documentation. The Inliner class now breaks
this style. I'd like to fix this.

3. The Inliner.init_customizations method grew from 6 physical lines
of code to almost 140 lines. This was because all of the formerly
statically defined class attributes were brought in, to be defined
dynamically depending on settings.character_level_inline_markup. I
plan to refactor this huge method into a small init_customizations and
shunt all the definitions into another method.

4. That ``args.update(vars(Inliner))`` line is fragile, and should be replaced.

I'll work on all these and propose another patch.

> Also with this patch, the attributes `start_string_prefix`,
> `end_string_suffix`, and `parts` are only available after calling
> ``inliner.init_customizations(document.settings)``.

This may change back to the prior status.

> Is there a use-case for this scenario we want to support?
> If not, we could define them as internal auxiliary variables after
> the API change that came with implementation of [ 103 ].

I want to restore the attributes (formerly class attributes, maybe now
they have to be instance attributes, although maybe not) that were
part of the de-facto API prior to [103]. We've seen one example of
client code that depended on these, and there may be others.

> That said, I am not against the patch. If including, I just propose a small
> correction:

Incorporated into my working copy.

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