2008-04-20
Finding the name of your caller in Python
One of the things that would be useful in an access tracer is reporting not just what was accessed, but where it was accessed from. A basic starter for this is knowing what function called you.
CPython has enough introspection faculties to give you this information, but it's not entirely documented how to dig it out. The big tool for this is the inspect module, and we can use it to define a function:
import inspect
def getcallerinfo(): fr = inspect.currentframe() try: fr = fr.f_back.f_back if fr is None: return "<no caller>" fi = inspect.getframeinfo(fr, 0) if fi[2] == "<module>": return "(%s:%d)" % (fi[0], fi[1]) else: return "%s() (%s:%d)" % (fi[2], fi[0], fi[1]) finally: del fr
This returns something like 'barfunc() (foo.py:30)
', which means that
the function that called getcallerinfo()
was called by barfunc()
,
specifically the code at line 30 of foo.py
.
Technically we don't need to call inspect.getframeinfo()
to obtain
this information (we could just use fr.f_code.co_filename
and so on directly, since they're documented), but it handles some
peculiar magic with the file name for us.
(Needless to say, this is probably specific to CPython; I would be surprised if the same code worked in Jython or IronPython or the like. Since all of this is documented, it is at least likely to be portable across different versions of CPython and to keep working in future ones.)
What FAQs are
Here's a question: which type of documentation is the ever-popular FAQ format?
My answer is that in practice, FAQs are a collection of tutorials; they tell you how to do various specific frequently asked operations. This has important implications if your primary documentation format is FAQs, because FAQs effectively have drawbacks from both sides; they're not as well organized or as comprehensive as reference documents, and they don't give you an overall view the way a single unified tutorial does.
(That they are a collection implies that FAQs live and die on their organization, ie how easy it is for people to find the specific question that they need.)
If FAQs are currently your primary form of documentation, I think that the most important second form to have is reference documentation, because it is the most efficient way to cover the remaining information and probably also the easiest for people to use.
(By 'efficient' I mean 'most results for the least amount of documentation writing'. Complete tutorial documentation is almost always longer than equally complete reference documentation.)
As an aside, FAQs as your primary documentation may seem silly, but I think it's a natural thing if you're too pressed for time to write much documentation. FAQs make it easy to create something useful right away and then grow it piece by piece, they give you a natural starting point, and it's less intimidating to sit down to write some FAQs than to write either full tutorial or full reference documentation.