Misc/python.man

   1 .TH PYTHON "1" "$Date$"
   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.