How To Introspect ( Look Inside ) Python Objects In IPython

IPython provide some magic command ( ?, ??, %pdef, %pdoc, %psource, %pfile ) for you to look inside python objects(  variable, function, class. module, object etc ). In this article i will tell you how to use them to introspect python objects in IPython. Below example need an ipython environment, if you do not install one, you can read article How To Use IPython Jupyter Notebook To Develop Python Code or if you want run below example in an isolated python virtual environment you can read article How To Start Jupyter Notebook In Anaconda Python Virtual Environment.

Open a terminal and input command ipython to get into ipython interactive environment.

(env_jupyter_example) C:\Users\song zhao>ipython
Python 3.7.6 (default, Jan  8 2020, 20:23:39) [MSC v.1916 64 bit (AMD64)]
Type 'copyright', 'credits' or 'license' for more information
IPython 7.12.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

1. Introspect Python Object With One Question Mark ? After It.

When you add one question mark ( ? ) after a python variable, function or class etc, it will display some useful and short description message of that python object.

1.1 Introspect Python Variable With ?.

Define a string variable like below.

In [1]: message  = 'hello world'

Add a question mark ( ? ) after the variable to show it’s description message.

In [2]: message?
Type:        str
String form: hello world
Length:      11
Docstring:
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

1.2 Introspect Python Function With ?.

Define a python function in ipython interactive console.

In [5]: def hello_world(username):
   ...:     print('hello ', username,', you are welcome to ipython.')
   ...:

In [6]: hello_world('jerry')
hello  jerry , you are welcome to ipython.

Add one question mark ( ? ) at the end of the function name to get the function description message.

In [8]: hello_world?
Signature: hello_world(username)
Docstring: <no docstring>
File:      c:\users\song zhao\<ipython-input-5-f30d5bee84f0>
Type:      function

Add one question mark after system defined os.listdir fucntion.

In [22]: import os

In [23]: os.listdir?
Signature: os.listdir(path=None)
Docstring:
Return a list containing the names of the files in the directory.

path can be specified as either str, bytes, or a path-like object.  If path is bytes,
  the filenames returned will also be bytes; in all other circumstances
  the filenames returned will be str.
If path is None, uses the path='.'.
On some platforms, path may also be specified as an open file descriptor;\
  the file descriptor must refer to a directory.
  If this functionality is unavailable, using it raises NotImplementedError.

The list is in arbitrary order.  It does not include the special
entries '.' and '..' even if they are present in the directory.
Type:      builtin_function_or_method

1.3 Introspect Python Module / Class With ?.

Import a python standard module in ipython.

In [9]: import os

Add one ? at the end of os module to get it’s short description.

In [10]: os?
Type:        module
String form: <module 'os' from 'C:\\Anaconda\\lib\\os.py'>
File:        c:\anaconda\lib\os.py
Docstring:
OS routines for NT or Posix depending on what system we're on.

This exports:
  - all functions from posix or nt, e.g. unlink, stat, etc.
  - os.path is either posixpath or ntpath
  - os.name is either 'posix' or 'nt'
  - os.curdir is a string representing the current directory (always '.')
  - os.pardir is a string representing the parent directory (always '..')
  - os.sep is the (or a most common) pathname separator ('/' or '\\')
  - os.extsep is the extension separator (always '.')
  - os.altsep is the alternate pathname separator (None or '/')
  - os.pathsep is the component separator used in $PATH etc
  - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
  - os.defpath is the default search path for executables
  - os.devnull is the file path of the null device ('/dev/null', etc.)

Programs that import and use 'os' stand a better chance of being
portable between different platforms.  Of course, they must then
only use functions that are defined by all platforms (e.g., unlink
and opendir), and leave all pathname manipulation to os.path
(e.g., split and join).

2. Introspect Python Object With Two Question Mark ?? After It.

You can also add two question mark ( ?? ) after python object( variable, function, class), it will display more detail description information about the python object.

2.1 Add ?? After Python Variable.

In [1]: message = 'hello world'

In [25]: message??
Type:        str
String form: hello world
Length:      11
Docstring:
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

2.2 Add ?? After Custom Python Function.

In [5]: def hello_world(username): 
...:        print('hello ', username,', you are welcome to ipython.') 
...: 

In [26]: hello_world??
Signature: hello_world(username)
Docstring: <no docstring>
Source:
def hello_world(username):
    print('hello ', username,', you are welcome to ipython.')
File:      c:\users\song zhao\<ipython-input-5-f30d5bee84f0>
Type:      function

2.3 Add ?? After System Defined Python Function.

In [27]: import os

In [28]: os.listdir??
Signature: os.listdir(path=None)
Docstring:
Return a list containing the names of the files in the directory.

path can be specified as either str, bytes, or a path-like object.  If path is bytes,
  the filenames returned will also be bytes; in all other circumstances
  the filenames returned will be str.
If path is None, uses the path='.'.
On some platforms, path may also be specified as an open file descriptor;\
  the file descriptor must refer to a directory.
  If this functionality is unavailable, using it raises NotImplementedError.

The list is in arbitrary order.  It does not include the special
entries '.' and '..' even if they are present in the directory.
Type:      builtin_function_or_method

2.4 Add ?? After Python Module.

In [11]: os??
Type:        module
String form: <module 'os' from 'C:\\Anaconda\\lib\\os.py'>
File:        c:\anaconda\lib\os.py
Source:
r"""OS routines for NT or Posix depending on what system we're on.

This exports:
  - all functions from posix or nt, e.g. unlink, stat, etc.
  - os.path is either posixpath or ntpath
  - os.name is either 'posix' or 'nt'
  - os.curdir is a string representing the current directory (always '.')
  - os.pardir is a string representing the parent directory (always '..')
  - os.sep is the (or a most common) pathname separator ('/' or '\\')
  - os.extsep is the extension separator (always '.')
  - os.altsep is the alternate pathname separator (None or '/')
  - os.pathsep is the component separator used in $PATH etc
  - os.linesep is the line separator in text files ('\r' or '\n' or '\r\n')
  - os.defpath is the default search path for executables
  - os.devnull is the file path of the null device ('/dev/null', etc.)

Programs that import and use 'os' stand a better chance of being
portable between different platforms.  Of course, they must then
only use functions that are defined by all platforms (e.g., unlink
and opendir), and leave all pathname manipulation to os.path
(e.g., split and join).
"""

#'
import abc
import sys
import stat as st

_names = sys.builtin_module_names

# Note:  more names are added to __all__ later.
__all__ = ["altsep", "curdir", "pardir", "sep", "pathsep", "linesep",
           "defpath", "name", "path", "devnull", "SEEK_SET", "SEEK_CUR",
           "SEEK_END", "fsencode", "fsdecode", "get_exec_path", "fdopen",
           "popen", "extsep"]

def _exists(name):
    return name in globals()

def _get_exports_list(module):
    try:
        return list(module.__all__)
    except AttributeError:
        return [n for n in dir(module) if n[0] != '_']

# Any new dependencies of the os module and/or changes in path separator
# requires updating importlib as well.
if 'posix' in _names:
    name = 'posix'
    linesep = '\n'
    from posix import *
    try:
        from posix import _exit
        __all__.append('_exit')
---Return to continue, q to quit---

3. Run Ipython Magic Command To Introspect Python Object.

Besides ? and ??, ipython provide other magic command ( %pdef, %pdoc, %psource, %pfile ) for you to introspect python objects.

3.1 %pdef Can Be Used To Display Function Definition.

Run ipython magic command %pdef to get function definition. This magic command can only be used on python function or method.

In [12]: import os

In [13]: %pdef os.listdir
 os.listdir(path=None)

In [14]: %pdef hello_world
 hello_world(username)

3.2 %pdoc Can Be Used To Display Python Object’s Doc String.

This magic command can be used to any python object ( variable, function, module, class etc ).

In [18]: import os

In [19]: %pdoc os.path
Class docstring:
    Common pathname manipulations, WindowsNT/95 version.

    Instead of importing this module directly, import os and refer to this
    module as os.path.

In [29]: %pdoc hello_world
Call docstring:
    Call self as a function.

In [30]: %pdoc message
Class docstring:
    str(object='') -> str
    str(bytes_or_buffer[, encoding[, errors]]) -> str

    Create a new string object from the given object. If encoding or
    errors is specified, then the object must expose a data buffer
    that will be decoded using the given encoding and error handler.
    Otherwise, returns the result of object.__str__() (if defined)
    or repr(object).
    encoding defaults to sys.getdefaultencoding().
    errors defaults to 'strict'.

3.3 %psource Can Be Used To Display Python Object’s Source Code.

Only python function, method, module, class has source code.

In [33]: %psource hello_world
def hello_world(username):
    print('hello ', username,', you are welcome to ipython.')

In [35]: %psource os.path
# Module 'ntpath' -- common operations on WinNT/Win95 pathnames
"""Common pathname manipulations, WindowsNT/95 version.

Instead of importing this module directly, import os and refer to this
module as os.path.
"""

# strings representing various path-related bits and pieces
# These are primarily for export; internally, they are hardcoded.
# Should be set before imports for resolving cyclic dependency.
curdir = '.'
pardir = '..'
extsep = '.'
sep = '\\'
pathsep = ';'
altsep = '/'
defpath = '.;C:\\bin'
devnull = 'nul'

3.4 %pfile Can Be Used To Display Python Object Defined File.

In [48]: %pfile os.path
# Module 'ntpath' -- common operations on WinNT/Win95 pathnames
"""Common pathname manipulations, WindowsNT/95 version.

Instead of importing this module directly, import os and refer to this
module as os.path.
"""

4. Display Python Object Information In Jupyter Notebook.

Besides run above ipython magic command in ipython command line console, you can also run above magic command in jupyter notebook line cell. The python object information will be printed at the bottom of jupyter notebook web page.

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.