Misc/python.man

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