Re: [Python-markdown-discuss] Errors/Warnings should output to `sys.stderr`

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

I've committed a patch (r58) that adds use of the logging module. I
have left the `message` method as a wrapper in case any one's using it
in their extensions.

We gain two more levels (WARN & ERROR) between INFO & CRITICAL. I may
go through the code and add a few more messages to make use of them
when I have the time.

If anyone has any other input/sugestions/critisisms, please share.

The following is some documentation for customization. I'll likely add
a more polished version to the wiki when I have the time.

### Adding Logging Handlers
You could easily add any handler supported by the logging module.
Currently, only StreamHandler (outputs to console via stderr) is being
used. As the message threshold is restricted on the handler and not
the logger, your own handlers can have whatever level you want. The
level set by MESSAGE_THRESHOLD or through command line options only
affect the console output. Therefore, were `myHandler` is a handler of
the type and configuration you want:

    import markdown
    markdown.logger.addHandler(myHandler)
    markdown.markdown(text)

### Logging in Extensions
You could also configure your extension to inherit from markdown's
logger. Markdown's logger is named "MARKDOWN", so logging in an
extension would look something like this:

    import logging
    mylogger = logging.getLogger("MARKDOWN.myextension")

    mylogger.critical('A critical message!')

Then your message would look something like this:

    MARKDOWN.myextension-CRITICAL: "A critical message!"

Notice how the extension name appears in the message, which can be
helpful in debugging.

On Nov 16, 2007 11:35 AM, Waylan Limberg <wa...@gm...> wrote:
> Ok, I've worked out some logging code and tested it in all supported
> versions of python (2.3 is a pain to configure compared to 2.4 & 2.5).
> The question is, do we want to leave the api the same and wrap logging
> in our existing `message` method, or use logging directly? It's no
> trouble to do either. See the attached test file for examples.
>
> Any suggestions/improvements to the message format?
> Currently: NAME-LEVEL: "MESSAGE"
>
> The attached sample outputs the following:
>
>     MARKDOWN-DEBUG: "A debug message"
>     MARKDOWN-INFO: "info message"
>     MARKDOWN-WARNING: "warn message"
>     MARKDOWN-ERROR: "error message"
>     MARKDOWN-CRITICAL: "critical message"
>     MARKDOWN-WARNING: "a warning"
>     MARKDOWN-CRITICAL: "A Message using Markdown's existing api"
>
> I'll also mention that we could define our own levels, but why?
>
>
>
> On Nov 16, 2007 12:52 AM, Yuri Takhteyev <qar...@gm...> wrote:
> > Oh, well, what do we sociologists know...  Sure, let's send it to stderr.
> >
> >   - yuri
> >
> >
> >
> > On Nov 15, 2007 11:25 PM, Waylan Limberg <wa...@gm... > wrote:
> > >
> > > On Nov 15, 2007 9:13 PM, Yuri Takhteyev < qar...@gm...> wrote:
> > > > Not all messages are errors, so they probably shouldn't all go to the
> > error
> > > > stream.  Or should they?
> > >
> > > Yes they should - that's the general convention as I see it. Its a
> > > poorly named status stream. In fact, the logging module sends all
> > > messages (including non-error) to the error stream by default.
> > > Consider this simple commandline example:
> > >
> > > As it goes currently, when we run this command:
> > >
> > >    $ python markdown.py input.txt > output.html
> > >
> > > Any messages will get output to stdout, which in this case is
> > > output.html. However, if all messages are sent to stderr, then they
> > > would display on the console - not in output.html. I would say that is
> > > the desired behavior. I shouldn't have to open the file to see if any
> > > messages were generated.
> > >
> > > In the case of a wsgi app (and by extension most wsgi web frameworks),
> > > anything that would get logged is expected to go to stderr. Stdout is
> > > expected to be disabled. Seeing stderr & stdout are the only two
> > > options we have, stderr is the only acceptable choice here.
> > >
> > > I could be wrong, but I'd say it's also more likely that if output to
> > > the console is not an option, applications of any kind are more likely
> > > to redirect stderr than stdout. So if we use stderr, the messages are
> > > more likely to go were the developers want them to.
> > >
> > >
> > > >
> > > > I think at the time I was thinking in fact of using messages for
> > non-error
> > > > messages and using print_error() for errors.  Now, arguably
> > > > message(CRITICAL, "...") should be interpreted as an error.  Perhaps the
> > > > thing to do is to follow Trent's suggestion and to yank this function
> > out
> > > > altogether and replace with with calls to logging.  Less confusion.
> > >
> > > I forgot about logging, so thanks Trent. Yeah that certainly makes the
> > > most sense. But, just redirecting the current system to stderr would
> > > accomplish the same end. Therefore, I'm inclined to just do the
> > > quickfix now and work on logging for later.
> > >
> > > One additional advantage that logging would give us is that is should
> > > be easier for others to send the messages wherever they want - stderr,
> > > stdout, a log file, a blackhole... Then, when someone finds a
> > > new/different environment to use markdown in, it's easy for them to
> > > get it to work the way they need/want. It defiantly makes sense to use
> > > logging long term.
> > >
> > >
> > >
> > >
> > > >
> > > >   - yuri
> > > >
> > > >
> > > >
> > > >
> > > > On Nov 15, 2007 5:56 PM, Waylan Limberg <wa...@gm... > wrote:
> > > > >
> > > > >
> > > > >
> > > > > I should mention the easy fix. Just have `message` write to
> > `sys.stderr`:
> > > > >
> > > > >      def message(level, text) :
> > > > >          if level >= MESSAGE_THRESHOLD :
> > > > >     -        print text
> > > > >    +        print >> sys.stderr, text          # or
> > > > sys.stderr.write(text+'\n')
> > > > >
> > > > > But, is that good enough or should we use python's built-in
> > > > error-handling?
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > On Nov 15, 2007 3:35 PM, Waylan Limberg < wa...@gm... > wrote:
> > > > > >
> > > > > > Below is the text of the bug [1] I just filed. The reason I'm
> > posting
> > > > > > here is to get some feedback. Why was it done the way it is? Is
> > there
> > > > > > any good reason not to change?
> > > > > >
> > > > > > [1]:
> > > >
> > http://sourceforge.net/tracker/index.php?func=detail&aid=1832747&group_id=153041&atid=790198
> > > > > >
> > > > > > > Currently, caught errors are handled by the `message` method which
> > > > > > > uses `print` to display error/warning messages. As `print` outputs
> > to
> > > > > > > `sys.stout` by default, this conflicts with the wsgi spec [1].
> > > > > > >
> > > > > > > To my knowledge, wsgi_mod [2] is the only server that enforces the
> > > > > > > spec here, but in doing so, any `message` generated by markdown
> > would
> > > > > > > cause a `500` response by wsgi_mod. As most any python
> > web-framework
> > > > > > > has a wsgi interface, we should expect python-markdown to be used
> > in
> > > > > > > wsgi environments repeatedly and IMO support such use. FYI, I
> > first
> > > > > > > came across the problem here [3].
> > > > > > >
> > > > > > > We could just raise exceptions, but python trackbacks can be ugly
> > > > > > > (especially when were dealing with an end user and markdown syntax
> > > > > > > errors) and we need multiple levels. Perhaps we should be using
> > the
> > > > > > > warnings module [3] (available since Python 2.1) which outputs to
> > > > > > > `sys.stderr` by default.
> > > > > > >
> > > > > > > [1]: http://www.python.org/dev/peps/pep-0333/#error-handling
> > > > > > > [2]: http://code.google.com/p/modwsgi/wiki/DebuggingTechniques
> > > > > > > [3]: http://code.djangoproject.com/ticket/2910#comment:12
> > > > > > > [4]: http://docs.python.org/lib/module-warnings.html
> > > > > >
> > > > > >
> > > > > > --
> > > > > > ----
> > > > > > Waylan Limberg
> > > > > > wa...@gm...
> > > > > >
> > > > >
> > > > >
> > > > >
> > > > > --
> > > > > ----
> > > > > Waylan Limberg
> > > > > wa...@gm...
> > > > >
> > > > >
> > -------------------------------------------------------------------------
> > > > > This SF.net email is sponsored by: Microsoft
> > > > > Defy all challenges. Microsoft(R) Visual Studio 2005.
> > > > > http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
> > > > > _______________________________________________
> > > > > Python-markdown-discuss mailing list
> > > > > Pyt...@li...
> > > > > https://lists.sourceforge.net/lists/listinfo/python-markdown-discuss
> > > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Yuri Takhteyev
> > > > Ph.D. Candidate, UC Berkeley School of Information
> > > > http://takhteyev.org/, http://www.freewisdom.org/
> > >
> > >
> > >
> > > --
> > > ----
> > >
> > >
> > >
> > > 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...
>

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