python-markdown-discuss

Re: [Python-markdown-discuss] Markdown package with debug statements

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

On Wed, Mar 5, 2008 at 12:08 PM, Malthe Borch <mb...@gm...> wrote:
> Hey Waylan, ––
>
>  In the 1.7-release of markdown there are some DEBUG statements left in
>  the code; is that on purpose?
>

Malthe,

I'm assuming you are referring to `message` statements set to level
DEBUG, like so:

    message(DEBUG, "a debug message")

If so, yes, that was intentional. If you notice, starting about line
36 we are using python's logging module and by default the logger is
set to level CRITICAL. That being the case any lower level (like
DEBUG) is ignored. However, if one wanted to do some debugging, a
simple change of the logger level would make that easy. This is
actually the intended purpose of the logging module. Much better than
adding (and latter remembering to find and remove) print statements.

If you'd like more information on the logging module, see the
[docs][1] or [PEP 282][2].

[1]: http://docs.python.org/lib/module-logging.html
[2]: http://www.python.org/dev/peps/pep-0282/

As the PEP says (under the "Configuration" section):

> The main benefit of a logging system like this is that one can
> control how much and what logging output one gets from an
> application without changing that application's source code.
> Therefore, although configuration can be performed through the
> logging API, it must also be possible to change the logging
> configuration without changing an application at all.

If your wondering why this is necessary for a command line script like
markdown, remember that many (perhaps most) are using markdown.py
behind a web server which would require the ability to reconfigure
logging. Such a user could conceivably redirect such messages to their
servers error log  for review when problems are encountered. In fact,
in most web server configurations this is the only way to debug a
problem.

I hope that answers your question. However, if you actually found some
print statements or such that I missed, please let me know where and
I'll remove them.

Either way, thanks for your feedback. It's always appreciated. In
fact, this reminds me that I should probably document how to configure
the logger for a few basic use cases.

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

Re: [Python-markdown-discuss] Markdown package with debug statements

[Malthe B. <mb...@gm...>]

Hey Waylan, ––

Thanks for your reply.

On 05/03/2008, Waylan Limberg <wa...@gm...> wrote:
>  If your wondering why this is necessary for a command line script like
>  markdown, remember that many (perhaps most) are using markdown.py
>  behind a web server which would require the ability to reconfigure
>  logging. Such a user could conceivably redirect such messages to their
>  servers error log  for review when problems are encountered. In fact,
>  in most web server configurations this is the only way to debug a
>  problem.

That's a good point, although I would think that at some point, the
package reaches a state of maturity where automated tests should take
the place of any runtime debugging. That is, ––– if the output is not
what's expected, it should be proven in a test such that it can be
fixed.

I think a good use for log statements is when rare or unexpected
events happen, or if the user of the package needs some information.

Instead of having the debug statement in the markdown package, I think
it should be in the application using markdown, if that application is
still in development.

\malthe

Re: [Python-markdown-discuss] Markdown package with debug statements

[Yuri T. <qar...@gm...>]

Malthe,

First, there are only two debug messages at the moment in subversion.
But I also disagree with the principle.  Code is never bug free.
People always end up finding new bugs.  Or ask for features.  Or
suggest optimizations.  In fact, the more mature the project is, the
more people use it, and the more bugs they report and the more
suggestions they make.  Which means that every now and then we have to
go an debug the code.  To paraphrase a well-known quotation, "a
software project is never finished, only abandoned."  Python-markdown
has not been abandoned yet, therefore it is not finished.

Some debug messages are very specific to a particular bug.  Once the
bug is fixed, they can be removed.  Except that of course you are
never 100% sure that the change you made fully fixes the bug.  Sure it
passes specific tests, but someone will come up with another test that
will fail.  (Or you will come up with one in the shower the next
morning.)  So, if the bug fix is tentative, it makes sense to leave
the debug statements in, I think.  It does make sense to clean those
up eventually.  Additionally, some debug messages come in handy for
pretty much any debugging session.  In those cases it makes sense to
leave them around for longer.

Tests are not a replacement for debug messages.  A test suit helps you
identify regressions, but it can't help you find what _causes_ them.

>  I think a good use for log statements is when rare or unexpected
>  events happen, or if the user of the package needs some information.

That's why the debug messages are filtered out by default.  You need
to ask for them to see them.  Default logging level is CRITICAL.

 - yuri

-- 
http://sputnik.freewisdom.org/

Re: [Python-markdown-discuss] Markdown package with debug statements

[Malthe B. <mb...@gm...>]

On 05/03/2008, Yuri Takhteyev <qar...@gm...> wrote:
>  Some debug messages are very specific to a particular bug.  Once the
>  bug is fixed, they can be removed.  Except that of course you are
>  never 100% sure that the change you made fully fixes the bug.  Sure it
>  passes specific tests, but someone will come up with another test that
>  will fail.  (Or you will come up with one in the shower the next
>  morning.)  So, if the bug fix is tentative, it makes sense to leave
>  the debug statements in, I think.  It does make sense to clean those
>  up eventually.  Additionally, some debug messages come in handy for
>  pretty much any debugging session.  In those cases it makes sense to
>  leave them around for longer.

I can see that there is no test suite included with the markdown
package; if believe that it would beneficial to move these debugging
statements out of the package and into a test suite (where you get to
explicitly define what you expect to see in those statements).

This way, you can let people know why you're interested in the output
and what you expect to see.

By the way: I'm only starting this thread because the markdown package
is great work and I'm a happy user :-)

\malthe

Re: [Python-markdown-discuss] Markdown package with debug statements

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

On Wed, Mar 5, 2008 at 5:49 PM, Malthe Borch <mb...@gm...> wrote:
>
>  I can see that there is no test suite included with the markdown
>  package; if believe that it would beneficial to move these debugging
>  statements out of the package and into a test suite (where you get to
>  explicitly define what you expect to see in those statements).

First, IIRC the debug statements are only in the wrapper functions. I
would think that this is the most likely that people using markdown
would want to debug. In debugging their app which uses markdown, they
might be unsure that their app is actually passing things on to
markdown correctly. Those debug messages allow them to easily check
that. I think that adds enough value to leave them.
>
>  This way, you can let people know why you're interested in the output
>  and what you expect to see.
>
>  By the way: I'm only starting this thread because the markdown package
>  is great work and I'm a happy user :-)

Glad to hear it, and glad you brought it up. The testing framework is
actually what I want to focus on now that 1.7 it out of the door. I
had started to develop some regression tests for the api, but
unfortunately lost them in a hard drive failure (and no I didn't have
a proper backup). I guess it's back to the drawing board on that. Any
input others may have is more than welcome.
>
>  \malthe
>

To be

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