blob: 1564f8d7549a8a3f3b2e84a6bb75ceb98711a13d [file] [log] [blame]
Guido van Rossum97bac532001-09-05 18:57:51 +00001.TH PYTHON "1" "$Date$"
Andrew M. Kuchling3afe4f32004-10-07 12:30:54 +00002
Matthias Klose8ed25202009-03-22 13:08:22 +00003.\" To view this file while editing, run it through groff:
4.\" groff -Tascii -man python.man | less
Andrew M. Kuchling3afe4f32004-10-07 12:30:54 +00005
Guido van Rossuma7925f11994-01-26 10:20:16 +00006.SH NAME
7python \- an interpreted, interactive, object-oriented programming language
8.SH SYNOPSIS
9.B python
10[
Guido van Rossuma7925f11994-01-26 10:20:16 +000011.B \-d
12]
13[
Guido van Rossumb674baf2001-09-05 18:55:34 +000014.B \-E
15]
16[
17.B \-h
18]
19[
Guido van Rossuma7925f11994-01-26 10:20:16 +000020.B \-i
21]
22[
Andrew M. Kuchling166e6252004-10-07 12:04:50 +000023.B \-m
24.I module-name
25]
26[
Guido van Rossum4cf4de51997-09-08 04:06:15 +000027.B \-O
28]
Guido van Rossumb674baf2001-09-05 18:55:34 +000029.br
30 [
31.B -Q
32.I argument
Guido van Rossum4cf4de51997-09-08 04:06:15 +000033]
34[
Guido van Rossumb674baf2001-09-05 18:55:34 +000035.B \-S
Neil Schemenauer7d4bb9f2001-07-23 16:30:27 +000036]
37[
Guido van Rossum29d465b1998-04-10 19:36:09 +000038.B \-t
39]
40[
Guido van Rossumef5bca31994-05-03 14:15:32 +000041.B \-u
Guido van Rossuma7925f11994-01-26 10:20:16 +000042]
Guido van Rossumb674baf2001-09-05 18:55:34 +000043.br
44 [
Guido van Rossuma7925f11994-01-26 10:20:16 +000045.B \-v
46]
Guido van Rossum07c44c71998-04-10 19:46:00 +000047[
Barry Warsaw64569372000-09-15 18:39:09 +000048.B \-V
49]
Guido van Rossum1378c322000-12-19 03:21:54 +000050[
51.B \-W
52.I argument
53]
Guido van Rossumb674baf2001-09-05 18:55:34 +000054[
55.B \-x
56]
Benjamin Petersonc4431ee2009-01-09 03:05:14 +000057[
58.B \-3
59]
Guido van Rossum4cf4de51997-09-08 04:06:15 +000060.br
61 [
Guido van Rossuma7925f11994-01-26 10:20:16 +000062.B \-c
63.I command
64|
65.I script
66|
67\-
68]
69[
70.I arguments
71]
72.SH DESCRIPTION
73Python is an interpreted, interactive, object-oriented programming
74language that combines remarkable power with very clear syntax.
75For an introduction to programming in Python you are referred to the
76Python Tutorial.
77The Python Library Reference documents built-in and standard types,
78constants, functions and modules.
79Finally, the Python Reference Manual describes the syntax and
80semantics of the core language in (perhaps too) much detail.
Guido van Rossumf4a090d2000-09-01 20:36:34 +000081(These documents may be located via the
82.B "INTERNET RESOURCES"
Fred Drake4c9be9d1999-08-20 13:10:20 +000083below; they may be installed on your system as well.)
Guido van Rossuma7925f11994-01-26 10:20:16 +000084.PP
85Python's basic power can be extended with your own modules written in
86C or C++.
Guido van Rossum74faed21996-07-30 19:27:05 +000087On most systems such modules may be dynamically loaded.
Guido van Rossuma7925f11994-01-26 10:20:16 +000088Python is also adaptable as an extension language for existing
89applications.
90See the internal documentation for hints.
Andrew M. Kuchling88717f42001-04-05 14:50:40 +000091.PP
92Documentation for installed Python modules and packages can be
93viewed by running the
94.B pydoc
95program.
Guido van Rossuma7925f11994-01-26 10:20:16 +000096.SH COMMAND LINE OPTIONS
97.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +000098.BI "\-c " command
99Specify the command to execute (see next section).
100This terminates the option list (following options are passed as
101arguments to the command).
102.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000103.B \-d
104Turn on parser debugging output (for wizards only, depending on
105compilation options).
Guido van Rossum9f65ae01994-02-23 09:10:27 +0000106.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +0000107.B \-E
108Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
109the behavior of the interpreter.
110.TP
111.B \-h
112Prints the usage for the interpreter executable and exits.
113.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000114.B \-i
115When a script is passed as first argument or the \fB\-c\fP option is
116used, enter interactive mode after executing the script or the
Guido van Rossum9f65ae01994-02-23 09:10:27 +0000117command. It does not read the $PYTHONSTARTUP file. This can be
118useful to inspect global variables or a stack trace when a script
119raises an exception.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000120.TP
Andrew M. Kuchling166e6252004-10-07 12:04:50 +0000121.BI "\-m " module-name
122Searches
123.I sys.path
124for the named module and runs the corresponding
125.I .py
126file as a script.
127.TP
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000128.B \-O
129Turn on basic optimizations. This changes the filename extension for
130compiled (bytecode) files from
131.I .pyc
Fred Drake4c9be9d1999-08-20 13:10:20 +0000132to \fI.pyo\fP. Given twice, causes docstrings to be discarded.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000133.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +0000134.BI "\-Q " argument
135Division control; see PEP 238. The argument must be one of "old" (the
136default, int/int and long/long return an int or long), "new" (new
137division semantics, i.e. int/int and long/long returns a float),
138"warn" (old division semantics with a warning for int/int and
139long/long), or "warnall" (old division semantics with a warning for
140all use of the division operator). For a use of "warnall", see the
141Tools/scripts/fixdiv.py script.
142.TP
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000143.B \-S
144Disable the import of the module
145.I site
146and the site-dependent manipulations of
147.I sys.path
148that it entails.
149.TP
Guido van Rossum29d465b1998-04-10 19:36:09 +0000150.B \-t
151Issue a warning when a source file mixes tabs and spaces for
152indentation in a way that makes it depend on the worth of a tab
153expressed in spaces. Issue an error when the option is given twice.
154.TP
Guido van Rossumef5bca31994-05-03 14:15:32 +0000155.B \-u
Sjoerd Mullenderb6434f22002-08-09 13:37:31 +0000156Force stdin, stdout and stderr to be totally unbuffered. On systems
157where it matters, also put stdin, stdout and stderr in binary mode.
158Note that there is internal buffering in xreadlines(), readlines() and
159file-object iterators ("for line in sys.stdin") which is not
160influenced by this option. To work around this, you will want to use
161"sys.stdin.readline()" inside a "while 1:" loop.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000162.TP
163.B \-v
164Print a message each time a module is initialized, showing the place
Fred Drake4c9be9d1999-08-20 13:10:20 +0000165(filename or built-in module) from which it is loaded. When given
166twice, print a message for each file that is checked for when
167searching for a module. Also provides information on module cleanup
168at exit.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000169.TP
Barry Warsaw64569372000-09-15 18:39:09 +0000170.B \-V
171Prints the Python version number of the executable and exits.
172.TP
Guido van Rossum1378c322000-12-19 03:21:54 +0000173.BI "\-W " argument
174Warning control. Python sometimes prints warning message to
175.IR sys.stderr .
176A typical warning message has the following form:
177.IB file ":" line ": " category ": " message.
178By default, each warning is printed once for each source line where it
179occurs. This option controls how often warnings are printed.
180Multiple
181.B \-W
182options may be given; when a warning matches more than one
183option, the action for the last matching option is performed.
184Invalid
185.B \-W
186options are ignored (a warning message is printed about invalid
187options when the first warning is issued). Warnings can also be
188controlled from within a Python program using the
189.I warnings
190module.
191
192The simplest form of
193.I argument
194is one of the following
195.I action
196strings (or a unique abbreviation):
197.B ignore
198to ignore all warnings;
199.B default
200to explicitly request the default behavior (printing each warning once
201per source line);
202.B all
203to print a warning each time it occurs (this may generate many
204messages if a warning is triggered repeatedly for the same source
Fred Drakebd2e3b02001-07-26 21:25:58 +0000205line, such as inside a loop);
Guido van Rossum1378c322000-12-19 03:21:54 +0000206.B module
207to print each warning only only the first time it occurs in each
208module;
209.B once
210to print each warning only the first time it occurs in the program; or
211.B error
212to raise an exception instead of printing a warning message.
213
214The full form of
215.I argument
216is
217.IB action : message : category : module : line.
218Here,
219.I action
220is as explained above but only applies to messages that match the
221remaining fields. Empty fields match all values; trailing empty
222fields may be omitted. The
223.I message
224field matches the start of the warning message printed; this match is
225case-insensitive. The
226.I category
227field matches the warning category. This must be a class name; the
228match test whether the actual warning category of the message is a
229subclass of the specified warning category. The full class name must
230be given. The
231.I module
232field matches the (fully-qualified) module name; this match is
233case-sensitive. The
234.I line
235field matches the line number, where zero matches all line numbers and
236is thus equivalent to an omitted line number.
237.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +0000238.B \-x
239Skip the first line of the source. This is intended for a DOS
240specific hack only. Warning: the line numbers in error messages will
241be off by one!
Benjamin Petersonc4431ee2009-01-09 03:05:14 +0000242.TP
243.B \-3
244Warn about Python 3.x incompatibilities that 2to3 cannot trivially fix.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000245.SH INTERPRETER INTERFACE
246The interpreter interface resembles that of the UNIX shell: when
247called with standard input connected to a tty device, it prompts for
248commands and executes them until an EOF is read; when called with a
249file name argument or with a file as standard input, it reads and
250executes a
251.I script
252from that file;
253when called with
254.B \-c
255.I command,
256it executes the Python statement(s) given as
257.I command.
258Here
259.I command
260may contain multiple statements separated by newlines.
261Leading whitespace is significant in Python statements!
Matthias Klose31a58df2005-03-20 14:16:03 +0000262In non-interactive mode, the entire input is parsed before it is
Guido van Rossuma7925f11994-01-26 10:20:16 +0000263executed.
264.PP
265If available, the script name and additional arguments thereafter are
266passed to the script in the Python variable
267.I sys.argv ,
268which is a list of strings (you must first
269.I import sys
270to be able to access it).
271If no script name is given,
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000272.I sys.argv[0]
273is an empty string; if
Guido van Rossuma7925f11994-01-26 10:20:16 +0000274.B \-c
275is used,
276.I sys.argv[0]
277contains the string
278.I '-c'.
Guido van Rossum74faed21996-07-30 19:27:05 +0000279Note that options interpreted by the Python interpreter itself
Guido van Rossuma7925f11994-01-26 10:20:16 +0000280are not placed in
281.I sys.argv.
282.PP
283In interactive mode, the primary prompt is `>>>'; the second prompt
284(which appears when a command is not complete) is `...'.
285The prompts can be changed by assignment to
286.I sys.ps1
287or
288.I sys.ps2.
289The interpreter quits when it reads an EOF at a prompt.
290When an unhandled exception occurs, a stack trace is printed and
291control returns to the primary prompt; in non-interactive mode, the
292interpreter exits after printing the stack trace.
293The interrupt signal raises the
294.I Keyboard\%Interrupt
295exception; other UNIX signals are not caught (except that SIGPIPE is
296sometimes ignored, in favor of the
297.I IOError
298exception). Error messages are written to stderr.
299.SH FILES AND DIRECTORIES
300These are subject to difference depending on local installation
Fred Drake4c9be9d1999-08-20 13:10:20 +0000301conventions; ${prefix} and ${exec_prefix} are installation-dependent
302and should be interpreted as for GNU software; they may be the same.
303The default for both is \fI/usr/local\fP.
304.IP \fI${exec_prefix}/bin/python\fP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000305Recommended location of the interpreter.
Fred Drake4c9be9d1999-08-20 13:10:20 +0000306.PP
307.I ${prefix}/lib/python<version>
308.br
309.I ${exec_prefix}/lib/python<version>
310.RS
311Recommended locations of the directories containing the standard
312modules.
313.RE
314.PP
315.I ${prefix}/include/python<version>
316.br
317.I ${exec_prefix}/include/python<version>
318.RS
319Recommended locations of the directories containing the include files
320needed for developing Python extensions and embedding the
321interpreter.
322.RE
323.IP \fI~/.pythonrc.py\fP
324User-specific initialization file loaded by the \fIuser\fP module;
325not used by default or by most applications.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000326.SH ENVIRONMENT VARIABLES
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000327.IP PYTHONHOME
328Change the location of the standard Python libraries. By default, the
Fred Drake4c9be9d1999-08-20 13:10:20 +0000329libraries are searched in ${prefix}/lib/python<version> and
330${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000331are installation-dependent directories, both defaulting to
Fred Drake4c9be9d1999-08-20 13:10:20 +0000332\fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value
333replaces both ${prefix} and ${exec_prefix}. To specify different values
334for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000335.IP PYTHONPATH
336Augments the default search path for module files.
337The format is the same as the shell's $PATH: one or more directory
338pathnames separated by colons.
Matthias Klose31a58df2005-03-20 14:16:03 +0000339Non-existent directories are silently ignored.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000340The default search path is installation dependent, but generally
Fred Drake4c9be9d1999-08-20 13:10:20 +0000341begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000342The default search path is always appended to $PYTHONPATH.
Guido van Rossum74faed21996-07-30 19:27:05 +0000343If a script argument is given, the directory containing the script is
344inserted in the path in front of $PYTHONPATH.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000345The search path can be manipulated from within a Python program as the
346variable
347.I sys.path .
348.IP PYTHONSTARTUP
349If this is the name of a readable file, the Python commands in that
350file are executed before the first prompt is displayed in interactive
351mode.
352The file is executed in the same name space where interactive commands
353are executed so that objects defined or imported in it can be used
354without qualification in the interactive session.
355You can also change the prompts
356.I sys.ps1
357and
358.I sys.ps2
359in this file.
Fred Drakebd2e3b02001-07-26 21:25:58 +0000360.IP PYTHONY2K
361Set this to a non-empty string to cause the \fItime\fP module to
362require dates specified as strings to include 4-digit years, otherwise
3632-digit years are converted based on rules described in the \fItime\fP
Andrew M. Kuchlingb2cb37f2002-05-09 14:33:18 +0000364module documentation.
Guido van Rossum9abaf4d2001-10-12 22:17:56 +0000365.IP PYTHONOPTIMIZE
366If this is set to a non-empty string it is equivalent to specifying
367the \fB\-O\fP option. If set to an integer, it is equivalent to
368specifying \fB\-O\fP multiple times.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000369.IP PYTHONDEBUG
370If this is set to a non-empty string it is equivalent to specifying
Guido van Rossum9abaf4d2001-10-12 22:17:56 +0000371the \fB\-d\fP option. If set to an integer, it is equivalent to
372specifying \fB\-d\fP multiple times.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000373.IP PYTHONINSPECT
374If this is set to a non-empty string it is equivalent to specifying
375the \fB\-i\fP option.
Guido van Rossumef5bca31994-05-03 14:15:32 +0000376.IP PYTHONUNBUFFERED
Guido van Rossuma7925f11994-01-26 10:20:16 +0000377If this is set to a non-empty string it is equivalent to specifying
Guido van Rossumef5bca31994-05-03 14:15:32 +0000378the \fB\-u\fP option.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000379.IP PYTHONVERBOSE
380If this is set to a non-empty string it is equivalent to specifying
Guido van Rossum9abaf4d2001-10-12 22:17:56 +0000381the \fB\-v\fP option. If set to an integer, it is equivalent to
382specifying \fB\-v\fP multiple times.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000383.SH AUTHOR
Andrew M. Kuchling6f593252004-10-07 12:27:31 +0000384The Python Software Foundation: http://www.python.org/psf
Guido van Rossum74faed21996-07-30 19:27:05 +0000385.SH INTERNET RESOURCES
Fred Drakebd2e3b02001-07-26 21:25:58 +0000386Main website: http://www.python.org/
Guido van Rossum74faed21996-07-30 19:27:05 +0000387.br
Andrew M. Kuchling895f2452004-10-07 12:23:12 +0000388Documentation: http://docs.python.org/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000389.br
Fred Drakebd2e3b02001-07-26 21:25:58 +0000390Community website: http://starship.python.net/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000391.br
Andrew M. Kuchling895f2452004-10-07 12:23:12 +0000392Developer resources: http://www.python.org/dev/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000393.br
Fred Drakebd2e3b02001-07-26 21:25:58 +0000394FTP: ftp://ftp.python.org/pub/python/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000395.br
Fred Drakebd2e3b02001-07-26 21:25:58 +0000396Module repository: http://www.vex.net/parnassus/
Guido van Rossum74faed21996-07-30 19:27:05 +0000397.br
Fred Drakebd2e3b02001-07-26 21:25:58 +0000398Newsgroups: comp.lang.python, comp.lang.python.announce
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000399.SH LICENSING
400Python is distributed under an Open Source license. See the file
401"LICENSE" in the Python source distribution for information on terms &
402conditions for accessing and otherwise using Python and for a
403DISCLAIMER OF ALL WARRANTIES.