marked-up Python code

[Tim Chase]

> "all" the Python parser has to do is skip the mark-up.
[snip]
> I know I can put the mark-up after a # and the problem is 
> solved trivially, but this will not work for all cases (e.g. 
> mark-up of single identifiers) and to be honest I was thinking
>  of recycling some mark-up capable editor and an existing
> mark-up language

Comments *are* the way in which you tell Python parser to "skip
the mark-up".

With a good editor, this is fairly easy to do.  And
folding/coloring is the job of the editor, not of Python.

I'll use Vim as an example, as it's my preferred tool and I know
it well enough to offer a solution using it, though surely any
other good editor can do similarly.

Vim offers two ways to do what you're describing.  First, you can
color sections by defining your own highlighting/syntax
augmentation.  Second, you can use folding to hide away bits of
your code that you don't want to see.

This combo can be used to do something like define several
markers such as

  # begin instrumenting
  # end instrumenting
  # one-line instrumentation

You can then do something like

  :set foldmethod=marker
  :set foldmarker=#\ begin,#\ end

This will create folds across all your blocks.  You can
selectively open/close these blocks with

  zR

to open all the folds and

  :g/#begin instrumenting/norm zC

to close just those folds tagged with "begin instrumenting".  The
two can be mapped into a single keypress, so you can do something
like

  :nnoremap <f4> zR:g/# begin instrumenting/norm zC<cr>

which will open all the folds and then just close the ones that
involve instrumenting merely by pressing <f4>

As for the single-line ones, you can use Vim's ":match"
functionality:

  :match Folded /.*# one-line instrumentation

The "Folded" is a highlighting group (it can be an existing one
such as "Folded" or "Error", or one you create to give you the
coloring you want).

Thus, in Vim, the whole thing could be done with a fairly simple
setup:

  :set foldmethod=marker foldmarker=#\ begin,#\ end
  :nnoremap <f4> zR:g/# begin instrumentation/norm zC<cr>:match
Folded /.*# one-line instrumentation/<cr>
  :nnoremap <f5> zR:g/# begin debugging/norm zC<cr>:match Folded
/.*# one-line debugging/<cr>

You would then mark up your code with things like

    import pdb; pdb.set_trace() # one-line debugging
    start = now() # one-line instrumentation
    do_stuff()
    # begin instrumentation
    end = now()
    delta = end - start
    # end instrumentation

and then use <f4> to hide your instrumentation code, and <f5> to
hide your debugging code.  it's a little more complex to invert
the behavior, but doable.

This can even be augmented to create these blocks for you:

  :vnoremap <s-F4> :'<put! ='# begin instrumentation'<cr>:'>put
='# end instrumentation'<cr>
  :nnoremap <s-F4> A# one-line instrumentation<esc>

which should define two mappings for shift+F4:  the first, in
visual-mode (with text selected) wraps those lines in the
begin/end pair.  In normal mode, shift+F4 just appends the
one-line tag to the end of the line.  Do similarly for shift+F5
for the debugging.

Hope this gives you some ideas to work with.  And perhaps
advocates of other editors can chime in with how it would be done
there.

-tkc