jpayne@68: .TH PYTHON "1"
jpayne@68: 
jpayne@68: .\" To view this file while editing, run it through groff:
jpayne@68: .\"   groff -Tascii -man python.man | less
jpayne@68: 
jpayne@68: .SH NAME
jpayne@68: python \- an interpreted, interactive, object-oriented programming language
jpayne@68: .SH SYNOPSIS
jpayne@68: .B python
jpayne@68: [
jpayne@68: .B \-B
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-b
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-d
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-E
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-h
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-i
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-I
jpayne@68: ]
jpayne@68: .br
jpayne@68:        [
jpayne@68: .B \-m
jpayne@68: .I module-name
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-q
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-O
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-OO
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-s
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-S
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-u
jpayne@68: ]
jpayne@68: .br
jpayne@68:        [
jpayne@68: .B \-v
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-V
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-W
jpayne@68: .I argument
jpayne@68: ]
jpayne@68: [
jpayne@68: .B \-x
jpayne@68: ]
jpayne@68: [
jpayne@68: [
jpayne@68: .B \-X
jpayne@68: .I option
jpayne@68: ]
jpayne@68: .B \-?
jpayne@68: ]
jpayne@68: .br
jpayne@68:        [
jpayne@68: .B \--check-hash-based-pycs
jpayne@68: .I default
jpayne@68: |
jpayne@68: .I always
jpayne@68: |
jpayne@68: .I never
jpayne@68: ]
jpayne@68: .br
jpayne@68:        [
jpayne@68: .B \-c
jpayne@68: .I command
jpayne@68: |
jpayne@68: .I script
jpayne@68: |
jpayne@68: \-
jpayne@68: ]
jpayne@68: [
jpayne@68: .I arguments
jpayne@68: ]
jpayne@68: .SH DESCRIPTION
jpayne@68: Python is an interpreted, interactive, object-oriented programming
jpayne@68: language that combines remarkable power with very clear syntax.
jpayne@68: For an introduction to programming in Python, see the Python Tutorial.
jpayne@68: The Python Library Reference documents built-in and standard types,
jpayne@68: constants, functions and modules.
jpayne@68: Finally, the Python Reference Manual describes the syntax and
jpayne@68: semantics of the core language in (perhaps too) much detail.
jpayne@68: (These documents may be located via the
jpayne@68: .B "INTERNET RESOURCES"
jpayne@68: below; they may be installed on your system as well.)
jpayne@68: .PP
jpayne@68: Python's basic power can be extended with your own modules written in
jpayne@68: C or C++.
jpayne@68: On most systems such modules may be dynamically loaded.
jpayne@68: Python is also adaptable as an extension language for existing
jpayne@68: applications.
jpayne@68: See the internal documentation for hints.
jpayne@68: .PP
jpayne@68: Documentation for installed Python modules and packages can be
jpayne@68: viewed by running the
jpayne@68: .B pydoc
jpayne@68: program.
jpayne@68: .SH COMMAND LINE OPTIONS
jpayne@68: .TP
jpayne@68: .B \-B
jpayne@68: Don't write
jpayne@68: .I .pyc
jpayne@68: files on import. See also PYTHONDONTWRITEBYTECODE.
jpayne@68: .TP
jpayne@68: .B \-b
jpayne@68: Issue warnings about str(bytes_instance), str(bytearray_instance)
jpayne@68: and comparing bytes/bytearray with str. (-bb: issue errors)
jpayne@68: .TP
jpayne@68: .BI "\-c " command
jpayne@68: Specify the command to execute (see next section).
jpayne@68: This terminates the option list (following options are passed as
jpayne@68: arguments to the command).
jpayne@68: .TP
jpayne@68: .BI "\-\-check-hash-based-pycs " mode
jpayne@68: Configure how Python evaluates the up-to-dateness of hash-based .pyc files.
jpayne@68: .TP
jpayne@68: .B \-d
jpayne@68: Turn on parser debugging output (for expert only, depending on
jpayne@68: compilation options).
jpayne@68: .TP
jpayne@68: .B \-E
jpayne@68: Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
jpayne@68: the behavior of the interpreter.
jpayne@68: .TP
jpayne@68: .B \-h ", " \-? ", "\-\-help
jpayne@68: Prints the usage for the interpreter executable and exits.
jpayne@68: .TP
jpayne@68: .B \-i
jpayne@68: When a script is passed as first argument or the \fB\-c\fP option is
jpayne@68: used, enter interactive mode after executing the script or the
jpayne@68: command.  It does not read the $PYTHONSTARTUP file.  This can be
jpayne@68: useful to inspect global variables or a stack trace when a script
jpayne@68: raises an exception.
jpayne@68: .TP
jpayne@68: .B \-I
jpayne@68: Run Python in isolated mode. This also implies \fB\-E\fP and \fB\-s\fP. In
jpayne@68: isolated mode sys.path contains neither the script's directory nor the user's
jpayne@68: site-packages directory. All PYTHON* environment variables are ignored, too.
jpayne@68: Further restrictions may be imposed to prevent the user from injecting
jpayne@68: malicious code.
jpayne@68: .TP
jpayne@68: .BI "\-m " module-name
jpayne@68: Searches
jpayne@68: .I sys.path
jpayne@68: for the named module and runs the corresponding
jpayne@68: .I .py
jpayne@68: file as a script.
jpayne@68: .TP
jpayne@68: .B \-O
jpayne@68: Remove assert statements and any code conditional on the value of
jpayne@68: __debug__; augment the filename for compiled (bytecode) files by
jpayne@68: adding .opt-1 before the .pyc extension.
jpayne@68: .TP
jpayne@68: .B \-OO
jpayne@68: Do \fB-O\fP and also discard docstrings; change the filename for
jpayne@68: compiled (bytecode) files by adding .opt-2 before the .pyc extension.
jpayne@68: .TP
jpayne@68: .B \-q
jpayne@68: Do not print the version and copyright messages. These messages are
jpayne@68: also suppressed in non-interactive mode.
jpayne@68: .TP
jpayne@68: .B \-s
jpayne@68: Don't add user site directory to sys.path.
jpayne@68: .TP
jpayne@68: .B \-S
jpayne@68: Disable the import of the module
jpayne@68: .I site
jpayne@68: and the site-dependent manipulations of
jpayne@68: .I sys.path
jpayne@68: that it entails.  Also disable these manipulations if
jpayne@68: .I site
jpayne@68: is explicitly imported later.
jpayne@68: .TP
jpayne@68: .B \-u
jpayne@68: Force the stdout and stderr streams to be unbuffered.
jpayne@68: This option has no effect on the stdin stream.
jpayne@68: .TP
jpayne@68: .B \-v
jpayne@68: Print a message each time a module is initialized, showing the place
jpayne@68: (filename or built-in module) from which it is loaded.  When given
jpayne@68: twice, print a message for each file that is checked for when
jpayne@68: searching for a module.  Also provides information on module cleanup
jpayne@68: at exit.
jpayne@68: .TP
jpayne@68: .B \-V ", " \-\-version
jpayne@68: Prints the Python version number of the executable and exits.  When given
jpayne@68: twice, print more information about the build.
jpayne@68: .TP
jpayne@68: .BI "\-W " argument
jpayne@68: Warning control.  Python sometimes prints warning message to
jpayne@68: .IR sys.stderr .
jpayne@68: A typical warning message has the following form:
jpayne@68: .IB file ":" line ": " category ": " message.
jpayne@68: By default, each warning is printed once for each source line where it
jpayne@68: occurs.  This option controls how often warnings are printed.
jpayne@68: Multiple
jpayne@68: .B \-W
jpayne@68: options may be given; when a warning matches more than one
jpayne@68: option, the action for the last matching option is performed.
jpayne@68: Invalid
jpayne@68: .B \-W
jpayne@68: options are ignored (a warning message is printed about invalid
jpayne@68: options when the first warning is issued).  Warnings can also be
jpayne@68: controlled from within a Python program using the
jpayne@68: .I warnings
jpayne@68: module.
jpayne@68: 
jpayne@68: The simplest form of
jpayne@68: .I argument
jpayne@68: is one of the following
jpayne@68: .I action
jpayne@68: strings (or a unique abbreviation):
jpayne@68: .B ignore
jpayne@68: to ignore all warnings;
jpayne@68: .B default
jpayne@68: to explicitly request the default behavior (printing each warning once
jpayne@68: per source line);
jpayne@68: .B all
jpayne@68: to print a warning each time it occurs (this may generate many
jpayne@68: messages if a warning is triggered repeatedly for the same source
jpayne@68: line, such as inside a loop);
jpayne@68: .B module
jpayne@68: to print each warning only the first time it occurs in each
jpayne@68: module;
jpayne@68: .B once
jpayne@68: to print each warning only the first time it occurs in the program; or
jpayne@68: .B error
jpayne@68: to raise an exception instead of printing a warning message.
jpayne@68: 
jpayne@68: The full form of
jpayne@68: .I argument
jpayne@68: is
jpayne@68: .IB action : message : category : module : line.
jpayne@68: Here,
jpayne@68: .I action
jpayne@68: is as explained above but only applies to messages that match the
jpayne@68: remaining fields.  Empty fields match all values; trailing empty
jpayne@68: fields may be omitted.  The
jpayne@68: .I message
jpayne@68: field matches the start of the warning message printed; this match is
jpayne@68: case-insensitive.  The
jpayne@68: .I category
jpayne@68: field matches the warning category.  This must be a class name; the
jpayne@68: match test whether the actual warning category of the message is a
jpayne@68: subclass of the specified warning category.  The full class name must
jpayne@68: be given.  The
jpayne@68: .I module
jpayne@68: field matches the (fully-qualified) module name; this match is
jpayne@68: case-sensitive.  The
jpayne@68: .I line
jpayne@68: field matches the line number, where zero matches all line numbers and
jpayne@68: is thus equivalent to an omitted line number.
jpayne@68: .TP
jpayne@68: .BI "\-X " option
jpayne@68: Set implementation specific option.
jpayne@68: .TP
jpayne@68: .B \-x
jpayne@68: Skip the first line of the source.  This is intended for a DOS
jpayne@68: specific hack only.  Warning: the line numbers in error messages will
jpayne@68: be off by one!
jpayne@68: .SH INTERPRETER INTERFACE
jpayne@68: The interpreter interface resembles that of the UNIX shell: when
jpayne@68: called with standard input connected to a tty device, it prompts for
jpayne@68: commands and executes them until an EOF is read; when called with a
jpayne@68: file name argument or with a file as standard input, it reads and
jpayne@68: executes a
jpayne@68: .I script
jpayne@68: from that file;
jpayne@68: when called with
jpayne@68: .B \-c
jpayne@68: .IR command ,
jpayne@68: it executes the Python statement(s) given as
jpayne@68: .IR command .
jpayne@68: Here
jpayne@68: .I command
jpayne@68: may contain multiple statements separated by newlines.
jpayne@68: Leading whitespace is significant in Python statements!
jpayne@68: In non-interactive mode, the entire input is parsed before it is
jpayne@68: executed.
jpayne@68: .PP
jpayne@68: If available, the script name and additional arguments thereafter are
jpayne@68: passed to the script in the Python variable
jpayne@68: .IR sys.argv ,
jpayne@68: which is a list of strings (you must first
jpayne@68: .I import sys
jpayne@68: to be able to access it).
jpayne@68: If no script name is given,
jpayne@68: .I sys.argv[0]
jpayne@68: is an empty string; if
jpayne@68: .B \-c
jpayne@68: is used,
jpayne@68: .I sys.argv[0]
jpayne@68: contains the string
jpayne@68: .I '-c'.
jpayne@68: Note that options interpreted by the Python interpreter itself
jpayne@68: are not placed in
jpayne@68: .IR sys.argv .
jpayne@68: .PP
jpayne@68: In interactive mode, the primary prompt is `>>>'; the second prompt
jpayne@68: (which appears when a command is not complete) is `...'.
jpayne@68: The prompts can be changed by assignment to
jpayne@68: .I sys.ps1
jpayne@68: or
jpayne@68: .IR sys.ps2 .
jpayne@68: The interpreter quits when it reads an EOF at a prompt.
jpayne@68: When an unhandled exception occurs, a stack trace is printed and
jpayne@68: control returns to the primary prompt; in non-interactive mode, the
jpayne@68: interpreter exits after printing the stack trace.
jpayne@68: The interrupt signal raises the
jpayne@68: .I Keyboard\%Interrupt
jpayne@68: exception; other UNIX signals are not caught (except that SIGPIPE is
jpayne@68: sometimes ignored, in favor of the
jpayne@68: .I IOError
jpayne@68: exception).  Error messages are written to stderr.
jpayne@68: .SH FILES AND DIRECTORIES
jpayne@68: These are subject to difference depending on local installation
jpayne@68: conventions; ${prefix} and ${exec_prefix} are installation-dependent
jpayne@68: and should be interpreted as for GNU software; they may be the same.
jpayne@68: The default for both is \fI/usr/local\fP.
jpayne@68: .IP \fI${exec_prefix}/bin/python\fP
jpayne@68: Recommended location of the interpreter.
jpayne@68: .PP
jpayne@68: .I ${prefix}/lib/python<version>
jpayne@68: .br
jpayne@68: .I ${exec_prefix}/lib/python<version>
jpayne@68: .RS
jpayne@68: Recommended locations of the directories containing the standard
jpayne@68: modules.
jpayne@68: .RE
jpayne@68: .PP
jpayne@68: .I ${prefix}/include/python<version>
jpayne@68: .br
jpayne@68: .I ${exec_prefix}/include/python<version>
jpayne@68: .RS
jpayne@68: Recommended locations of the directories containing the include files
jpayne@68: needed for developing Python extensions and embedding the
jpayne@68: interpreter.
jpayne@68: .RE
jpayne@68: .SH ENVIRONMENT VARIABLES
jpayne@68: .IP PYTHONHOME
jpayne@68: Change the location of the standard Python libraries.  By default, the
jpayne@68: libraries are searched in ${prefix}/lib/python<version> and
jpayne@68: ${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
jpayne@68: are installation-dependent directories, both defaulting to
jpayne@68: \fI/usr/local\fP.  When $PYTHONHOME is set to a single directory, its value
jpayne@68: replaces both ${prefix} and ${exec_prefix}.  To specify different values
jpayne@68: for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
jpayne@68: .IP PYTHONPATH
jpayne@68: Augments the default search path for module files.
jpayne@68: The format is the same as the shell's $PATH: one or more directory
jpayne@68: pathnames separated by colons.
jpayne@68: Non-existent directories are silently ignored.
jpayne@68: The default search path is installation dependent, but generally
jpayne@68: begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
jpayne@68: The default search path is always appended to $PYTHONPATH.
jpayne@68: If a script argument is given, the directory containing the script is
jpayne@68: inserted in the path in front of $PYTHONPATH.
jpayne@68: The search path can be manipulated from within a Python program as the
jpayne@68: variable
jpayne@68: .IR sys.path .
jpayne@68: .IP PYTHONSTARTUP
jpayne@68: If this is the name of a readable file, the Python commands in that
jpayne@68: file are executed before the first prompt is displayed in interactive
jpayne@68: mode.
jpayne@68: The file is executed in the same name space where interactive commands
jpayne@68: are executed so that objects defined or imported in it can be used
jpayne@68: without qualification in the interactive session.
jpayne@68: You can also change the prompts
jpayne@68: .I sys.ps1
jpayne@68: and
jpayne@68: .I sys.ps2
jpayne@68: in this file.
jpayne@68: .IP PYTHONOPTIMIZE
jpayne@68: If this is set to a non-empty string it is equivalent to specifying
jpayne@68: the \fB\-O\fP option. If set to an integer, it is equivalent to
jpayne@68: specifying \fB\-O\fP multiple times.
jpayne@68: .IP PYTHONDEBUG
jpayne@68: If this is set to a non-empty string it is equivalent to specifying
jpayne@68: the \fB\-d\fP option. If set to an integer, it is equivalent to
jpayne@68: specifying \fB\-d\fP multiple times.
jpayne@68: .IP PYTHONDONTWRITEBYTECODE
jpayne@68: If this is set to a non-empty string it is equivalent to specifying
jpayne@68: the \fB\-B\fP option (don't try to write
jpayne@68: .I .pyc
jpayne@68: files).
jpayne@68: .IP PYTHONINSPECT
jpayne@68: If this is set to a non-empty string it is equivalent to specifying
jpayne@68: the \fB\-i\fP option.
jpayne@68: .IP PYTHONIOENCODING
jpayne@68: If this is set before running the interpreter, it overrides the encoding used
jpayne@68: for stdin/stdout/stderr, in the syntax
jpayne@68: .IB encodingname ":" errorhandler
jpayne@68: The
jpayne@68: .IB errorhandler
jpayne@68: part is optional and has the same meaning as in str.encode. For stderr, the
jpayne@68: .IB errorhandler
jpayne@68:  part is ignored; the handler will always be \'backslashreplace\'.
jpayne@68: .IP PYTHONNOUSERSITE
jpayne@68: If this is set to a non-empty string it is equivalent to specifying the
jpayne@68: \fB\-s\fP option (Don't add the user site directory to sys.path).
jpayne@68: .IP PYTHONUNBUFFERED
jpayne@68: If this is set to a non-empty string it is equivalent to specifying
jpayne@68: the \fB\-u\fP option.
jpayne@68: .IP PYTHONVERBOSE
jpayne@68: If this is set to a non-empty string it is equivalent to specifying
jpayne@68: the \fB\-v\fP option. If set to an integer, it is equivalent to
jpayne@68: specifying \fB\-v\fP multiple times.
jpayne@68: .IP PYTHONWARNINGS
jpayne@68: If this is set to a comma-separated string it is equivalent to
jpayne@68: specifying the \fB\-W\fP option for each separate value.
jpayne@68: .IP PYTHONHASHSEED
jpayne@68: If this variable is set to "random", a random value is used to seed the hashes
jpayne@68: of str and bytes objects.
jpayne@68: 
jpayne@68: If PYTHONHASHSEED is set to an integer value, it is used as a fixed seed for
jpayne@68: generating the hash() of the types covered by the hash randomization.  Its
jpayne@68: purpose is to allow repeatable hashing, such as for selftests for the
jpayne@68: interpreter itself, or to allow a cluster of python processes to share hash
jpayne@68: values.
jpayne@68: 
jpayne@68: The integer must be a decimal number in the range [0,4294967295].  Specifying
jpayne@68: the value 0 will disable hash randomization.
jpayne@68: .IP PYTHONMALLOC
jpayne@68: Set the Python memory allocators and/or install debug hooks. The available
jpayne@68: memory allocators are
jpayne@68: .IR malloc
jpayne@68: and
jpayne@68: .IR pymalloc .
jpayne@68: The available debug hooks are
jpayne@68: .IR debug ,
jpayne@68: .IR malloc_debug ,
jpayne@68: and
jpayne@68: .IR pymalloc_debug .
jpayne@68: .IP
jpayne@68: When Python is compiled in debug mode, the default is
jpayne@68: .IR pymalloc_debug
jpayne@68: and the debug hooks are automatically used. Otherwise, the default is
jpayne@68: .IR pymalloc .
jpayne@68: .IP PYTHONMALLOCSTATS
jpayne@68: If set to a non-empty string, Python will print statistics of the pymalloc
jpayne@68: memory allocator every time a new pymalloc object arena is created, and on
jpayne@68: shutdown.
jpayne@68: .IP
jpayne@68: This variable is ignored if the
jpayne@68: .RB $ PYTHONMALLOC
jpayne@68: environment variable is used to force the
jpayne@68: .BR malloc (3)
jpayne@68: allocator of the C library, or if Python is configured without pymalloc support.
jpayne@68: .IP PYTHONASYNCIODEBUG
jpayne@68: If this environment variable is set to a non-empty string, enable the debug
jpayne@68: mode of the asyncio module.
jpayne@68: .IP PYTHONTRACEMALLOC
jpayne@68: If this environment variable is set to a non-empty string, start tracing
jpayne@68: Python memory allocations using the tracemalloc module.
jpayne@68: .IP
jpayne@68: The value of the variable is the maximum number of frames stored in a
jpayne@68: traceback of a trace. For example,
jpayne@68: .IB PYTHONTRACEMALLOC=1
jpayne@68: stores only the most recent frame.
jpayne@68: .IP PYTHONFAULTHANDLER
jpayne@68: If this environment variable is set to a non-empty string,
jpayne@68: .IR faulthandler.enable()
jpayne@68: is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS
jpayne@68: and SIGILL signals to dump the Python traceback.
jpayne@68: .IP
jpayne@68: This is equivalent to the \fB-X faulthandler\fP option.
jpayne@68: .IP PYTHONEXECUTABLE
jpayne@68: If this environment variable is set,
jpayne@68: .IB sys.argv[0]
jpayne@68: will be set to its value instead of the value got through the C runtime. Only
jpayne@68: works on Mac OS X.
jpayne@68: .IP PYTHONUSERBASE
jpayne@68: Defines the user base directory, which is used to compute the path of the user
jpayne@68: .IR site-packages
jpayne@68: directory and Distutils installation paths for
jpayne@68: .IR "python setup\.py install \-\-user" .
jpayne@68: .IP PYTHONPROFILEIMPORTTIME
jpayne@68: If this environment variable is set to a non-empty string, Python will
jpayne@68: show how long each import takes. This is exactly equivalent to setting
jpayne@68: \fB\-X importtime\fP on the command line.
jpayne@68: .IP PYTHONBREAKPOINT
jpayne@68: If this environment variable is set to 0, it disables the default debugger. It
jpayne@68: can be set to the callable of your debugger of choice.
jpayne@68: .SS Debug-mode variables
jpayne@68: Setting these variables only has an effect in a debug build of Python, that is,
jpayne@68: if Python was configured with the
jpayne@68: \fB\--with-pydebug\fP build option.
jpayne@68: .IP PYTHONTHREADDEBUG
jpayne@68: If this environment variable is set, Python will print threading debug info.
jpayne@68: .IP PYTHONDUMPREFS
jpayne@68: If this environment variable is set, Python will dump objects and reference
jpayne@68: counts still alive after shutting down the interpreter.
jpayne@68: .SH AUTHOR
jpayne@68: The Python Software Foundation: https://www.python.org/psf/
jpayne@68: .SH INTERNET RESOURCES
jpayne@68: Main website:  https://www.python.org/
jpayne@68: .br
jpayne@68: Documentation:  https://docs.python.org/
jpayne@68: .br
jpayne@68: Developer resources:  https://devguide.python.org/
jpayne@68: .br
jpayne@68: Downloads:  https://www.python.org/downloads/
jpayne@68: .br
jpayne@68: Module repository:  https://pypi.org/
jpayne@68: .br
jpayne@68: Newsgroups:  comp.lang.python, comp.lang.python.announce
jpayne@68: .SH LICENSING
jpayne@68: Python is distributed under an Open Source license.  See the file
jpayne@68: "LICENSE" in the Python source distribution for information on terms &
jpayne@68: conditions for accessing and otherwise using Python and for a
jpayne@68: DISCLAIMER OF ALL WARRANTIES.