Wandering Thoughts archives

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.)

python/FindingCallersName written at 23:04:48;

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.

tech/WhatFAQsAre written at 00:34:26;


Page tools: See As Normal.
Search:
Login: Password:

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.