[Python-markdown-discuss] The purpose of reset()

[Waylan L. <wa...@gm...>]

Wanted to copy everyone on a discussion between Yuri and myself
regarding the purpose and behavior of the reset method. The bug that
sparked this discussion has since been fixed in svn, but I thought
Yuri's explanation  (included below) of reset was very helpful. It
occurs to me that this may be good to add to the documentation in some
form on the "Writing Extensions" page.

Anyone else have any thoughts, additions, etc.?

On 11/3/07, Yuri Takhteyev <qar...@gm...> wrote:
> The intended behavior was the following: calling reset() may be
> necessary depending on the extensions that you use, but should not be
> required in general.  So, in this case it is a bug.
>
> Ideally, the user will reset on individual extensions, when needed,
> which may not be after every conversion.  E.g., suppose you want to
> convert several "books", each with several chapters, where each
> chapter is a separate markdown file.  Suppose you want all footnotes
> for all chapters of each book to be rendered as endnotes, as a
> separate file in that book.  So, you write an endnote extension and
> use it as follows:
>
> for book in books:
>       md.extensions["endnotes"].reset() # can't remember the exact syntax
>       for chapter in chapter.get_books():
>             converted_chapter = md.convert(chapter)
>             converted_chapter.save()
>       book.endnotes = md.extensions["endnotes"].get_endnotes()
>
> So, in this case you reset the extension, process _several_ files,
> then reset it.
>
> reset() is just a shortcut to reset all extensions - if you want to
> make sure that you start with a clean slate.
>
> All that said, if you don't have any extensions, convert() shouldn't
> change the state of anything, so what Trent reported _is_ a bug.
>
> Oh, and yes, we should discuss this on the list.  You can either post
> your question there and I will re-post the answer, or you can forward
> my response, or whatever.
>
>   - yuri
>
> On Nov 3, 2007 1:08 PM, Waylan Limberg <wa...@gm...> wrote:
> > Yuri,
> >
> > Could you clarify the intended behavior here. My assumption is that
> > md.reset should be called between each call to md.convert and that
> > this is not a bug, just a documentation issue. If you can confirm,
> > I'll update the docs.
> >
> > Although, if we are depreciating/removing all other methods and
> > md.convert will be the only way to pass source text in, perhaps
> > convert should automatically call reset each time. Perhaps that's a
> > question to pose to the list.
> >
> > ---------- Forwarded message ----------
> > From: SourceForge.net <no...@so...>
> > Date: Nov 3, 2007 1:04 PM
> > Subject: [ python-markdown-Bugs-1825231 ] repeated md.convert() can
> > give incorrect results
> > To: no...@so...
> >
> >
> > Bugs item #1825231, was opened at 2007-11-03 17:04
> > Message generated for change (Tracker Item Submitted) made by Item Submitter
> > You can respond by visiting:
> > https://sourceforge.net/tracker/?func=detail&atid=790198&aid=1825231&group_id=153041
> >
> > Please note that this message will contain a full copy of the comment thread,
> > including the initial issue submission, for this request,
> > not just the latest update.
> > Category: None
> > Group: Markdown Core
> > Status: Open
> > Resolution: None
> > Priority: 5
> > Private: No
> > Submitted By: Trent Mick (tmick)
> > Assigned to: Nobody/Anonymous (nobody)
> > Summary: repeated md.convert() can give incorrect results
> >
> > Initial Comment:
> > This is for markdown.py version:
> >  version = "1.6b"
> >  version_info = (1,6,2,"rc-2")
> >
> >
> > A problem can occur when you have code that creates a
> > Markdown instance and calls .convert() on it more than once, e.g.:
> >
> >  m = Markdown()
> >  m.convert(some_text)
> >  m.convert(some_other_text)
> >
> > Currently, if "some_other_text" is the empty string, then
> > m.convert(some_other_text) will return the results for
> > m.convert(some_text).
> >
> > Or is it the intention that one must call:
> >
> >  m.reset()
> >
> > before calling m.convert() again?
> >
> > If so, perhaps the short example in the module docstring could be
> > updated to indicate that.
> >
> > (Aside: the module docstring usage snippet is wrong. It creates a
> > 'Markdown' instance as variable 'md' but then doesn't use 'md' for the
> > '.convert()' call.)
> >
> >
> >
> >
> > ----------------------------------------------------------------------
> >
> > You can respond by visiting:
> > https://sourceforge.net/tracker/?func=detail&atid=790198&aid=1825231&group_id=153041
> >
> >
> > --
> > ----
> > Waylan Limberg
> > wa...@gm...
> >
>
>
>
> --
> Yuri Takhteyev
> Ph.D. Candidate, UC Berkeley School of Information
> http://takhteyev.org/, http://www.freewisdom.org/
>


-- 
----
Waylan Limberg
wa...@gm...