Using Help

Using Help

Python is a computer language, not a human language. As a result, you won’t speak it fluently at first. If you think about it for a moment, it makes sense that you won’t speak Python fluently (and as with most human languages, you won’t know every command even after you do become fluent). Having  to discover Python commands a little at a time is the same thing that hap- pens when you learn to speak another human language. If you normally speak English and try to say something in German, you find that you must have some sort of guide to help you along. Otherwise, anything you say is gibberish and people will look at you quite oddly. Even if you manage to say something that makes sense, it may not be what you want. You might go to

a restaurant and order hot hubcaps for dinner when what you really wanted was a steak.

Likewise, when you try to speak Python, you need a guide to help you. Fortu- nately, Python is quite accommodating and provides immediate help to keep you from ordering something you really don’t want. The help provided inside Python works at two levels:

• Help mode, in which you can browse the available commands
• Direct help, in which you ask about a specific command

There isn’t a correct way to use help — just the method that works best for you at a particular time. The following sections describe how to obtain help.

Getting into help mode

When you first start Python, you see a display similar to the one shown in Figure 3-1. Notice that Python provides you with four commands at the outset (which is actually your first piece of help information):

• help
• copyright
• credits
• license

All four commands provide you with help, of a sort, about Python. For exam- ple, the copyright() command tells you about who holds the right to copy, license, or otherwise distribute Python. The credits() command tells you

who put Python together. The license() command describes the usage agreement between you and the copyright holder. However, the command you most want to know about is simply help().

To enter help mode, type help( ) and press Enter. Notice that you must include the parentheses after the command even though they don’t appear in the help text. Every Python command has parentheses associated with it.

After you enter this command, Python goes into help mode and you see a dis- play similar to the one shown in Figure 3-3.

Figure 3-3: You ask Python about other commands

in help mode.

You can always tell that you’re in help mode by the help> prompt that you see in the Python window. As long as you see the help> prompt, you know that you’re in help mode.

Asking for help

To obtain help, you need to know what question to ask. The initial help mes- sage that you see when you go into help mode (refer to Figure 3-3) provides some helpful tips about the kinds of questions you can ask. If you want to explore Python, the three basic topics are

• modules
• keywords
• topics

The first two topics won’t tell you much for now. You won’t need the modules topic until Chapter 10. The keywords topic will begin proving useful in Chapter 4. However, the topics keyword is already useful because it helps you understand where to begin your Python adventure. To see what topics  are available, type topics and press Enter. You see a list of topics similar to those shown in Figure 3-4.

Figure 3-4:

The topics help topic provides you with a starting point for

your Python adventure.

When you see a topic that you like, such as FUNCTIONS, simply type that topic and press Enter. To see how this works, type FUNCTIONS and press Enter (you must type the word in uppercase — don’t worry, Python won’t think you’re shouting). You see help information similar to that shown in Figure 3-5.

Figure 3-5:

You must

use uppercase

when requesting

topic information.

As you work through examples in the book, you use commands that look interesting, and you might want more information about them. For example, in the “Seeing the result” section of this chapter, you use the print() com- mand. To see more information about the print() command, type print and press Enter (notice that you don’t include the parentheses this time because you’re requesting help about print(), not actually using the command).

Figure 3-6 shows typical help information for the print() command.

Figure 3-6:

Request

com­ mand help information by typing the command

using whatever case it actually uses.

Unfortunately, reading the help information probably doesn’t help much yet because you need to know more about Python. However, you can ask for more information. For example, you might wonder what sys.stdout means — and the help topic certainly doesn’t tell you anything about it. Type sys.stdout and press Enter. You see the help information shown in Figure 3-7.

Figure 3-7: You can ask for help on the help you

receive.

You may still not find the information as helpful as you need, but at least you know a little more. In this case, help has a lot to say and it can’t all fit on one screen. Notice the following entry at the bottom of the screen:

To see the additional information, press the spacebar. The next page of help appears. As you read to the bottom of each page of help, you can press the spacebar to see the next page. The pages don’t go away — you can scroll up to see previous material.

Leaving help mode

At some point, you need to leave help mode to perform useful work. All you have to do is press Enter without typing anything. When you press Enter, you see a message about leaving help, and then the prompt changes to the stan- dard Python prompt, as shown in Figure 3-8.

Figure 3-8: Exit help mode by pressing Enter with­ out typing anything.

Obtaining help directly

Entering help mode isn’t necessary unless you want to browse, which is always a good idea, or unless you don’t actually know what you need to find. If you have a good idea of what you need, all you need to do is ask for help directly (a really nice thing for Python to do). So, instead of fiddling with  help mode, you simply type the word help, followed by a left parenthesis and

single quote, whatever you want to find, another single quote, and the right parenthesis. For example, if you want to know more about the print() com- mand, you type help(‘print’) and press Enter. Figure 3-9 shows typical output when you access help this way.

Figure 3-9:

Python makes it possible to obtain help whenever you need

it without leaving the Python prompt.

You can browse at the Python prompt, too. For example, when you type help(‘topics’) and press Enter, you see a list of topics like the one that appears in Figure 3-10. You can compare this list with the one shown in Figure 3-4. The two lists are identical, even though you typed one while in help mode and the other while at the Python prompt.

Figure 3-10: It’s possible to browse at the Python prompt if you really want to.

You might wonder why Python has a help mode at all if you can get the same results at the Python prompt. The answer is convenience. It’s easier to browse in the help mode. In addition, even though you don’t do a lot of extra typing

at the prompt, you do perform less typing while in help mode. Help mode also provides additional helps, such as by listing commands that you can type, as shown in Figure 3-3. So you have all kinds of good reasons to enter help mode when you plan to ask Python a lot of help questions.

No matter where you ask for help, you need to observe the correct capitaliza- tion of help topics. For example, if you want general information about func- tions, you must type help(‘FUNCTIONS’) and not help(‘Functions’) or help(‘functions’). When you use the wrong capitalization, Python will tell you that it doesn’t know what you mean or that it couldn’t find the help topic. It won’t know to tell you that you used the wrong capitalization. Someday computers will know what you meant to type, rather than what you did type, but  that  hasn’t  happened  yet.

Closing the Command Line

Eventually, you want to leave Python. Yes, it’s hard to believe, but people have other things to do besides playing with Python all day long. You have two standard methods for leaving Python and a whole bunch of nonstandard methods. Generally, you want to use one of the standard methods to ensure that Python behaves as you expect it to, but the nonstandard methods work just fine when you simply want to play around with Python and not perform any productive work. The two standard methods are

• quit()
• exit()

Either of these methods will close the interactive version of Python. The shell

(the Python program) is designed to allow either command.

Both of these commands can accept an optional argument. For example, you can type quit(5) or exit(5) and press Enter to exit the shell. The numeric argument sets the command prompt’s ERRORLEVEL environment variable, which you can then intercept at the command line or as part of a batch file.

Standard practice is to simply use quit() or exit() when nothing has gone wrong with the application. To see this way of exiting at work, you must

1. Open a command prompt or

You see a prompt.

2. Type Python and press Enter to start

You see the Python prompt.

3. Type quit(5) and press Enter.

You see the prompt again.

4. Type echo %ERRORLEVEL% and press Enter.

You see the error code, as shown in Figure 3-11. When working with plat- forms other than Windows, you may need to type something other than echo %ERRORLEVEL%. For example, when working with a bash script, you  type  echo $ instead.

Figure 3-11: Add an error code when needed to tell others the Python exit status.

One of the most common nonstandard exit methods is to simply click the command prompt’s or terminal’s Close button. Using this approach means that your application may not have time to perform any required cleanup, which can result in odd behaviors. It’s always better to close Python using an expected approach if you’ve been doing anything more than simply browsing.

You also have access to a number of other commands for closing the command prompt when needed. In most cases, you won’t need these special commands, so you can skip the rest of this section if desired.

When you use quit() or exit(), Python performs a number of tasks to ensure that everything is neat and tidy before the session ends. If you sus- pect that a session might not end properly anyway, you can always rely on one of these two commands to close the command prompt:

• exit()
• _exit()

Both of these commands are used in emergency situations only. The first, sys.exit(), provides special error-handling features that you discover in Chapter 9. The second, os._exit(), exits Python without performing any of the usual cleanup tasks. In both cases, you must import the required module, either sys or os, before you can use the associated command. Consequently, to use the sys.exit() command, you actually use this code:

You must provide an error code when using os._exit() because this command is used only when an extreme error has occurred. The call to this command will fail if you don’t provide an error code. To use the os._ exit() command, you actually use this code (where the error code is 5):

Chapter 10 discusses importing modules in detail. For now, just know that these two commands are for special uses only and you won’t normally use them in an application.