blob: 52aedee5bf0b9748180c90b994bf5b42c7825cc2 [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
Benjamin Peterson5f28b7b2009-03-26 21:49:58 +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[
Matthias Klosec8b16f82010-01-31 16:14:37 +000011.B \-B
12]
13[
Senthil Kumarance3dd0b2013-06-19 22:19:46 -050014.B \-b
15]
16[
Guido van Rossuma7925f11994-01-26 10:20:16 +000017.B \-d
18]
19[
Guido van Rossumb674baf2001-09-05 18:55:34 +000020.B \-E
21]
22[
23.B \-h
24]
25[
Guido van Rossuma7925f11994-01-26 10:20:16 +000026.B \-i
27]
28[
Christian Heimesad73a9c2013-08-10 16:36:18 +020029.B \-I
Andrew M. Kuchling166e6252004-10-07 12:04:50 +000030]
Guido van Rossumb674baf2001-09-05 18:55:34 +000031.br
32 [
Christian Heimesad73a9c2013-08-10 16:36:18 +020033.B \-m
34.I module-name
35]
36[
Senthil Kumarance3dd0b2013-06-19 22:19:46 -050037.B \-q
38]
39[
Matthias Klosec8b16f82010-01-31 16:14:37 +000040.B \-O
41]
42[
R David Murray9c4f09d2011-05-01 11:13:56 -040043.B \-OO
Matthias Klosec8b16f82010-01-31 16:14:37 +000044]
45[
Matthias Klosec8b16f82010-01-31 16:14:37 +000046.B \-s
47]
48[
Guido van Rossumb674baf2001-09-05 18:55:34 +000049.B \-S
Neil Schemenauer7d4bb9f2001-07-23 16:30:27 +000050]
51[
Guido van Rossumef5bca31994-05-03 14:15:32 +000052.B \-u
Guido van Rossuma7925f11994-01-26 10:20:16 +000053]
Guido van Rossumb674baf2001-09-05 18:55:34 +000054.br
55 [
Guido van Rossuma7925f11994-01-26 10:20:16 +000056.B \-v
57]
Guido van Rossum07c44c71998-04-10 19:46:00 +000058[
Barry Warsaw64569372000-09-15 18:39:09 +000059.B \-V
60]
Guido van Rossum1378c322000-12-19 03:21:54 +000061[
62.B \-W
63.I argument
64]
Guido van Rossumb674baf2001-09-05 18:55:34 +000065[
66.B \-x
67]
Matthias Klosec8b16f82010-01-31 16:14:37 +000068[
Senthil Kumarance3dd0b2013-06-19 22:19:46 -050069[
70.B \-X
71.I option
72]
Matthias Klosec8b16f82010-01-31 16:14:37 +000073.B \-?
74]
Guido van Rossum4cf4de51997-09-08 04:06:15 +000075.br
76 [
Guido van Rossuma7925f11994-01-26 10:20:16 +000077.B \-c
78.I command
79|
80.I script
81|
82\-
83]
84[
85.I arguments
86]
87.SH DESCRIPTION
88Python is an interpreted, interactive, object-oriented programming
89language that combines remarkable power with very clear syntax.
90For an introduction to programming in Python you are referred to the
91Python Tutorial.
92The Python Library Reference documents built-in and standard types,
93constants, functions and modules.
94Finally, the Python Reference Manual describes the syntax and
95semantics of the core language in (perhaps too) much detail.
Guido van Rossumf4a090d2000-09-01 20:36:34 +000096(These documents may be located via the
97.B "INTERNET RESOURCES"
Fred Drake4c9be9d1999-08-20 13:10:20 +000098below; they may be installed on your system as well.)
Guido van Rossuma7925f11994-01-26 10:20:16 +000099.PP
100Python's basic power can be extended with your own modules written in
101C or C++.
Guido van Rossum74faed21996-07-30 19:27:05 +0000102On most systems such modules may be dynamically loaded.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000103Python is also adaptable as an extension language for existing
104applications.
105See the internal documentation for hints.
Andrew M. Kuchling88717f42001-04-05 14:50:40 +0000106.PP
107Documentation for installed Python modules and packages can be
108viewed by running the
109.B pydoc
110program.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000111.SH COMMAND LINE OPTIONS
112.TP
Matthias Klosec8b16f82010-01-31 16:14:37 +0000113.B \-B
114Don't write
115.I .py[co]
116files on import. See also PYTHONDONTWRITEBYTECODE.
117.TP
Senthil Kumarance3dd0b2013-06-19 22:19:46 -0500118.B \-b
119Issue warnings about str(bytes_instance), str(bytearray_instance)
120and comparing bytes/bytearray with str. (-bb: issue errors)
121.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +0000122.BI "\-c " command
123Specify the command to execute (see next section).
124This terminates the option list (following options are passed as
125arguments to the command).
126.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000127.B \-d
128Turn on parser debugging output (for wizards only, depending on
129compilation options).
Guido van Rossum9f65ae01994-02-23 09:10:27 +0000130.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +0000131.B \-E
132Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
133the behavior of the interpreter.
134.TP
Matthias Klosec8b16f82010-01-31 16:14:37 +0000135.B \-h ", " \-? ", "\-\-help
Guido van Rossumb674baf2001-09-05 18:55:34 +0000136Prints the usage for the interpreter executable and exits.
137.TP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000138.B \-i
139When a script is passed as first argument or the \fB\-c\fP option is
140used, enter interactive mode after executing the script or the
Guido van Rossum9f65ae01994-02-23 09:10:27 +0000141command. It does not read the $PYTHONSTARTUP file. This can be
142useful to inspect global variables or a stack trace when a script
143raises an exception.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000144.TP
Christian Heimesad73a9c2013-08-10 16:36:18 +0200145.B \-I
146Run Python in isolated mode. This also implies \fB\-E\fP and \fB\-S\fP. In
147isolated mode sys.path contains neither the script’s directory nor the user’s
148site-packages directory. All PYTHON* environment variables are ignored, too.
149Further restrictions may be imposed to prevent the user from injecting
150malicious code.
151.TP
Andrew M. Kuchling166e6252004-10-07 12:04:50 +0000152.BI "\-m " module-name
153Searches
154.I sys.path
155for the named module and runs the corresponding
156.I .py
157file as a script.
158.TP
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000159.B \-O
160Turn on basic optimizations. This changes the filename extension for
161compiled (bytecode) files from
162.I .pyc
Fred Drake4c9be9d1999-08-20 13:10:20 +0000163to \fI.pyo\fP. Given twice, causes docstrings to be discarded.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000164.TP
R David Murray9c4f09d2011-05-01 11:13:56 -0400165.B \-OO
Matthias Klosec8b16f82010-01-31 16:14:37 +0000166Discard docstrings in addition to the \fB-O\fP optimizations.
167.TP
Georg Brandl9d871192010-12-04 10:47:18 +0000168.B \-q
169Do not print the version and copyright messages. These messages are
170also suppressed in non-interactive mode.
171.TP
Matthias Klosec8b16f82010-01-31 16:14:37 +0000172.B \-s
173Don't add user site directory to sys.path.
174.TP
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000175.B \-S
176Disable the import of the module
177.I site
178and the site-dependent manipulations of
179.I sys.path
Éric Araujoc09fca62011-03-23 02:06:24 +0100180that it entails. Also disable these manipulations if
181.I site
182is explicitly imported later.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000183.TP
Guido van Rossumef5bca31994-05-03 14:15:32 +0000184.B \-u
Ezio Melotti61b0c672013-07-25 05:04:02 +0200185Force the binary I/O layers of stdout and stderr to be unbuffered.
186stdin is always buffered.
Georg Brandl379299c2010-04-02 08:47:07 +0000187The text I/O layer will still be line-buffered.
188.\" Note that there is internal buffering in readlines() and
189.\" file-object iterators ("for line in sys.stdin") which is not
190.\" influenced by this option. To work around this, you will want to use
191.\" "sys.stdin.readline()" inside a "while 1:" loop.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000192.TP
193.B \-v
194Print a message each time a module is initialized, showing the place
Fred Drake4c9be9d1999-08-20 13:10:20 +0000195(filename or built-in module) from which it is loaded. When given
196twice, print a message for each file that is checked for when
197searching for a module. Also provides information on module cleanup
198at exit.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000199.TP
Matthias Klosec8b16f82010-01-31 16:14:37 +0000200.B \-V ", " \-\-version
Barry Warsaw64569372000-09-15 18:39:09 +0000201Prints the Python version number of the executable and exits.
202.TP
Guido van Rossum1378c322000-12-19 03:21:54 +0000203.BI "\-W " argument
204Warning control. Python sometimes prints warning message to
205.IR sys.stderr .
206A typical warning message has the following form:
207.IB file ":" line ": " category ": " message.
208By default, each warning is printed once for each source line where it
209occurs. This option controls how often warnings are printed.
210Multiple
211.B \-W
212options may be given; when a warning matches more than one
213option, the action for the last matching option is performed.
214Invalid
215.B \-W
216options are ignored (a warning message is printed about invalid
217options when the first warning is issued). Warnings can also be
218controlled from within a Python program using the
219.I warnings
220module.
221
222The simplest form of
223.I argument
224is one of the following
225.I action
226strings (or a unique abbreviation):
227.B ignore
228to ignore all warnings;
229.B default
230to explicitly request the default behavior (printing each warning once
231per source line);
232.B all
233to print a warning each time it occurs (this may generate many
234messages if a warning is triggered repeatedly for the same source
Fred Drakebd2e3b02001-07-26 21:25:58 +0000235line, such as inside a loop);
Guido van Rossum1378c322000-12-19 03:21:54 +0000236.B module
Georg Brandleeb575f2009-06-24 06:42:05 +0000237to print each warning only the first time it occurs in each
Guido van Rossum1378c322000-12-19 03:21:54 +0000238module;
239.B once
240to print each warning only the first time it occurs in the program; or
241.B error
242to raise an exception instead of printing a warning message.
243
244The full form of
245.I argument
246is
247.IB action : message : category : module : line.
248Here,
249.I action
250is as explained above but only applies to messages that match the
251remaining fields. Empty fields match all values; trailing empty
252fields may be omitted. The
253.I message
254field matches the start of the warning message printed; this match is
255case-insensitive. The
256.I category
257field matches the warning category. This must be a class name; the
258match test whether the actual warning category of the message is a
259subclass of the specified warning category. The full class name must
260be given. The
261.I module
262field matches the (fully-qualified) module name; this match is
263case-sensitive. The
264.I line
265field matches the line number, where zero matches all line numbers and
266is thus equivalent to an omitted line number.
267.TP
Senthil Kumarance3dd0b2013-06-19 22:19:46 -0500268.BI "\-X " option
269Set implementation specific option.
270.TP
Guido van Rossumb674baf2001-09-05 18:55:34 +0000271.B \-x
272Skip the first line of the source. This is intended for a DOS
273specific hack only. Warning: the line numbers in error messages will
274be off by one!
Guido van Rossuma7925f11994-01-26 10:20:16 +0000275.SH INTERPRETER INTERFACE
276The interpreter interface resembles that of the UNIX shell: when
277called with standard input connected to a tty device, it prompts for
278commands and executes them until an EOF is read; when called with a
279file name argument or with a file as standard input, it reads and
280executes a
281.I script
282from that file;
283when called with
284.B \-c
doko@ubuntu.comd8623e82012-06-20 13:16:31 +0200285.IR command ,
Guido van Rossuma7925f11994-01-26 10:20:16 +0000286it executes the Python statement(s) given as
doko@ubuntu.comd8623e82012-06-20 13:16:31 +0200287.IR command .
Guido van Rossuma7925f11994-01-26 10:20:16 +0000288Here
289.I command
290may contain multiple statements separated by newlines.
291Leading whitespace is significant in Python statements!
Matthias Klose31a58df2005-03-20 14:16:03 +0000292In non-interactive mode, the entire input is parsed before it is
Guido van Rossuma7925f11994-01-26 10:20:16 +0000293executed.
294.PP
295If available, the script name and additional arguments thereafter are
296passed to the script in the Python variable
doko@ubuntu.comd8623e82012-06-20 13:16:31 +0200297.IR sys.argv ,
Guido van Rossuma7925f11994-01-26 10:20:16 +0000298which is a list of strings (you must first
299.I import sys
300to be able to access it).
301If no script name is given,
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000302.I sys.argv[0]
303is an empty string; if
Guido van Rossuma7925f11994-01-26 10:20:16 +0000304.B \-c
305is used,
306.I sys.argv[0]
307contains the string
308.I '-c'.
Guido van Rossum74faed21996-07-30 19:27:05 +0000309Note that options interpreted by the Python interpreter itself
Guido van Rossuma7925f11994-01-26 10:20:16 +0000310are not placed in
doko@ubuntu.comd8623e82012-06-20 13:16:31 +0200311.IR sys.argv .
Guido van Rossuma7925f11994-01-26 10:20:16 +0000312.PP
313In interactive mode, the primary prompt is `>>>'; the second prompt
314(which appears when a command is not complete) is `...'.
315The prompts can be changed by assignment to
316.I sys.ps1
317or
doko@ubuntu.comd8623e82012-06-20 13:16:31 +0200318.IR sys.ps2 .
Guido van Rossuma7925f11994-01-26 10:20:16 +0000319The interpreter quits when it reads an EOF at a prompt.
320When an unhandled exception occurs, a stack trace is printed and
321control returns to the primary prompt; in non-interactive mode, the
322interpreter exits after printing the stack trace.
323The interrupt signal raises the
324.I Keyboard\%Interrupt
325exception; other UNIX signals are not caught (except that SIGPIPE is
326sometimes ignored, in favor of the
327.I IOError
328exception). Error messages are written to stderr.
329.SH FILES AND DIRECTORIES
330These are subject to difference depending on local installation
Fred Drake4c9be9d1999-08-20 13:10:20 +0000331conventions; ${prefix} and ${exec_prefix} are installation-dependent
332and should be interpreted as for GNU software; they may be the same.
333The default for both is \fI/usr/local\fP.
334.IP \fI${exec_prefix}/bin/python\fP
Guido van Rossuma7925f11994-01-26 10:20:16 +0000335Recommended location of the interpreter.
Fred Drake4c9be9d1999-08-20 13:10:20 +0000336.PP
337.I ${prefix}/lib/python<version>
338.br
339.I ${exec_prefix}/lib/python<version>
340.RS
341Recommended locations of the directories containing the standard
342modules.
343.RE
344.PP
345.I ${prefix}/include/python<version>
346.br
347.I ${exec_prefix}/include/python<version>
348.RS
349Recommended locations of the directories containing the include files
350needed for developing Python extensions and embedding the
351interpreter.
352.RE
Guido van Rossuma7925f11994-01-26 10:20:16 +0000353.SH ENVIRONMENT VARIABLES
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000354.IP PYTHONHOME
355Change the location of the standard Python libraries. By default, the
Fred Drake4c9be9d1999-08-20 13:10:20 +0000356libraries are searched in ${prefix}/lib/python<version> and
357${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000358are installation-dependent directories, both defaulting to
Fred Drake4c9be9d1999-08-20 13:10:20 +0000359\fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value
360replaces both ${prefix} and ${exec_prefix}. To specify different values
361for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000362.IP PYTHONPATH
363Augments the default search path for module files.
364The format is the same as the shell's $PATH: one or more directory
365pathnames separated by colons.
Matthias Klose31a58df2005-03-20 14:16:03 +0000366Non-existent directories are silently ignored.
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000367The default search path is installation dependent, but generally
Fred Drake4c9be9d1999-08-20 13:10:20 +0000368begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
Guido van Rossum4cf4de51997-09-08 04:06:15 +0000369The default search path is always appended to $PYTHONPATH.
Guido van Rossum74faed21996-07-30 19:27:05 +0000370If a script argument is given, the directory containing the script is
371inserted in the path in front of $PYTHONPATH.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000372The search path can be manipulated from within a Python program as the
373variable
doko@ubuntu.comd8623e82012-06-20 13:16:31 +0200374.IR sys.path .
Guido van Rossuma7925f11994-01-26 10:20:16 +0000375.IP PYTHONSTARTUP
376If this is the name of a readable file, the Python commands in that
377file are executed before the first prompt is displayed in interactive
378mode.
379The file is executed in the same name space where interactive commands
380are executed so that objects defined or imported in it can be used
381without qualification in the interactive session.
382You can also change the prompts
383.I sys.ps1
384and
385.I sys.ps2
386in this file.
Fred Drakebd2e3b02001-07-26 21:25:58 +0000387.IP PYTHONY2K
388Set this to a non-empty string to cause the \fItime\fP module to
389require dates specified as strings to include 4-digit years, otherwise
3902-digit years are converted based on rules described in the \fItime\fP
Andrew M. Kuchlingb2cb37f2002-05-09 14:33:18 +0000391module documentation.
Guido van Rossum9abaf4d2001-10-12 22:17:56 +0000392.IP PYTHONOPTIMIZE
393If this is set to a non-empty string it is equivalent to specifying
394the \fB\-O\fP option. If set to an integer, it is equivalent to
395specifying \fB\-O\fP multiple times.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000396.IP PYTHONDEBUG
397If this is set to a non-empty string it is equivalent to specifying
Guido van Rossum9abaf4d2001-10-12 22:17:56 +0000398the \fB\-d\fP option. If set to an integer, it is equivalent to
399specifying \fB\-d\fP multiple times.
Matthias Klosec8b16f82010-01-31 16:14:37 +0000400.IP PYTHONDONTWRITEBYTECODE
401If this is set to a non-empty string it is equivalent to specifying
402the \fB\-B\fP option (don't try to write
403.I .py[co]
404files).
Guido van Rossuma7925f11994-01-26 10:20:16 +0000405.IP PYTHONINSPECT
406If this is set to a non-empty string it is equivalent to specifying
407the \fB\-i\fP option.
Benjamin Petersonee85a1d2010-10-13 22:20:15 +0000408.IP PYTHONIOENCODING
409If this is set before running the interpreter, it overrides the encoding used
410for stdin/stdout/stderr, in the syntax
411.IB encodingname ":" errorhandler
412The
413.IB errorhandler
414part is optional and has the same meaning as in str.encode. For stderr, the
415.IB errorhandler
416 part is ignored; the handler will always be \'backslashreplace\'.
Matthias Klosec8b16f82010-01-31 16:14:37 +0000417.IP PYTHONNOUSERSITE
Benjamin Petersonee85a1d2010-10-13 22:20:15 +0000418If this is set to a non-empty string it is equivalent to specifying the
419\fB\-s\fP option (Don't add the user site directory to sys.path).
Guido van Rossumef5bca31994-05-03 14:15:32 +0000420.IP PYTHONUNBUFFERED
Guido van Rossuma7925f11994-01-26 10:20:16 +0000421If this is set to a non-empty string it is equivalent to specifying
Guido van Rossumef5bca31994-05-03 14:15:32 +0000422the \fB\-u\fP option.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000423.IP PYTHONVERBOSE
424If this is set to a non-empty string it is equivalent to specifying
Guido van Rossum9abaf4d2001-10-12 22:17:56 +0000425the \fB\-v\fP option. If set to an integer, it is equivalent to
426specifying \fB\-v\fP multiple times.
Philip Jenvey0805ca32010-04-07 04:04:10 +0000427.IP PYTHONWARNINGS
428If this is set to a comma-separated string it is equivalent to
429specifying the \fB\-W\fP option for each separate value.
Georg Brandl2daf6ae2012-02-20 19:54:16 +0100430.IP PYTHONHASHSEED
Benjamin Petersonc9f54cf2012-02-21 16:08:05 -0500431If this variable is set to "random", a random value is used to seed the hashes
432of str, bytes and datetime objects.
Georg Brandl2daf6ae2012-02-20 19:54:16 +0100433
434If PYTHONHASHSEED is set to an integer value, it is used as a fixed seed for
435generating the hash() of the types covered by the hash randomization. Its
436purpose is to allow repeatable hashing, such as for selftests for the
437interpreter itself, or to allow a cluster of python processes to share hash
438values.
439
440The integer must be a decimal number in the range [0,4294967295]. Specifying
Benjamin Petersonc9f54cf2012-02-21 16:08:05 -0500441the value 0 will disable hash randomization.
Guido van Rossuma7925f11994-01-26 10:20:16 +0000442.SH AUTHOR
Andrew M. Kuchling6f593252004-10-07 12:27:31 +0000443The Python Software Foundation: http://www.python.org/psf
Guido van Rossum74faed21996-07-30 19:27:05 +0000444.SH INTERNET RESOURCES
Fred Drakebd2e3b02001-07-26 21:25:58 +0000445Main website: http://www.python.org/
Guido van Rossum74faed21996-07-30 19:27:05 +0000446.br
Benjamin Peterson6aa7c8c2009-09-13 02:23:12 +0000447Documentation: http://docs.python.org/py3k/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000448.br
Éric Araujoa2b89e32011-11-29 16:36:17 +0100449Developer resources: http://docs.python.org/devguide/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000450.br
Benjamin Peterson25a8dd72009-09-13 02:22:00 +0000451Downloads: http://python.org/download/
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000452.br
Benjamin Peterson25a8dd72009-09-13 02:22:00 +0000453Module repository: http://pypi.python.org/
Guido van Rossum74faed21996-07-30 19:27:05 +0000454.br
Fred Drakebd2e3b02001-07-26 21:25:58 +0000455Newsgroups: comp.lang.python, comp.lang.python.announce
Guido van Rossumf4a090d2000-09-01 20:36:34 +0000456.SH LICENSING
457Python is distributed under an Open Source license. See the file
458"LICENSE" in the Python source distribution for information on terms &
459conditions for accessing and otherwise using Python and for a
460DISCLAIMER OF ALL WARRANTIES.