blob: 3166a359b8798ae7a5b9b968b49e916df7c5ea12 [file] [log] [blame]
Fred Drakef2e9e291999-08-20 13:30:49 +00001.TH PYTHON "1" "20 August, 1999"
Guido van Rossuma7925f11994-01-26 10:20:16 +00002.SH NAME
3python \- an interpreted, interactive, object-oriented programming language
4.SH SYNOPSIS
5.B python
6[
Guido van Rossuma7925f11994-01-26 10:20:16 +00007.B \-d
8]
9[
10.B \-i
11]
12[
Guido van Rossum4cf4de51997-09-08 04:06:15 +000013.B \-O
14]
15[
16.B \-S
17]
18[
Guido van Rossum29d465b1998-04-10 19:36:09 +000019.B \-t
20]
21[
Guido van Rossumef5bca31994-05-03 14:15:32 +000022.B \-u
Guido van Rossuma7925f11994-01-26 10:20:16 +000023]
24[
25.B \-v
26]
Fred Drake4c9be9d1999-08-20 13:10:20 +000027.br
28 [
Guido van Rossum07c44c71998-04-10 19:46:00 +000029.B \-x
30]
31[
Guido van Rossum4cf4de51997-09-08 04:06:15 +000032.B \-X
33]
34.br
35 [
Guido van Rossuma7925f11994-01-26 10:20:16 +000036.B \-c
37.I command
38|
39.I script
40|
41\-
42]
43[
44.I arguments
45]
46.SH DESCRIPTION
47Python is an interpreted, interactive, object-oriented programming
48language that combines remarkable power with very clear syntax.
49For an introduction to programming in Python you are referred to the
50Python Tutorial.
51The Python Library Reference documents built-in and standard types,
52constants, functions and modules.
53Finally, the Python Reference Manual describes the syntax and
54semantics of the core language in (perhaps too) much detail.
Fred Drake4c9be9d1999-08-20 13:10:20 +000055(Information on locating these documents is included in
56.B "SEE ALSO"
57below; they may be installed on your system as well.)
Guido van Rossuma7925f11994-01-26 10:20:16 +000058.PP
59Python's basic power can be extended with your own modules written in
60C or C++.
Guido van Rossum74faed21996-07-30 19:27:05 +000061On most systems such modules may be dynamically loaded.
Guido van Rossuma7925f11994-01-26 10:20:16 +000062Python is also adaptable as an extension language for existing
63applications.
64See the internal documentation for hints.
65.SH COMMAND LINE OPTIONS
66.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +000067.B \-d
68Turn on parser debugging output (for wizards only, depending on
69compilation options).
Guido van Rossum9f65ae01994-02-23 09:10:27 +000070.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +000071.B \-i
72When a script is passed as first argument or the \fB\-c\fP option is
73used, enter interactive mode after executing the script or the
Guido van Rossum9f65ae01994-02-23 09:10:27 +000074command. It does not read the $PYTHONSTARTUP file. This can be
75useful to inspect global variables or a stack trace when a script
76raises an exception.
Guido van Rossuma7925f11994-01-26 10:20:16 +000077.TP
Guido van Rossum4cf4de51997-09-08 04:06:15 +000078.B \-O
79Turn on basic optimizations. This changes the filename extension for
80compiled (bytecode) files from
81.I .pyc
Fred Drake4c9be9d1999-08-20 13:10:20 +000082to \fI.pyo\fP. Given twice, causes docstrings to be discarded.
Guido van Rossum4cf4de51997-09-08 04:06:15 +000083.TP
84.B \-S
85Disable the import of the module
86.I site
87and the site-dependent manipulations of
88.I sys.path
89that it entails.
90.TP
Guido van Rossum29d465b1998-04-10 19:36:09 +000091.B \-t
92Issue a warning when a source file mixes tabs and spaces for
93indentation in a way that makes it depend on the worth of a tab
94expressed in spaces. Issue an error when the option is given twice.
95.TP
Guido van Rossumef5bca31994-05-03 14:15:32 +000096.B \-u
Guido van Rossum4cf4de51997-09-08 04:06:15 +000097Force stdin, stdout and stderr to be totally unbuffered.
Guido van Rossuma7925f11994-01-26 10:20:16 +000098.TP
99.B \-v
100Print a message each time a module is initialized, showing the place
Fred Drake4c9be9d1999-08-20 13:10:20 +0000101(filename or built-in module) from which it is loaded. When given
102twice, print a message for each file that is checked for when
103searching for a module. Also provides information on module cleanup
104at exit.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000105.TP
Guido van Rossum07c44c71998-04-10 19:46:00 +0000106.B \-x
107Skip the first line of the source. This is intended for a DOS
108specific hack only. Warning: the line numbers in error messages will
109be off by one!
110.TP
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000111.B \-X
112Make the standard exceptions strings instead of classes.
Fred Drake4c9be9d1999-08-20 13:10:20 +0000113Use for backward compatibility with old code only. This is not
114necessary for most uses of string exceptions.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000115.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000116.BI "\-c " command
117Specify the command to execute (see next section).
118This terminates the option list (following options are passed as
119arguments to the command).
Guido van Rossuma7925f11994-01-26 10:20:16 +0000120.SH INTERPRETER INTERFACE
121The interpreter interface resembles that of the UNIX shell: when
122called with standard input connected to a tty device, it prompts for
123commands and executes them until an EOF is read; when called with a
124file name argument or with a file as standard input, it reads and
125executes a
126.I script
127from that file;
128when called with
129.B \-c
130.I command,
131it executes the Python statement(s) given as
132.I command.
133Here
134.I command
135may contain multiple statements separated by newlines.
136Leading whitespace is significant in Python statements!
137In non-interactive mode, the entire input is parsed befored it is
138executed.
139.PP
140If available, the script name and additional arguments thereafter are
141passed to the script in the Python variable
142.I sys.argv ,
143which is a list of strings (you must first
144.I import sys
145to be able to access it).
146If no script name is given,
147.I sys.argv
148is empty; if
149.B \-c
150is used,
151.I sys.argv[0]
152contains the string
153.I '-c'.
Guido van Rossum74faed21996-07-30 19:27:05 +0000154Note that options interpreted by the Python interpreter itself
Guido van Rossuma7925f11994-01-26 10:20:16 +0000155are not placed in
156.I sys.argv.
157.PP
158In interactive mode, the primary prompt is `>>>'; the second prompt
159(which appears when a command is not complete) is `...'.
160The prompts can be changed by assignment to
161.I sys.ps1
162or
163.I sys.ps2.
164The interpreter quits when it reads an EOF at a prompt.
165When an unhandled exception occurs, a stack trace is printed and
166control returns to the primary prompt; in non-interactive mode, the
167interpreter exits after printing the stack trace.
168The interrupt signal raises the
169.I Keyboard\%Interrupt
170exception; other UNIX signals are not caught (except that SIGPIPE is
171sometimes ignored, in favor of the
172.I IOError
173exception). Error messages are written to stderr.
174.SH FILES AND DIRECTORIES
175These are subject to difference depending on local installation
Fred Drake4c9be9d1999-08-20 13:10:20 +0000176conventions; ${prefix} and ${exec_prefix} are installation-dependent
177and should be interpreted as for GNU software; they may be the same.
178The default for both is \fI/usr/local\fP.
179.IP \fI${exec_prefix}/bin/python\fP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000180Recommended location of the interpreter.
Fred Drake4c9be9d1999-08-20 13:10:20 +0000181.PP
182.I ${prefix}/lib/python<version>
183.br
184.I ${exec_prefix}/lib/python<version>
185.RS
186Recommended locations of the directories containing the standard
187modules.
188.RE
189.PP
190.I ${prefix}/include/python<version>
191.br
192.I ${exec_prefix}/include/python<version>
193.RS
194Recommended locations of the directories containing the include files
195needed for developing Python extensions and embedding the
196interpreter.
197.RE
198.IP \fI~/.pythonrc.py\fP
199User-specific initialization file loaded by the \fIuser\fP module;
200not used by default or by most applications.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000201.SH ENVIRONMENT VARIABLES
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000202.IP PYTHONHOME
203Change the location of the standard Python libraries. By default, the
Fred Drake4c9be9d1999-08-20 13:10:20 +0000204libraries are searched in ${prefix}/lib/python<version> and
205${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000206are installation-dependent directories, both defaulting to
Fred Drake4c9be9d1999-08-20 13:10:20 +0000207\fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value
208replaces both ${prefix} and ${exec_prefix}. To specify different values
209for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000210.IP PYTHONPATH
211Augments the default search path for module files.
212The format is the same as the shell's $PATH: one or more directory
213pathnames separated by colons.
214Non-existant directories are silently ignored.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000215The default search path is installation dependent, but generally
Fred Drake4c9be9d1999-08-20 13:10:20 +0000216begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000217The default search path is always appended to $PYTHONPATH.
Guido van Rossum74faed21996-07-30 19:27:05 +0000218If a script argument is given, the directory containing the script is
219inserted in the path in front of $PYTHONPATH.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000220The search path can be manipulated from within a Python program as the
221variable
222.I sys.path .
223.IP PYTHONSTARTUP
224If this is the name of a readable file, the Python commands in that
225file are executed before the first prompt is displayed in interactive
226mode.
227The file is executed in the same name space where interactive commands
228are executed so that objects defined or imported in it can be used
229without qualification in the interactive session.
230You can also change the prompts
231.I sys.ps1
232and
233.I sys.ps2
234in this file.
235.IP PYTHONDEBUG
236If this is set to a non-empty string it is equivalent to specifying
237the \fB\-d\fP option.
238.IP PYTHONINSPECT
239If this is set to a non-empty string it is equivalent to specifying
240the \fB\-i\fP option.
Guido van Rossumef5bca31994-05-03 14:15:32 +0000241.IP PYTHONUNBUFFERED
Guido van Rossuma7925f11994-01-26 10:20:16 +0000242If this is set to a non-empty string it is equivalent to specifying
Guido van Rossumef5bca31994-05-03 14:15:32 +0000243the \fB\-u\fP option.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000244.IP PYTHONVERBOSE
245If this is set to a non-empty string it is equivalent to specifying
246the \fB\-v\fP option.
247.SH SEE ALSO
Fred Drake4c9be9d1999-08-20 13:10:20 +0000248.IP "Python Tutorial"
249URL: http://www.python.org/doc/tut/tut.html
250.IP "Python Library Reference"
251URL: http://www.python.org/doc/lib/lib.html
252.IP "Python Reference Manual"
253URL: http://www.python.org/doc/ref/ref.html
254.IP "Extending and Embedding the Python Interpreter"
255URL: http://www.python.org/doc/ext/ext.html
256.IP "Python/C API"
257URL: http://www.python.org/doc/api/api.html
258.PP
259Downloadable versions of these documents in many formats are available
260at the Python website; see \fB\INTERNET RESOURCES\fP below.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000261.SH AUTHOR
262.nf
263Guido van Rossum
Guido van Rossum74faed21996-07-30 19:27:05 +0000264CNRI
2651895 Preston White Drive
266Reston, VA 20191
267USA
Guido van Rossuma7925f11994-01-26 10:20:16 +0000268.PP
Guido van Rossum74faed21996-07-30 19:27:05 +0000269E-mail: guido@cnri.reston.va.us, guido@python.org
Guido van Rossuma7925f11994-01-26 10:20:16 +0000270.fi
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000271.PP
272And a cast of thousands.
Guido van Rossum74faed21996-07-30 19:27:05 +0000273.SH INTERNET RESOURCES
274Web site: http://www.python.org
275.br
276FTP site: ftp://ftp.python.org
277.br
Fred Drake4c9be9d1999-08-20 13:10:20 +0000278Newsgroups: comp.lang.python, comp.lang.python.announce
279.PP
280There are many mirror sites; a current list is available at
281http://www.python.org/mirrors.html.
282.PP
283The \fI\Python Software Activity\fP provides many mailing lists which
284serve various special interests within the Python community;
285information on these special interest groups is available at
286http://www.python.org/sigs/.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000287.SH COPYRIGHT
Guido van Rossum227a0a11995-01-04 19:21:21 +0000288Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
289The Netherlands.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000290.IP " "
291All Rights Reserved
292.PP
Guido van Rossum227a0a11995-01-04 19:21:21 +0000293Permission to use, copy, modify, and distribute this software and its
294documentation for any purpose and without fee is hereby granted,
Guido van Rossuma7925f11994-01-26 10:20:16 +0000295provided that the above copyright notice appear in all copies and that
Guido van Rossum227a0a11995-01-04 19:21:21 +0000296both that copyright notice and this permission notice appear in
Guido van Rossuma7925f11994-01-26 10:20:16 +0000297supporting documentation, and that the names of Stichting Mathematisch
Guido van Rossumd266eb41996-10-25 14:44:06 +0000298Centrum or CWI or Corporation for National Research Initiatives or
299CNRI not be used in advertising or publicity pertaining to
300distribution of the software without specific, written prior
301permission.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000302
Guido van Rossumd266eb41996-10-25 14:44:06 +0000303While CWI is the initial source for this software, a modified version
304is made available by the Corporation for National Research Initiatives
305(CNRI) at the Internet address ftp://ftp.python.org.
306
307STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
308REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
309MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
310CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
311DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
312PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
313TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
314PERFORMANCE OF THIS SOFTWARE.