How is introspection useful?

Suppose you are given a custom object and you want to know if the object has certain attributes or has as a certain method, then the introspection function such as hasattr can be used to find that out.

Also like the DiveintoPython book already illustrates, suppose you are building a GUI Editor with Auto-Completion feature, you want to get the public methods of the object which are callable at the run-time, then you can use the introspection methods like getattr for each for the methods got via dir and check if it is callable and then display it in your auto-completion list.

A little bit late on this, but another example of introspection in use is with Active Record (a Ruby library that maps objects to database tables). Active Record uses introspection to look at the name of the class, determine the associated table, and defines methods that access object attributes after inferring their names from the database schema. It reads the schema at runtime (metaprogramming & introspection in play here). So for example, if you have a class Person, you don't have to write accessor methods e.g nameoremail. As long as columns by the same name (in this case nameandemail) exist in the associated table (in this case people`), Active Record defines accessor methods for these attributes of the same name at runtime.

I wrote a documentation validator that runs tests on PDF files to check for various problems with them. The tests are methods of special classes that represent Subversion branches, products, manuals, and arbitrary groupings of various types. The validator engine uses introspection to find these special classes, instantiate them, and run their methods.

I could have written the validator so that you have to write boilerplate code to instantiate each class, call each method, etc. But that is repeating yourself and it is prone to maintenance problems (failure to update both places when adding/removing tests, in this case). By taking advantage of the fact that you want to apply the same operation to all the special classes, the computer can essentially do the boilerplate stuff for you, and it won't make mistakes. That way, you have to declare the structure of the documentation in only one place.

One example where I have used introspection on a real project:

We had a service that was managing background tasks called TaskService. Each task was actually implemented as a class that was implementing the Start() Stop() methods of a given interface. We had a config file, in which we were matching each task with its class. So when running TaskService, it just browsed the config file, and for each task it took the name of the class and instanciated it (during runtime) through reflection (introspection is a subpart of reflection).

Another example of where introspection can be useful is in the use of annotations in your programming language. Annotations are used to give metainformation about your classes to other third party programs (like ORMs), for instance you can use annotations to tell whether a class is an entity class (it is the case in Java, I don't know about Python sorry), or about the type of association of certain attributs etc.

Code Completion is another example of the usefulness of introspection.

And by the way, as you mentionned, introspection helps a lot to program documentation tools.