Python/CIndex include file support

Attached is a patch that implements include file traversal support for the Python binding’s TranslationUnit class (plus a test case and a small example program).

The new TranslationUnit.includes property returns a sequence of tuples containing the including file (or None for the “inclusion” of the TU source file), the included file, the source location and the include depth. Basically, it returns an attributed edge list (graph).

I also wrote a small example utility that dumps the include graph as a Graphviz dot file.

Andrew Sutton
andrew.n.sutton@gmail.com

Oops. Now the patch is attached. Stupid ‘Send’ button.

Andrew Sutton
andrew.n.sutton@gmail.com

py.diff (6.78 KB)

Hi Andrew,

Sorry I haven't had time to look at this yet. I'll try to get to it by
the weekend.

One immediate comment though, I would prefer to not expose this via a
property. I prefer to use functions (get_includes or so) for features
which require significant work, and only use properties for things
which are logically O(1). Otherwise the API tends to give the wrong
mental model of what is going on under the covers.

- Daniel

Sorry I haven’t had time to look at this yet. I’ll try to get to it by
the weekend.

No rush.

One immediate comment though, I would prefer to not expose this via a
property. I prefer to use functions (get_includes or so) for features
which require significant work, and only use properties for things
which are logically O(1). Otherwise the API tends to give the wrong
mental model of what is going on under the covers.

I was back and forth on that issue. Also, I’m not fully convinced that the returning tuples is the right thing to do. It might be better to create a class called “Inclusion” that explicitly names the including file, included file, location, depth, etc.

Also, on the CIndex side, is there a plan to support a max-depth on that traversal? It’s easy enough to emulate from the Python side, but it wouldn’t actually bound the traversal.

Andrew Sutton
andrew.n.sutton@gmail.com

Sorry I haven't had time to look at this yet. I'll try to get to it by
the weekend.

No rush.

One immediate comment though, I would prefer to not expose this via a
property. I prefer to use functions (get_includes or so) for features
which require significant work, and only use properties for things
which are logically O(1). Otherwise the API tends to give the wrong
mental model of what is going on under the covers.

I was back and forth on that issue. Also, I'm not fully convinced that the
returning tuples is the right thing to do. It might be better to create a
class called "Inclusion" that explicitly names the including file, included
file, location, depth, etc.

Yeah, I haven't looked closely, but I think it might make sense to have a class.

Also, on the CIndex side, is there a plan to support a max-depth on that
traversal? It's easy enough to emulate from the Python side, but it wouldn't
actually bound the traversal.

Not currently, and I'm not sure how much efficiency there is to gain
with it. Was there a particular use case?

- Daniel

I was back and forth on that issue. Also, I’m not fully convinced that the
returning tuples is the right thing to do. It might be better to create a
class called “Inclusion” that explicitly names the including file, included
file, location, depth, etc.

Yeah, I haven’t looked closely, but I think it might make sense to have a class.

Let me rewrite that and post a new patch for consideration.

Also, on the CIndex side, is there a plan to support a max-depth on that
traversal? It’s easy enough to emulate from the Python side, but it wouldn’t
actually bound the traversal.

Not currently, and I’m not sure how much efficiency there is to gain
with it. Was there a particular use case?

Not especially. For some reason, I was thinking that the VisitChildren function had a bounded depth, and that this would be nicely symmetric. Looking closer, I see that I’m wrong. So… never mind :slight_smile:

Andrew Sutton
andrew.n.sutton@gmail.com