1 .TH PYTHON "1" "$Date$"
3 .\" To view this file while editing, run it through groff:
4 .\" groff -Tascii -man python.man | less
7 python \- an interpreted, interactive, object-oriented programming language
73 Python is an interpreted, interactive, object-oriented programming
74 language that combines remarkable power with very clear syntax.
75 For an introduction to programming in Python you are referred to the
77 The Python Library Reference documents built-in and standard types,
78 constants, functions and modules.
79 Finally, the Python Reference Manual describes the syntax and
80 semantics of the core language in (perhaps too) much detail.
81 (These documents may be located via the
82 .B "INTERNET RESOURCES"
83 below; they may be installed on your system as well.)
85 Python's basic power can be extended with your own modules written in
87 On most systems such modules may be dynamically loaded.
88 Python is also adaptable as an extension language for existing
90 See the internal documentation for hints.
92 Documentation for installed Python modules and packages can be
96 .SH COMMAND LINE OPTIONS
99 Specify the command to execute (see next section).
100 This terminates the option list (following options are passed as
101 arguments to the command).
104 Turn on parser debugging output (for wizards only, depending on
105 compilation options).
108 Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
109 the behavior of the interpreter.
112 Prints the usage for the interpreter executable and exits.
115 When a script is passed as first argument or the \fB\-c\fP option is
116 used, enter interactive mode after executing the script or the
117 command. It does not read the $PYTHONSTARTUP file. This can be
118 useful to inspect global variables or a stack trace when a script
121 .BI "\-m " module-name
124 for the named module and runs the corresponding
129 Turn on basic optimizations. This changes the filename extension for
130 compiled (bytecode) files from
132 to \fI.pyo\fP. Given twice, causes docstrings to be discarded.
135 Division control; see PEP 238. The argument must be one of "old" (the
136 default, int/int and long/long return an int or long), "new" (new
137 division semantics, i.e. int/int and long/long returns a float),
138 "warn" (old division semantics with a warning for int/int and
139 long/long), or "warnall" (old division semantics with a warning for
140 all use of the division operator). For a use of "warnall", see the
141 Tools/scripts/fixdiv.py script.
144 Disable the import of the module
146 and the site-dependent manipulations of
151 Issue a warning when a source file mixes tabs and spaces for
152 indentation in a way that makes it depend on the worth of a tab
153 expressed in spaces. Issue an error when the option is given twice.
156 Force stdin, stdout and stderr to be totally unbuffered. On systems
157 where it matters, also put stdin, stdout and stderr in binary mode.
158 Note that there is internal buffering in xreadlines(), readlines() and
159 file-object iterators ("for line in sys.stdin") which is not
160 influenced by this option. To work around this, you will want to use
161 "sys.stdin.readline()" inside a "while 1:" loop.
164 Print a message each time a module is initialized, showing the place
165 (filename or built-in module) from which it is loaded. When given
166 twice, print a message for each file that is checked for when
167 searching for a module. Also provides information on module cleanup
171 Prints the Python version number of the executable and exits.
174 Warning control. Python sometimes prints warning message to
176 A typical warning message has the following form:
177 .IB file ":" line ": " category ": " message.
178 By default, each warning is printed once for each source line where it
179 occurs. This option controls how often warnings are printed.
182 options may be given; when a warning matches more than one
183 option, the action for the last matching option is performed.
186 options are ignored (a warning message is printed about invalid
187 options when the first warning is issued). Warnings can also be
188 controlled from within a Python program using the
194 is one of the following
196 strings (or a unique abbreviation):
198 to ignore all warnings;
200 to explicitly request the default behavior (printing each warning once
203 to print a warning each time it occurs (this may generate many
204 messages if a warning is triggered repeatedly for the same source
205 line, such as inside a loop);
207 to print each warning only the first time it occurs in each
210 to print each warning only the first time it occurs in the program; or
212 to raise an exception instead of printing a warning message.
217 .IB action : message : category : module : line.
220 is as explained above but only applies to messages that match the
221 remaining fields. Empty fields match all values; trailing empty
222 fields may be omitted. The
224 field matches the start of the warning message printed; this match is
225 case-insensitive. The
227 field matches the warning category. This must be a class name; the
228 match test whether the actual warning category of the message is a
229 subclass of the specified warning category. The full class name must
232 field matches the (fully-qualified) module name; this match is
235 field matches the line number, where zero matches all line numbers and
236 is thus equivalent to an omitted line number.
239 Skip the first line of the source. This is intended for a DOS
240 specific hack only. Warning: the line numbers in error messages will
244 Warn about Python 3.x incompatibilities that 2to3 cannot trivially fix.
245 .SH INTERPRETER INTERFACE
246 The interpreter interface resembles that of the UNIX shell: when
247 called with standard input connected to a tty device, it prompts for
248 commands and executes them until an EOF is read; when called with a
249 file name argument or with a file as standard input, it reads and
256 it executes the Python statement(s) given as
260 may contain multiple statements separated by newlines.
261 Leading whitespace is significant in Python statements!
262 In non-interactive mode, the entire input is parsed before it is
265 If available, the script name and additional arguments thereafter are
266 passed to the script in the Python variable
268 which is a list of strings (you must first
270 to be able to access it).
271 If no script name is given,
273 is an empty string; if
279 Note that options interpreted by the Python interpreter itself
283 In interactive mode, the primary prompt is `>>>'; the second prompt
284 (which appears when a command is not complete) is `...'.
285 The prompts can be changed by assignment to
289 The interpreter quits when it reads an EOF at a prompt.
290 When an unhandled exception occurs, a stack trace is printed and
291 control returns to the primary prompt; in non-interactive mode, the
292 interpreter exits after printing the stack trace.
293 The interrupt signal raises the
294 .I Keyboard\%Interrupt
295 exception; other UNIX signals are not caught (except that SIGPIPE is
296 sometimes ignored, in favor of the
298 exception). Error messages are written to stderr.
299 .SH FILES AND DIRECTORIES
300 These are subject to difference depending on local installation
301 conventions; ${prefix} and ${exec_prefix} are installation-dependent
302 and should be interpreted as for GNU software; they may be the same.
303 The default for both is \fI/usr/local\fP.
304 .IP \fI${exec_prefix}/bin/python\fP
305 Recommended location of the interpreter.
307 .I ${prefix}/lib/python<version>
309 .I ${exec_prefix}/lib/python<version>
311 Recommended locations of the directories containing the standard
315 .I ${prefix}/include/python<version>
317 .I ${exec_prefix}/include/python<version>
319 Recommended locations of the directories containing the include files
320 needed for developing Python extensions and embedding the
323 .IP \fI~/.pythonrc.py\fP
324 User-specific initialization file loaded by the \fIuser\fP module;
325 not used by default or by most applications.
326 .SH ENVIRONMENT VARIABLES
328 Change the location of the standard Python libraries. By default, the
329 libraries are searched in ${prefix}/lib/python<version> and
330 ${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
331 are installation-dependent directories, both defaulting to
332 \fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value
333 replaces both ${prefix} and ${exec_prefix}. To specify different values
334 for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
336 Augments the default search path for module files.
337 The format is the same as the shell's $PATH: one or more directory
338 pathnames separated by colons.
339 Non-existent directories are silently ignored.
340 The default search path is installation dependent, but generally
341 begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
342 The default search path is always appended to $PYTHONPATH.
343 If a script argument is given, the directory containing the script is
344 inserted in the path in front of $PYTHONPATH.
345 The search path can be manipulated from within a Python program as the
349 If this is the name of a readable file, the Python commands in that
350 file are executed before the first prompt is displayed in interactive
352 The file is executed in the same name space where interactive commands
353 are executed so that objects defined or imported in it can be used
354 without qualification in the interactive session.
355 You can also change the prompts
361 Set this to a non-empty string to cause the \fItime\fP module to
362 require dates specified as strings to include 4-digit years, otherwise
363 2-digit years are converted based on rules described in the \fItime\fP
364 module documentation.
366 If this is set to a non-empty string it is equivalent to specifying
367 the \fB\-O\fP option. If set to an integer, it is equivalent to
368 specifying \fB\-O\fP multiple times.
370 If this is set to a non-empty string it is equivalent to specifying
371 the \fB\-d\fP option. If set to an integer, it is equivalent to
372 specifying \fB\-d\fP multiple times.
374 If this is set to a non-empty string it is equivalent to specifying
375 the \fB\-i\fP option.
377 If this is set to a non-empty string it is equivalent to specifying
378 the \fB\-u\fP option.
380 If this is set to a non-empty string it is equivalent to specifying
381 the \fB\-v\fP option. If set to an integer, it is equivalent to
382 specifying \fB\-v\fP multiple times.
384 The Python Software Foundation: http://www.python.org/psf
385 .SH INTERNET RESOURCES
386 Main website: http://www.python.org/
388 Documentation: http://docs.python.org/
390 Community website: http://starship.python.net/
392 Developer resources: http://www.python.org/dev/
394 FTP: ftp://ftp.python.org/pub/python/
396 Module repository: http://www.vex.net/parnassus/
398 Newsgroups: comp.lang.python, comp.lang.python.announce
400 Python is distributed under an Open Source license. See the file
401 "LICENSE" in the Python source distribution for information on terms &
402 conditions for accessing and otherwise using Python and for a
403 DISCLAIMER OF ALL WARRANTIES.