Showing the changes to sys/src/cmd/python/Misc/python.man (1 of 3706 files). Show all
Unified · Split
| @@ -0,0 +1,397 @@ | ||
| 1 | +.TH PYTHON "1" "$Date: 2005-03-21 01:16:03 +1100 (Mon, 21 Mar 2005) $" | |
| 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. | |