Idea for HTML annotation
Wolfgang Ulmer
Hi, during the Cython tutorial on EuroPython, an idea came up for improving the HTML annotation, that you get when running cython with -a: Sometimes, it is not directly clear if an identifier in Python (e.g. module or function) is being treated in the C or Python domain. I remember a question during the tutorial where there was a Python math.sin replaced by a C call to the sin function. On another line, there was math.pi being used which of course was not found in the C math library (there it is called M_PI).
I wondered if there is a way to annotate the different identifiers in the HTML output somehow so that their treatment (C or Python) is more explicitly visible. In the described case above, the math.sin would get e.g. a gray border (for C) whereas the math.pi would have gotten e.g. a blue border (for Python).
This is just an idea so I am not totally sure if this would help people to understand more clearly what Cython is doing (if you look deeper in the generated C code, you will always know, but it is not so explicit). But for the cases I can remember, it might have helped me find those minor glitches much easier.
Is there anyone else who thinks this would be an improvement to the annotated HTML of the Python code?
Stefan Behnel
annotated HTML does not have that type information any more. It's a plain
text based tool that runs as part of the C code generation step and is
actually independent of the code generator itself. The implementation is in
Annotate.py. Its input is not more than the plain generated C code.
That being said, if this is really just about adding special annotations
for certain names, it might be possible to get away with somehow passing
that meta-data (e.g. a dict with certain information about the local
variables of the current function) into the CCodeWriter, so that the
AnnotationCCodeWriter could intercept and use it. Injecting type names
and/or certain css classes into the HTML generated by pygments should then
be doable.
Contributions welcome.
Stefan
Wolfgang Ulmer
My idea was to create custom `AnnotationItems` for example for `CallNode` or `NameNode` which contain the information if this node refers to a Python or a C object. I would like to use these annotations then in the `AnnotationCCodeWriter` in `_save_annotation_body`. However I am not sure if I understand the use of `AnnotationItems`.
Is it possible to use these somehow in the `AnnotationCCodeWriter`? I can't find where they are stored and wether they are accessible by the `AnnotationCCodeWriter`?
Stefan Behnel
> Thanks. I had a look over the code and I am not sure if I understand the
> annotation mechanism.
> My idea was to create custom `AnnotationItems` for example for `CallNode`
> or `NameNode` which contain the information if this node refers to a Python
> or a C object. I would like to use these annotations then in the
> `AnnotationCCodeWriter` in `_save_annotation_body`. However I am not sure
> if I understand the use of `AnnotationItems`.
They provide interesting information, though, such as hints on function
calls or type coercions. It might not be entirely easy to merge them into
the syntax highlighted source code, which I guess is one of the reasons why
their usage was disabled back in 2010.
I added some things in master. First of all, the code writer has access to
the current function scope now, and the annotation writer remembers the
scope for each code position. I then also grouped the annotation items by
files, so that they can be accessed more easily in _save_annotation_body().
The scope has an attribute "entries" that holds a mapping of names to
symbol table entries (class Entry). Those know everything about the name,
including its type (attribute "type"), so that should give you all you need.
I also added a test for the HTML file writer, which seemed to be missing.
Can you build on this? Feel free to change the details of what I added,
it's not currently used and is only meant as helpful infrastructure.
Stefan