From 257c0fe9aad40879ebe9b6e84613d5c3a5adf2b5 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Mon, 29 Dec 2014 11:39:00 -0500 Subject: Better docs of treeprocessor API. Fixes #375. Explains the difference between returning None and returning a modified root element. Also makes the docs more consistent with the doc strings in the code. --- docs/extensions/api.txt | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt index 8837818..7987c25 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.txt @@ -136,7 +136,8 @@ the tree and runs the InlinePatterns on the text of each Element in the tree. A Treeprocessor should inherit from ``markdown.treeprocessors.Treeprocessor``, over-ride the ``run`` method which takes one argument ``root`` (an Elementree -object) and returns either that root element or a modified root element. +object) and either modifies that root element and returns `None` or returns a +new ElementTree object. A pseudo example: @@ -144,8 +145,18 @@ A pseudo example: class MyTreeprocessor(Treeprocessor): def run(self, root): - #do stuff - return my_modified_root + root.text = 'modified content' + +Note that Python class methods return `None` by default when no `return` +statement is defined. Additionly all Python variables refer to objects by +reference. Therefore, the above `run` method modifies the `root` element +in place and returns `None`. The changes made to the `root` element and its +children are retained. + +Some may be inclined to return the modified `root` element. While that would +work, it would cause a copy of the entire ElemetTree to be generated each +time the treeprocessor is run. Therefore, it is generally expected that +the `run` method would only return `None` or a new ElementTree object. For specifics on manipulating the ElementTree, see [Working with the ElementTree][] below. -- cgit v1.2.3