Exploring Python Modules and Objects

You can interactively explore modules and objects directly from the Python interpreter. This is an underrated feature that’s easy to overlook, especially if you’re switching to Python from another language.

Many programming languages make it difficult to inspect a package or class without consulting online documentation or learning interface definitions by heart.

Python is different—an effective developer will spend quite a bit of time in REPL sessions working interactively with the Python interpreter. For example, I often do this to work out little snippets of code and logic that I then copy and paste into a Python file I’m working on in my editor.

In this chapter you’ll learn two simple techniques you can use to explore Python classes and methods interactively from the interpreter.

These techniques will work on any Python install—just start up the Python interpreter with the python command from the commandline and fire away. This is great for debugging sessions on systems where you don’t have access to a fancy editor or IDE, for example, because you’re working over the network in a terminal session.

Ready? Here we go! Imagine you’re writing a program that uses Python’s datetime module from the standard library. How can you find out what functions or classes this module exports, and which methods and attributes can you find on its classes?

Consulting a search engine or looking up the official Python documentation on the web would be one way to do it. But Python’s builtin dir() function lets you access this information directly from the Python REPL:

>>> import datetime
>>> dir(datetime)
['MAXYEAR', 'MINYEAR', '__builtins__', '__cached__',
'__doc__', '__file__', '__loader__', '__name__',
'__package__', '__spec__', '_divide_and_round',
'date', 'datetime', 'datetime_CAPI', 'time',
'timedelta', 'timezone', 'tzinfo']

In the example above, I first imported the datetime module from the standard library and then inspected it with the dir() function. Calling dir() on a module gives you an alphabetized list of the names and attributes the module provides.

Because “everything” is an object in Python, the same technique works not only on the module itself, but also on the classes and data structures exported by the module.
意思就是不仅仅模块其他的类和数据结构都有同样的技术方法

In fact, you can keep drilling down into the module by calling dir() again on individual objects that look interesting. For example, here’s how you’d inspect the datetime.date class:

>>> dir(datetime.date)
['__add__', '__class__', ..., 'day', 'fromordinal',
'isocalendar', 'isoformat', 'isoweekday', 'max',
'min', 'month', 'replace', 'resolution', 'strftime',
'timetuple', 'today', 'toordinal', 'weekday', 'year']

As you can see, dir() gives you a quick overview of what’s available on a module or class. If you don’t remember the exact spelling for a particular class or function, then maybe that’s all you need to keep going without interrupting your coding flow.

Sometimes calling dir() on an object will result in too much information—on a complex module or class you’ll get a long printout that’s difficult to read quickly. Here’s a little trick you can use to filter down the list of attributes to just the ones you’re interested in:

>>> [_ for _ in dir(datetime) if 'date' in _.lower()]
['date', 'datetime', 'datetime_CAPI']

这里也演示了在for loop中的_的用法

Here, I used a list comprehension to filter down the results of the dir(datetime) call to only contain names that include the word “date.” Notice how I called the lower() method on each name to make sure the filtering is case-insensitive.

Getting a raw listing of the attributes on an object won’t always be enough information to solve the problem at hand. So, how can you get more info and further details on the functions and classes exported by the datetime module?
之前只是获取对象中的属性和方法，现在的话就是想了解具体方法等的如何使用。

Python’s built-in help() function will come to your rescue. With it, you can invoke Python’s interactive help system to browse the autogenerated documentation for any Python object:

>>> help(datetime)

If you run the above example in a Python interpreter session, your terminal will display a text-based help screen for the datetime module, looking somewhat like this:

Help on module datetime:

NAME
  datetime - Fast implementation of the datetime type.

CLASSES
  builtins.object
    date
      datetime
    time

You can use the cursor up and down keys to scroll through the documentation. Alternatively you can also hit the space bar to scroll down a few lines at once. To leave this interactive help mode you’ll need to press the q key. This will take you back to the interpreter prompt. Nice feature, right?

By the way, you can call help() on arbitrary Python objects, including other built-in functions and your own Python classes. The Python interpreter automatically generates this documentation from the attributes on an object and its docstring (if available.) The examples below are all valid uses of the help function:

>>> help(datetime.date)
>>> help(datetime.date.fromtimestamp)
>>> help(dir)

Of course, dir() and help() won’t replace nicely formatted HTML documentation, the powers of a search engine, or a Stack Overflow search. But they’re great tools for quickly looking things up without having to switch away from the Python interpreter. They’re also available offline and work without an internet connection—which can be very useful in a pinch.

Key Takeaways

• Use the built-in dir() function to interactively explore Python modules and classes from an interpreter session.
• The help() built-in lets you browse through the documentation right from your interpreter (hit q to exit.)