Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .TH PYTHON "1" "$Date: 2005/03/20 14:18:04 $" |
2 | ||
3 | ./" To view this file while editing, run it through groff: | |
4 | ./" groff -Tascii -man python.man | less | |
5 | ||
6 | .SH NAME | |
7 | python \- an interpreted, interactive, object-oriented programming language | |
8 | .SH SYNOPSIS | |
9 | .B python | |
10 | [ | |
11 | .B \-d | |
12 | ] | |
13 | [ | |
14 | .B \-E | |
15 | ] | |
16 | [ | |
17 | .B \-h | |
18 | ] | |
19 | [ | |
20 | .B \-i | |
21 | ] | |
22 | [ | |
23 | .B \-m | |
24 | .I module-name | |
25 | ] | |
26 | [ | |
27 | .B \-O | |
28 | ] | |
29 | .br | |
30 | [ | |
31 | .B -Q | |
32 | .I argument | |
33 | ] | |
34 | [ | |
35 | .B \-S | |
36 | ] | |
37 | [ | |
38 | .B \-t | |
39 | ] | |
40 | [ | |
41 | .B \-u | |
42 | ] | |
43 | .br | |
44 | [ | |
45 | .B \-v | |
46 | ] | |
47 | [ | |
48 | .B \-V | |
49 | ] | |
50 | [ | |
51 | .B \-W | |
52 | .I argument | |
53 | ] | |
54 | [ | |
55 | .B \-x | |
56 | ] | |
57 | .br | |
58 | [ | |
59 | .B \-c | |
60 | .I command | |
61 | | | |
62 | .I script | |
63 | | | |
64 | \- | |
65 | ] | |
66 | [ | |
67 | .I arguments | |
68 | ] | |
69 | .SH DESCRIPTION | |
70 | Python is an interpreted, interactive, object-oriented programming | |
71 | language that combines remarkable power with very clear syntax. | |
72 | For an introduction to programming in Python you are referred to the | |
73 | Python Tutorial. | |
74 | The Python Library Reference documents built-in and standard types, | |
75 | constants, functions and modules. | |
76 | Finally, the Python Reference Manual describes the syntax and | |
77 | semantics of the core language in (perhaps too) much detail. | |
78 | (These documents may be located via the | |
79 | .B "INTERNET RESOURCES" | |
80 | below; they may be installed on your system as well.) | |
81 | .PP | |
82 | Python's basic power can be extended with your own modules written in | |
83 | C or C++. | |
84 | On most systems such modules may be dynamically loaded. | |
85 | Python is also adaptable as an extension language for existing | |
86 | applications. | |
87 | See the internal documentation for hints. | |
88 | .PP | |
89 | Documentation for installed Python modules and packages can be | |
90 | viewed by running the | |
91 | .B pydoc | |
92 | program. | |
93 | .SH COMMAND LINE OPTIONS | |
94 | .TP | |
95 | .BI "\-c " command | |
96 | Specify the command to execute (see next section). | |
97 | This terminates the option list (following options are passed as | |
98 | arguments to the command). | |
99 | .TP | |
100 | .B \-d | |
101 | Turn on parser debugging output (for wizards only, depending on | |
102 | compilation options). | |
103 | .TP | |
104 | .B \-E | |
105 | Ignore environment variables like PYTHONPATH and PYTHONHOME that modify | |
106 | the behavior of the interpreter. | |
107 | .TP | |
108 | .B \-h | |
109 | Prints the usage for the interpreter executable and exits. | |
110 | .TP | |
111 | .B \-i | |
112 | When a script is passed as first argument or the \fB\-c\fP option is | |
113 | used, enter interactive mode after executing the script or the | |
114 | command. It does not read the $PYTHONSTARTUP file. This can be | |
115 | useful to inspect global variables or a stack trace when a script | |
116 | raises an exception. | |
117 | .TP | |
118 | .BI "\-m " module-name | |
119 | Searches | |
120 | .I sys.path | |
121 | for the named module and runs the corresponding | |
122 | .I .py | |
123 | file as a script. | |
124 | .TP | |
125 | .B \-O | |
126 | Turn on basic optimizations. This changes the filename extension for | |
127 | compiled (bytecode) files from | |
128 | .I .pyc | |
129 | to \fI.pyo\fP. Given twice, causes docstrings to be discarded. | |
130 | .TP | |
131 | .BI "\-Q " argument | |
132 | Division control; see PEP 238. The argument must be one of "old" (the | |
133 | default, int/int and long/long return an int or long), "new" (new | |
134 | division semantics, i.e. int/int and long/long returns a float), | |
135 | "warn" (old division semantics with a warning for int/int and | |
136 | long/long), or "warnall" (old division semantics with a warning for | |
137 | all use of the division operator). For a use of "warnall", see the | |
138 | Tools/scripts/fixdiv.py script. | |
139 | .TP | |
140 | .B \-S | |
141 | Disable the import of the module | |
142 | .I site | |
143 | and the site-dependent manipulations of | |
144 | .I sys.path | |
145 | that it entails. | |
146 | .TP | |
147 | .B \-t | |
148 | Issue a warning when a source file mixes tabs and spaces for | |
149 | indentation in a way that makes it depend on the worth of a tab | |
150 | expressed in spaces. Issue an error when the option is given twice. | |
151 | .TP | |
152 | .B \-u | |
153 | Force stdin, stdout and stderr to be totally unbuffered. On systems | |
154 | where it matters, also put stdin, stdout and stderr in binary mode. | |
155 | Note that there is internal buffering in xreadlines(), readlines() and | |
156 | file-object iterators ("for line in sys.stdin") which is not | |
157 | influenced by this option. To work around this, you will want to use | |
158 | "sys.stdin.readline()" inside a "while 1:" loop. | |
159 | .TP | |
160 | .B \-v | |
161 | Print a message each time a module is initialized, showing the place | |
162 | (filename or built-in module) from which it is loaded. When given | |
163 | twice, print a message for each file that is checked for when | |
164 | searching for a module. Also provides information on module cleanup | |
165 | at exit. | |
166 | .TP | |
167 | .B \-V | |
168 | Prints the Python version number of the executable and exits. | |
169 | .TP | |
170 | .BI "\-W " argument | |
171 | Warning control. Python sometimes prints warning message to | |
172 | .IR sys.stderr . | |
173 | A typical warning message has the following form: | |
174 | .IB file ":" line ": " category ": " message. | |
175 | By default, each warning is printed once for each source line where it | |
176 | occurs. This option controls how often warnings are printed. | |
177 | Multiple | |
178 | .B \-W | |
179 | options may be given; when a warning matches more than one | |
180 | option, the action for the last matching option is performed. | |
181 | Invalid | |
182 | .B \-W | |
183 | options are ignored (a warning message is printed about invalid | |
184 | options when the first warning is issued). Warnings can also be | |
185 | controlled from within a Python program using the | |
186 | .I warnings | |
187 | module. | |
188 | ||
189 | The simplest form of | |
190 | .I argument | |
191 | is one of the following | |
192 | .I action | |
193 | strings (or a unique abbreviation): | |
194 | .B ignore | |
195 | to ignore all warnings; | |
196 | .B default | |
197 | to explicitly request the default behavior (printing each warning once | |
198 | per source line); | |
199 | .B all | |
200 | to print a warning each time it occurs (this may generate many | |
201 | messages if a warning is triggered repeatedly for the same source | |
202 | line, such as inside a loop); | |
203 | .B module | |
204 | to print each warning only only the first time it occurs in each | |
205 | module; | |
206 | .B once | |
207 | to print each warning only the first time it occurs in the program; or | |
208 | .B error | |
209 | to raise an exception instead of printing a warning message. | |
210 | ||
211 | The full form of | |
212 | .I argument | |
213 | is | |
214 | .IB action : message : category : module : line. | |
215 | Here, | |
216 | .I action | |
217 | is as explained above but only applies to messages that match the | |
218 | remaining fields. Empty fields match all values; trailing empty | |
219 | fields may be omitted. The | |
220 | .I message | |
221 | field matches the start of the warning message printed; this match is | |
222 | case-insensitive. The | |
223 | .I category | |
224 | field matches the warning category. This must be a class name; the | |
225 | match test whether the actual warning category of the message is a | |
226 | subclass of the specified warning category. The full class name must | |
227 | be given. The | |
228 | .I module | |
229 | field matches the (fully-qualified) module name; this match is | |
230 | case-sensitive. The | |
231 | .I line | |
232 | field matches the line number, where zero matches all line numbers and | |
233 | is thus equivalent to an omitted line number. | |
234 | .TP | |
235 | .B \-x | |
236 | Skip the first line of the source. This is intended for a DOS | |
237 | specific hack only. Warning: the line numbers in error messages will | |
238 | be off by one! | |
239 | .SH INTERPRETER INTERFACE | |
240 | The interpreter interface resembles that of the UNIX shell: when | |
241 | called with standard input connected to a tty device, it prompts for | |
242 | commands and executes them until an EOF is read; when called with a | |
243 | file name argument or with a file as standard input, it reads and | |
244 | executes a | |
245 | .I script | |
246 | from that file; | |
247 | when called with | |
248 | .B \-c | |
249 | .I command, | |
250 | it executes the Python statement(s) given as | |
251 | .I command. | |
252 | Here | |
253 | .I command | |
254 | may contain multiple statements separated by newlines. | |
255 | Leading whitespace is significant in Python statements! | |
256 | In non-interactive mode, the entire input is parsed before it is | |
257 | executed. | |
258 | .PP | |
259 | If available, the script name and additional arguments thereafter are | |
260 | passed to the script in the Python variable | |
261 | .I sys.argv , | |
262 | which is a list of strings (you must first | |
263 | .I import sys | |
264 | to be able to access it). | |
265 | If no script name is given, | |
266 | .I sys.argv[0] | |
267 | is an empty string; if | |
268 | .B \-c | |
269 | is used, | |
270 | .I sys.argv[0] | |
271 | contains the string | |
272 | .I '-c'. | |
273 | Note that options interpreted by the Python interpreter itself | |
274 | are not placed in | |
275 | .I sys.argv. | |
276 | .PP | |
277 | In interactive mode, the primary prompt is `>>>'; the second prompt | |
278 | (which appears when a command is not complete) is `...'. | |
279 | The prompts can be changed by assignment to | |
280 | .I sys.ps1 | |
281 | or | |
282 | .I sys.ps2. | |
283 | The interpreter quits when it reads an EOF at a prompt. | |
284 | When an unhandled exception occurs, a stack trace is printed and | |
285 | control returns to the primary prompt; in non-interactive mode, the | |
286 | interpreter exits after printing the stack trace. | |
287 | The interrupt signal raises the | |
288 | .I Keyboard\%Interrupt | |
289 | exception; other UNIX signals are not caught (except that SIGPIPE is | |
290 | sometimes ignored, in favor of the | |
291 | .I IOError | |
292 | exception). Error messages are written to stderr. | |
293 | .SH FILES AND DIRECTORIES | |
294 | These are subject to difference depending on local installation | |
295 | conventions; ${prefix} and ${exec_prefix} are installation-dependent | |
296 | and should be interpreted as for GNU software; they may be the same. | |
297 | The default for both is \fI/usr/local\fP. | |
298 | .IP \fI${exec_prefix}/bin/python\fP | |
299 | Recommended location of the interpreter. | |
300 | .PP | |
301 | .I ${prefix}/lib/python<version> | |
302 | .br | |
303 | .I ${exec_prefix}/lib/python<version> | |
304 | .RS | |
305 | Recommended locations of the directories containing the standard | |
306 | modules. | |
307 | .RE | |
308 | .PP | |
309 | .I ${prefix}/include/python<version> | |
310 | .br | |
311 | .I ${exec_prefix}/include/python<version> | |
312 | .RS | |
313 | Recommended locations of the directories containing the include files | |
314 | needed for developing Python extensions and embedding the | |
315 | interpreter. | |
316 | .RE | |
317 | .IP \fI~/.pythonrc.py\fP | |
318 | User-specific initialization file loaded by the \fIuser\fP module; | |
319 | not used by default or by most applications. | |
320 | .SH ENVIRONMENT VARIABLES | |
321 | .IP PYTHONHOME | |
322 | Change the location of the standard Python libraries. By default, the | |
323 | libraries are searched in ${prefix}/lib/python<version> and | |
324 | ${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix} | |
325 | are installation-dependent directories, both defaulting to | |
326 | \fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value | |
327 | replaces both ${prefix} and ${exec_prefix}. To specify different values | |
328 | for these, set $PYTHONHOME to ${prefix}:${exec_prefix}. | |
329 | .IP PYTHONPATH | |
330 | Augments the default search path for module files. | |
331 | The format is the same as the shell's $PATH: one or more directory | |
332 | pathnames separated by colons. | |
333 | Non-existent directories are silently ignored. | |
334 | The default search path is installation dependent, but generally | |
335 | begins with ${prefix}/lib/python<version> (see PYTHONHOME above). | |
336 | The default search path is always appended to $PYTHONPATH. | |
337 | If a script argument is given, the directory containing the script is | |
338 | inserted in the path in front of $PYTHONPATH. | |
339 | The search path can be manipulated from within a Python program as the | |
340 | variable | |
341 | .I sys.path . | |
342 | .IP PYTHONSTARTUP | |
343 | If this is the name of a readable file, the Python commands in that | |
344 | file are executed before the first prompt is displayed in interactive | |
345 | mode. | |
346 | The file is executed in the same name space where interactive commands | |
347 | are executed so that objects defined or imported in it can be used | |
348 | without qualification in the interactive session. | |
349 | You can also change the prompts | |
350 | .I sys.ps1 | |
351 | and | |
352 | .I sys.ps2 | |
353 | in this file. | |
354 | .IP PYTHONY2K | |
355 | Set this to a non-empty string to cause the \fItime\fP module to | |
356 | require dates specified as strings to include 4-digit years, otherwise | |
357 | 2-digit years are converted based on rules described in the \fItime\fP | |
358 | module documentation. | |
359 | .IP PYTHONOPTIMIZE | |
360 | If this is set to a non-empty string it is equivalent to specifying | |
361 | the \fB\-O\fP option. If set to an integer, it is equivalent to | |
362 | specifying \fB\-O\fP multiple times. | |
363 | .IP PYTHONDEBUG | |
364 | If this is set to a non-empty string it is equivalent to specifying | |
365 | the \fB\-d\fP option. If set to an integer, it is equivalent to | |
366 | specifying \fB\-d\fP multiple times. | |
367 | .IP PYTHONINSPECT | |
368 | If this is set to a non-empty string it is equivalent to specifying | |
369 | the \fB\-i\fP option. | |
370 | .IP PYTHONUNBUFFERED | |
371 | If this is set to a non-empty string it is equivalent to specifying | |
372 | the \fB\-u\fP option. | |
373 | .IP PYTHONVERBOSE | |
374 | If this is set to a non-empty string it is equivalent to specifying | |
375 | the \fB\-v\fP option. If set to an integer, it is equivalent to | |
376 | specifying \fB\-v\fP multiple times. | |
377 | .SH AUTHOR | |
378 | The Python Software Foundation: http://www.python.org/psf | |
379 | .SH INTERNET RESOURCES | |
380 | Main website: http://www.python.org/ | |
381 | .br | |
382 | Documentation: http://docs.python.org/ | |
383 | .br | |
384 | Community website: http://starship.python.net/ | |
385 | .br | |
386 | Developer resources: http://www.python.org/dev/ | |
387 | .br | |
388 | FTP: ftp://ftp.python.org/pub/python/ | |
389 | .br | |
390 | Module repository: http://www.vex.net/parnassus/ | |
391 | .br | |
392 | Newsgroups: comp.lang.python, comp.lang.python.announce | |
393 | .SH LICENSING | |
394 | Python is distributed under an Open Source license. See the file | |
395 | "LICENSE" in the Python source distribution for information on terms & | |
396 | conditions for accessing and otherwise using Python and for a | |
397 | DISCLAIMER OF ALL WARRANTIES. |