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