/Misc/python.man

http://unladen-swallow.googlecode.com/ · Unknown · 401 lines · 397 code · 4 blank · 0 comment · 0 complexity · ff27c2d61262176a5f99f978677eee89 MD5 · raw file

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