> Here's what I'm actually doing::
> source = document.current_source
> if source is None:
> return os.getcwd()
``document.current_source`` will only be set to ``None`` after parsing
is finished. If this code is inside a directive function, parsing is
ongoing, so you shouldn't need the test. If that local ``source`` is
ever ``None``, it would be a bug, and the test above would mask it.
> Now that I understand what's going on, I'm a bit less unhappy, but I
> think that perhaps the names should be changed from
> ``source``/``current_source`` to ``original_source``/``source``.
"source" is the source of the element itself. It doesn't change.
"current_source" is the source of the line of data currently being
parsed. This may change, for example if an "include" directive is
used. The names make sense to me.
> I'm still a bit confused about the distinction between
> ``document.source`` (which is ``None``) and ``document['source']``.
``document.source`` is an internal instance attribute, an
implementation detail, added to get better error/warning output.
``document['source']`` is an external attribute. All external
attributes are stored in ``element.attributes`` (a dict), get
exported as XML attributes, and are documented in spec/docutils.dtd
> I'm also thinking that the use of ``Element.__getitem__`` needs
> redesign; I can just imagine what Alex Martelli would say about
> getting different kinds of data based on the type of key presented.
> Probably the simplest approach would be to stop using
> ``__getitem__`` as a proxy for ``Element.attributes``. (I'm not
> going to argue with you, but I can tell you that Alex *WILL* argue
> with you if/when he sees that. ;-)
You know what? I don't care what Alex would say. :-)
The technique makes sense for this application. ``element`` gives
the first child, and ``element['name']`` gets the "name" attribute.
It may be a wart to some eyes, but it's a very practical and useful
wart that reduces complexity. If you don't like it, use
``element.children`` and ``element.attributes['name']``; but they
don't do the extra bookkeeping that ``Element.__setitem__`` and
I seem to recall a quote about just this topic, maybe it was Guido
expressing his disgust with a similar convention. But I can't locate
it now. Pity.
David Goodger <goodger@...> Open-source projects:
- Python Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)
- The Go Tools Project: http://gotools.sourceforge.net/