4. Introspection#
A Python code can ask and answer questions about itself and the objects it is manipulating.
4.1. 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
diris given an argument (i.e.dir(<object>), then it inspects the namespace of the object which it was passed.
For example:
# NBVAL_IGNORE_OUTPUT
apples = ['Cox', 'Braeburn', 'Jazz']
dir(apples)
['__add__',
'__class__',
'__contains__',
'__delattr__',
'__delitem__',
'__dir__',
'__doc__',
'__eq__',
'__format__',
'__ge__',
'__getattribute__',
'__getitem__',
'__gt__',
'__hash__',
'__iadd__',
'__imul__',
'__init__',
'__init_subclass__',
'__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']
# NBVAL_IGNORE_OUTPUT
dir()
['In',
'Out',
'_',
'_1',
'__',
'___',
'__builtin__',
'__builtins__',
'__doc__',
'__loader__',
'__name__',
'__package__',
'__spec__',
'_dh',
'_i',
'_i1',
'_i2',
'_ih',
'_ii',
'_iii',
'_oh',
'apples',
'exit',
'get_ipython',
'quit']
# NBVAL_IGNORE_OUTPUT
name = "Peter"
dir(name)
['__add__',
'__class__',
'__contains__',
'__delattr__',
'__dir__',
'__doc__',
'__eq__',
'__format__',
'__ge__',
'__getattribute__',
'__getitem__',
'__getnewargs__',
'__gt__',
'__hash__',
'__init__',
'__init_subclass__',
'__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']
4.1.1. 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.)
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
4.2. type#
The type(<object>)command returns the type of an object:
type(1)
int
type(1.0)
float
type("Python")
str
import math
type(math)
module
type(math.sin)
builtin_function_or_method
4.3. isinstance#
isinstance(<object>, <typespec>) 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.
isinstance(2,int)
True
isinstance(2.,int)
False
isinstance(a,int) # a is an instance of my_int
True
type(a)
__main__.my_int
4.4. help#
The
help(<object>)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,helpwill 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
helpcommand a lot to remind oneself of the syntax and semantic of commands.
help(isinstance)
Help on built-in function isinstance in module builtins:
isinstance(obj, class_or_tuple, /)
Return whether an object is an instance of a class or of a subclass thereof.
A tuple, as in ``isinstance(x, (A, B, ...))``, may be given as the target to
check against. This is equivalent to ``isinstance(x, A) or isinstance(x, B)
or ...`` etc.
# NBVAL_IGNORE_OUTPUT
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).
# NBVAL_IGNORE_OUTPUT
help(math)
Help on module math:
NAME
math
MODULE REFERENCE
https://docs.python.org/3.6/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 Integral.
This is the smallest integer >= 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 Integral.
This is the largest integer <= 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.
gcd(...)
gcd(x, y) -> int
greatest common divisor of x and y
hypot(...)
hypot(x, y)
Return the Euclidean distance, sqrt(x*x + y*y).
isclose(...)
isclose(a, b, *, rel_tol=1e-09, abs_tol=0.0) -> bool
Determine whether two floating point numbers are close in value.
rel_tol
maximum difference for being considered "close", relative to the
magnitude of the input values
abs_tol
maximum difference for being considered "close", regardless of the
magnitude of the input values
Return True if a is close in value to b, and False otherwise.
For the values to be considered close, the difference between them
must be smaller than at least one of the tolerances.
-inf, inf and NaN behave similarly to the IEEE 754 Standard. That
is, NaN is not close to anything, even itself. inf and -inf are
only close to themselves.
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
inf = inf
nan = nan
pi = 3.141592653589793
tau = 6.283185307179586
FILE
/Users/fangohr/anaconda3/lib/python3.6/lib-dynload/math.cpython-36m-darwin.so
The help function needs to be given the name of an object (which must exist in the current name space). For example help(math.sqrt) will not work if the math module has not been imported before.
# NBVAL_IGNORE_OUTPUT
help(math.sqrt)
Help on built-in function sqrt in module math:
sqrt(...)
sqrt(x)
Return the square root of x.
# NBVAL_IGNORE_OUTPUT
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.:
# NBVAL_IGNORE_OUTPUT
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 exampleand,iforprint(i.e.help(’and’),help(’if’)andhelp(’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.
4.5. Docstrings#
The command help(<object>) 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.
# NBVAL_IGNORE_OUTPUT
help(math.sin)
Help on built-in function sin in module math:
sin(...)
sin(x)
Return the sine of x (measured in radians).
# NBVAL_IGNORE_OUTPUT
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:
def power2and3(x):
"""Returns the tuple (x**2, x**3)"""
return x**2 ,x**3
power2and3(2)
(4, 8)
power2and3(4.5)
(20.25, 91.125)
power2and3(0+1j)
((-1+0j), (-0-1j))
help(power2and3)
Help on function power2and3 in module __main__:
power2and3(x)
Returns the tuple (x**2, x**3)
print(power2and3.__doc__)
Returns the tuple (x**2, x**3)