1 .TH PYTHON "1" "$Date: 2005-03-20 09:16:03 -0500 (Sun, 20 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.