[cfe-commits] [PATCH] Add Python bindings to comment AST introspection APIs

[Gregory Szorc]

On 12/20/12 2:06 PM, Ben Gertzfield wrote:
> Exposes Dmitri's new comment AST introspection APIs ( 
> http://clang.llvm.org/doxygen/group__CINDEX__COMMENT.html ) via the 
> existing Python bindings.
Nice! I hope to look at this in full soon. Could you please upload the 
diff to http://llvm-reviews.chandlerc.com/differential/ to make the 
review easier?
>
> 1) For the comment AST methods, they're currently all in one 
> (way-too-large) Comment class.
>
> Should I split these into multiple Python classes, or leave them in a 
> flat hierarchy to match the libclang API?
>
> Splitting it up may make it easier to read the API, but makes it more 
> fragile when the AST logic changes (and it probably will change over 
> time).
>
> Keeping it in one class makes it simpler to handle AST logic changes 
> in the future, but the class is pretty bloated, and has a number of 
> is_foo_type() methods.

This is a hard question. On one hand, I sympathize with the crowd that 
wants the Python bindings to resemble libclang APIs as closely as 
possible. On the other, the Python bindings are supposed to be "Pythonic."

I didn't pay much attention to the development of the libclang 
commenting APIs, but I'm guessing the reason we went with a single 
struct (CXComment) is because that's just how C works. The underlying 
C++ implementation, however, does use separate classes for each comment 
type.

Separate Python classes seem to make sense to me. I'm not too worried 
about fragility because the C bindings will tend to reflect what's 
happening in C++ land. Besides, the C API is supposed to be relatively 
stable. If you model the Python class hierarchy after C++, I think 
things will be fine. Besides, having to call is_foo_type() instead of 
using isinstance() everywhere isn't very "Pythonic."
>
> 2) For the methods that return HTML and XML, should they just return 
> strings, or should I make the API return parser objects? (It seems 
> like introducing a dependency on those modules is probably not the 
> best idea, but I'm not sure what the state of the art is in HTML and 
> XML in Python.)
>
Yes, a dependency would be bad. And, forcing people to use one XML 
implementation over the other may not be desirable. That being said, I'm 
supportive of leaving the door open to returning "rich" data types in 
the future. Perhaps rename the string-returning methods to 
"as_xml_string()" or similar?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20121220/d4142aa0/attachment.html>