Introspection

A Python code can ask and answer questions about itself and the objects it is manipulating.

dir()

`dir()` is a built-in function which returns a list of all the names belonging to some namespace.

  • If no arguments are passed to dir (i.e. `dir()`), it inspects the namespace in which it was called.

  • If `dir` is given an argument (i.e. `dir()`, then it inspects the namespace of the object which it was passed.

    For example:

    In [1]:
    apples = ['Cox', 'Braeburn', 'Jazz']
dir(apples)
    Out[1]:
    ['__add__',
 '__class__',
 '__contains__',
 '__delattr__',
 '__delitem__',
 '__dir__',
 '__doc__',
 '__eq__',
 '__format__',
 '__ge__',
 '__getattribute__',
 '__getitem__',
 '__gt__',
 '__hash__',
 '__iadd__',
 '__imul__',
 '__init__',
 '__iter__',
 '__le__',
 '__len__',
 '__lt__',
 '__mul__',
 '__ne__',
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',
 '__reversed__',
 '__rmul__',
 '__setattr__',
 '__setitem__',
 '__sizeof__',
 '__str__',
 '__subclasshook__',
 'append',
 'clear',
 'copy',
 'count',
 'extend',
 'index',
 'insert',
 'pop',
 'remove',
 'reverse',
 'sort']
    In [2]:
    dir()
    Out[2]:
    ['In',
 'Out',
 '_',
 '_1',
 '__',
 '___',
 '__builtin__',
 '__builtins__',
 '__doc__',
 '__loader__',
 '__name__',
 '__package__',
 '__spec__',
 '_dh',
 '_i',
 '_i1',
 '_i2',
 '_ih',
 '_ii',
 '_iii',
 '_oh',
 '_sh',
 'apples',
 'exit',
 'get_ipython',
 'quit']
    In [3]:
    name = "Peter"
dir(name)
    Out[3]:
    ['__add__',
 '__class__',
 '__contains__',
 '__delattr__',
 '__dir__',
 '__doc__',
 '__eq__',
 '__format__',
 '__ge__',
 '__getattribute__',
 '__getitem__',
 '__getnewargs__',
 '__gt__',
 '__hash__',
 '__init__',
 '__iter__',
 '__le__',
 '__len__',
 '__lt__',
 '__mod__',
 '__mul__',
 '__ne__',
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',
 '__rmod__',
 '__rmul__',
 '__setattr__',
 '__sizeof__',
 '__str__',
 '__subclasshook__',
 'capitalize',
 'casefold',
 'center',
 'count',
 'encode',
 'endswith',
 'expandtabs',
 'find',
 'format',
 'format_map',
 'index',
 'isalnum',
 'isalpha',
 'isdecimal',
 'isdigit',
 'isidentifier',
 'islower',
 'isnumeric',
 'isprintable',
 'isspace',
 'istitle',
 'isupper',
 'join',
 'ljust',
 'lower',
 'lstrip',
 'maketrans',
 'partition',
 'replace',
 'rfind',
 'rindex',
 'rjust',
 'rpartition',
 'rsplit',
 'rstrip',
 'split',
 'splitlines',
 'startswith',
 'strip',
 'swapcase',
 'title',
 'translate',
 'upper',
 'zfill']

    Magic names

    You will find many names which both start and end with a double underscore (e.g. `__name__`). These are called magic names. Functions with magic names provide the implementation of particular python functionality.

    For example, the application of the `str` to an object `a`, i.e. `str(a)`, will – internally – result in the method `a.__str__()` being called. This method `__str__` generally needs to return a string. The idea is that the `__str__()` method should be defined for all objects (including those that derive from new classes that a programmer may create) so that all objects (independent of their type or class) can be printed using the `str()` function. The actual conversion of some object `x` to the string is then done via the object specific method `x.__str__()`.

    We can demonstrate this by creating a class `my_int` which inherits from the Python’s integer base class, and overrides the `__str__` method. (It requires more Python knowledge than provided up to this point in the text to be able to understand this example.)

    In [4]:
    class my_int(int): 
    """Inherited from int""" 
    def __str__(self): 
        """Tailored str representation of my int""" 
        return "my_int: %s" % (int.__str__(self))
 
a = my_int(3)
b = int(4)            # equivalent to b = 4
print("a * b = ", a * b)
print("Type a = ", type(a), "str(a) = ", str(a))
print("Type b = ", type(b), "str(b) = ", str(b))

    a * b =  12
Type a =  <class '__main__.my_int'> str(a) =  my_int: 3
Type b =  <class 'int'> str(b) =  4

    Further Reading

    See →Python documentation, Data Model

    type

    The `type()` command returns the type of an object:

    In [5]:
    type(1)
    Out[5]:
    int
    In [6]:
    type(1.0)
    Out[6]:
    float
    In [7]:
    type("Python")
    Out[7]:
    str
    In [8]:
    import math
type(math)
    Out[8]:
    module
    In [9]:
    type(math.sin)
    Out[9]:
    builtin_function_or_method

    isinstance

    `isinstance(, )` returns True if the given object is an instance of the given type, or any of its superclasses. Use `help(isinstance`) for the full syntax.

    In [10]:
    isinstance(2,int)
    Out[10]:
    True
    In [11]:
    isinstance(2.,int)
    Out[11]:
    False
    In [12]:
    isinstance(a,int)    # a is an instance of my_int
    Out[12]:
    True
    In [13]:
    type(a)
    Out[13]:
    __main__.my_int

    help

    • The `help()` function will report the docstring (magic attritube with name `__doc__`) of the object that it is given, sometimes complemented with additional information. In the case of functions, `help` will also show the list of arguments that the function accepts (but it cannot provide the return value).

    • `help()` starts an interactive help environment.

    • It is common to use the `help` command a lot to remind oneself of the syntax and semantic of commands.

      • In [14]:
      help(isinstance)

      Help on built-in function isinstance in module builtins:

isinstance(...)
    isinstance(object, class-or-type-or-tuple) -> bool
    
    Return whether an object is an instance of a class or of a subclass thereof.
    With a type as second argument, return whether that is the object's type.
    The form using a tuple, isinstance(x, (A, B, ...)), is a shortcut for
    isinstance(x, A) or isinstance(x, B) or ... (etc.).
      In [15]:
      import math
help(math.sin)

      Help on built-in function sin in module math:

sin(...)
    sin(x)
    
    Return the sine of x (measured in radians).
      In [16]:
      help(math)

      Help on module math:

NAME
    math

MODULE REFERENCE
    http://docs.python.org/3.4/library/math
    
    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

DESCRIPTION
    This module is always available.  It provides access to the
    mathematical functions defined by the C standard.

FUNCTIONS
    acos(...)
        acos(x)
        
        Return the arc cosine (measured in radians) of x.
    
    acosh(...)
        acosh(x)
        
        Return the inverse hyperbolic cosine of x.
    
    asin(...)
        asin(x)
        
        Return the arc sine (measured in radians) of x.
    
    asinh(...)
        asinh(x)
        
        Return the inverse hyperbolic sine of x.
    
    atan(...)
        atan(x)
        
        Return the arc tangent (measured in radians) of x.
    
    atan2(...)
        atan2(y, x)
        
        Return the arc tangent (measured in radians) of y/x.
        Unlike atan(y/x), the signs of both x and y are considered.
    
    atanh(...)
        atanh(x)
        
        Return the inverse hyperbolic tangent of x.
    
    ceil(...)
        ceil(x)
        
        Return the ceiling of x as an int.
        This is the smallest integral value >= x.
    
    copysign(...)
        copysign(x, y)
        
        Return a float with the magnitude (absolute value) of x but the sign 
        of y. On platforms that support signed zeros, copysign(1.0, -0.0) 
        returns -1.0.
    
    cos(...)
        cos(x)
        
        Return the cosine of x (measured in radians).
    
    cosh(...)
        cosh(x)
        
        Return the hyperbolic cosine of x.
    
    degrees(...)
        degrees(x)
        
        Convert angle x from radians to degrees.
    
    erf(...)
        erf(x)
        
        Error function at x.
    
    erfc(...)
        erfc(x)
        
        Complementary error function at x.
    
    exp(...)
        exp(x)
        
        Return e raised to the power of x.
    
    expm1(...)
        expm1(x)
        
        Return exp(x)-1.
        This function avoids the loss of precision involved in the direct evaluation of exp(x)-1 for small x.
    
    fabs(...)
        fabs(x)
        
        Return the absolute value of the float x.
    
    factorial(...)
        factorial(x) -> Integral
        
        Find x!. Raise a ValueError if x is negative or non-integral.
    
    floor(...)
        floor(x)
        
        Return the floor of x as an int.
        This is the largest integral value <= x.
    
    fmod(...)
        fmod(x, y)
        
        Return fmod(x, y), according to platform C.  x % y may differ.
    
    frexp(...)
        frexp(x)
        
        Return the mantissa and exponent of x, as pair (m, e).
        m is a float and e is an int, such that x = m * 2.**e.
        If x is 0, m and e are both 0.  Else 0.5 <= abs(m) < 1.0.
    
    fsum(...)
        fsum(iterable)
        
        Return an accurate floating point sum of values in the iterable.
        Assumes IEEE-754 floating point arithmetic.
    
    gamma(...)
        gamma(x)
        
        Gamma function at x.
    
    hypot(...)
        hypot(x, y)
        
        Return the Euclidean distance, sqrt(x*x + y*y).
    
    isfinite(...)
        isfinite(x) -> bool
        
        Return True if x is neither an infinity nor a NaN, and False otherwise.
    
    isinf(...)
        isinf(x) -> bool
        
        Return True if x is a positive or negative infinity, and False otherwise.
    
    isnan(...)
        isnan(x) -> bool
        
        Return True if x is a NaN (not a number), and False otherwise.
    
    ldexp(...)
        ldexp(x, i)
        
        Return x * (2**i).
    
    lgamma(...)
        lgamma(x)
        
        Natural logarithm of absolute value of Gamma function at x.
    
    log(...)
        log(x[, base])
        
        Return the logarithm of x to the given base.
        If the base not specified, returns the natural logarithm (base e) of x.
    
    log10(...)
        log10(x)
        
        Return the base 10 logarithm of x.
    
    log1p(...)
        log1p(x)
        
        Return the natural logarithm of 1+x (base e).
        The result is computed in a way which is accurate for x near zero.
    
    log2(...)
        log2(x)
        
        Return the base 2 logarithm of x.
    
    modf(...)
        modf(x)
        
        Return the fractional and integer parts of x.  Both results carry the sign
        of x and are floats.
    
    pow(...)
        pow(x, y)
        
        Return x**y (x to the power of y).
    
    radians(...)
        radians(x)
        
        Convert angle x from degrees to radians.
    
    sin(...)
        sin(x)
        
        Return the sine of x (measured in radians).
    
    sinh(...)
        sinh(x)
        
        Return the hyperbolic sine of x.
    
    sqrt(...)
        sqrt(x)
        
        Return the square root of x.
    
    tan(...)
        tan(x)
        
        Return the tangent of x (measured in radians).
    
    tanh(...)
        tanh(x)
        
        Return the hyperbolic tangent of x.
    
    trunc(...)
        trunc(x:Real) -> Integral
        
        Truncates x to the nearest Integral toward 0. Uses the __trunc__ magic method.

DATA
    e = 2.718281828459045
    pi = 3.141592653589793

FILE
    /Users/fangohr/anaconda/lib/python3.4/lib-dynload/math.so

      The `help` function needs to be given the name of an object (which must exist in the current name space). For example pyhelp(math.sqrt) will not work if the `math` module has not been imported before

      In [17]:
      help(math.sqrt)

      Help on built-in function sqrt in module math:

sqrt(...)
    sqrt(x)
    
    Return the square root of x.
      In [18]:
      import math
help(math.sqrt)

      Help on built-in function sqrt in module math:

sqrt(...)
    sqrt(x)
    
    Return the square root of x.

      Instead of importing the module, we could also have given the string of `math.sqrt` to the help function, i.e.:

      In [19]:
      help('math.sqrt')

      Help on built-in function sqrt in math:

math.sqrt = sqrt(...)
    sqrt(x)
    
    Return the square root of x.

      `help` is a function which gives information about the object which is passed as its argument. Most things in Python (classes, functions, modules, etc.) are objects, and therefor can be passed to help. There are, however, some things on which you might like to ask for help, which are not existing Python objects. In such cases it is often possible to pass a string containing the name of the thing or concept to help, for example

      • `help(’modules’)` will generate a list of all modules which can be imported into the current interpreter. Note that help(modules) (note absence of quotes) will result in a NameError (unless you are unlucky enough to have a variable called modules floating around, in which case you will get help on whatever that variable happens to refer to.)

      • `help(’some_module’)`, where some_module is a module which has not been imported yet (and therefor isn’t an object yet), will give you that module’s help information.

      • `help(’some_keyword’)`: For example `and`, `if` or `print` (i.e. `help(’and’)`, `help(’if’)` and `help(’print’)`). These are special words recognized by Python: they are not objects and thus cannot be passed as arguments to help. Passing the name of the keyword as a string to help works, but only if you have Python’s HTML documentation installed, and the interpreter has been made aware of its location by setting the environment variable PYTHONDOCS.

      Docstrings

      The command `help()` accesses the documentation strings of objects.

      Any literal string apparing as the first item in the definition of a class, function, method or module, is taken to be its docstring.

      `help` includes the docstring in the information it displays about the object.

      In addition to the docstring it may display some other information, for example, in the case of functions, it displays the function’s signature.

      The docstring is stored in the object’s `__doc__` attribute.

      In [20]:
      help(math.sin)

      Help on built-in function sin in module math:

sin(...)
    sin(x)
    
    Return the sine of x (measured in radians).
      In [21]:
      print(math.sin.__doc__)

      sin(x)

Return the sine of x (measured in radians).

      For user-defined functions, classes, types, modules, …), one should always provide a docstring.

      Documenting a user-provided function:

      In [22]:
      def power2and3(x):
    """Returns the tuple (x**2, x**3)"""
    return x**2 ,x**3

power2and3(2)
      Out[22]:
      (4, 8)
      In [23]:
      power2and3(4.5)
      Out[23]:
      (20.25, 91.125)
      In [24]:
      power2and3(0+1j)
      Out[24]:
      ((-1+0j), (-0-1j))
      In [25]:
      help(power2and3)

      Help on function power2and3 in module __main__:

power2and3(x)
    Returns the tuple (x**2, x**3)
      In [26]:
      print(power2and3.__doc__)

      Returns the tuple (x**2, x**3)