logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

python3.1 (18354B)


  1. .TH PYTHON "1"
  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 \-B
  10. ]
  11. [
  12. .B \-b
  13. ]
  14. [
  15. .B \-d
  16. ]
  17. [
  18. .B \-E
  19. ]
  20. [
  21. .B \-h
  22. ]
  23. [
  24. .B \-i
  25. ]
  26. [
  27. .B \-I
  28. ]
  29. .br
  30. [
  31. .B \-m
  32. .I module-name
  33. ]
  34. [
  35. .B \-q
  36. ]
  37. [
  38. .B \-O
  39. ]
  40. [
  41. .B \-OO
  42. ]
  43. [
  44. .B \-s
  45. ]
  46. [
  47. .B \-S
  48. ]
  49. [
  50. .B \-u
  51. ]
  52. .br
  53. [
  54. .B \-v
  55. ]
  56. [
  57. .B \-V
  58. ]
  59. [
  60. .B \-W
  61. .I argument
  62. ]
  63. [
  64. .B \-x
  65. ]
  66. [
  67. [
  68. .B \-X
  69. .I option
  70. ]
  71. .B \-?
  72. ]
  73. .br
  74. [
  75. .B \--check-hash-based-pycs
  76. .I default
  77. |
  78. .I always
  79. |
  80. .I never
  81. ]
  82. .br
  83. [
  84. .B \-c
  85. .I command
  86. |
  87. .I script
  88. |
  89. \-
  90. ]
  91. [
  92. .I arguments
  93. ]
  94. .SH DESCRIPTION
  95. Python is an interpreted, interactive, object-oriented programming
  96. language that combines remarkable power with very clear syntax.
  97. For an introduction to programming in Python, see the Python Tutorial.
  98. The Python Library Reference documents built-in and standard types,
  99. constants, functions and modules.
  100. Finally, the Python Reference Manual describes the syntax and
  101. semantics of the core language in (perhaps too) much detail.
  102. (These documents may be located via the
  103. .B "INTERNET RESOURCES"
  104. below; they may be installed on your system as well.)
  105. .PP
  106. Python's basic power can be extended with your own modules written in
  107. C or C++.
  108. On most systems such modules may be dynamically loaded.
  109. Python is also adaptable as an extension language for existing
  110. applications.
  111. See the internal documentation for hints.
  112. .PP
  113. Documentation for installed Python modules and packages can be
  114. viewed by running the
  115. .B pydoc
  116. program.
  117. .SH COMMAND LINE OPTIONS
  118. .TP
  119. .B \-B
  120. Don't write
  121. .I .pyc
  122. files on import. See also PYTHONDONTWRITEBYTECODE.
  123. .TP
  124. .B \-b
  125. Issue warnings about str(bytes_instance), str(bytearray_instance)
  126. and comparing bytes/bytearray with str. (-bb: issue errors)
  127. .TP
  128. .BI "\-c " command
  129. Specify the command to execute (see next section).
  130. This terminates the option list (following options are passed as
  131. arguments to the command).
  132. .TP
  133. .BI "\-\-check-hash-based-pycs " mode
  134. Configure how Python evaluates the up-to-dateness of hash-based .pyc files.
  135. .TP
  136. .B \-d
  137. Turn on parser debugging output (for expert only, depending on
  138. compilation options).
  139. .TP
  140. .B \-E
  141. Ignore environment variables like PYTHONPATH and PYTHONHOME that modify
  142. the behavior of the interpreter.
  143. .TP
  144. .B \-h ", " \-? ", "\-\-help
  145. Prints the usage for the interpreter executable and exits.
  146. .TP
  147. .B \-i
  148. When a script is passed as first argument or the \fB\-c\fP option is
  149. used, enter interactive mode after executing the script or the
  150. command. It does not read the $PYTHONSTARTUP file. This can be
  151. useful to inspect global variables or a stack trace when a script
  152. raises an exception.
  153. .TP
  154. .B \-I
  155. Run Python in isolated mode. This also implies \fB\-E\fP and \fB\-s\fP. In
  156. isolated mode sys.path contains neither the script's directory nor the user's
  157. site-packages directory. All PYTHON* environment variables are ignored, too.
  158. Further restrictions may be imposed to prevent the user from injecting
  159. malicious code.
  160. .TP
  161. .BI "\-m " module-name
  162. Searches
  163. .I sys.path
  164. for the named module and runs the corresponding
  165. .I .py
  166. file as a script. This terminates the option list (following options
  167. are passed as arguments to the module).
  168. .TP
  169. .B \-O
  170. Remove assert statements and any code conditional on the value of
  171. __debug__; augment the filename for compiled (bytecode) files by
  172. adding .opt-1 before the .pyc extension.
  173. .TP
  174. .B \-OO
  175. Do \fB-O\fP and also discard docstrings; change the filename for
  176. compiled (bytecode) files by adding .opt-2 before the .pyc extension.
  177. .TP
  178. .B \-q
  179. Do not print the version and copyright messages. These messages are
  180. also suppressed in non-interactive mode.
  181. .TP
  182. .B \-s
  183. Don't add user site directory to sys.path.
  184. .TP
  185. .B \-S
  186. Disable the import of the module
  187. .I site
  188. and the site-dependent manipulations of
  189. .I sys.path
  190. that it entails. Also disable these manipulations if
  191. .I site
  192. is explicitly imported later.
  193. .TP
  194. .B \-u
  195. Force the stdout and stderr streams to be unbuffered.
  196. This option has no effect on the stdin stream.
  197. .TP
  198. .B \-v
  199. Print a message each time a module is initialized, showing the place
  200. (filename or built-in module) from which it is loaded. When given
  201. twice, print a message for each file that is checked for when
  202. searching for a module. Also provides information on module cleanup
  203. at exit.
  204. .TP
  205. .B \-V ", " \-\-version
  206. Prints the Python version number of the executable and exits. When given
  207. twice, print more information about the build.
  208. .TP
  209. .BI "\-W " argument
  210. Warning control. Python's warning machinery by default prints warning messages
  211. to
  212. .IR sys.stderr .
  213. The simplest settings apply a particular action unconditionally to all warnings
  214. emitted by a process (even those that are otherwise ignored by default):
  215. -Wdefault # Warn once per call location
  216. -Werror # Convert to exceptions
  217. -Walways # Warn every time
  218. -Wmodule # Warn once per calling module
  219. -Wonce # Warn once per Python process
  220. -Wignore # Never warn
  221. The action names can be abbreviated as desired and the interpreter will resolve
  222. them to the appropriate action name. For example,
  223. .B -Wi
  224. is the same as
  225. .B -Wignore .
  226. The full form of argument is:
  227. .IB action:message:category:module:lineno
  228. Empty fields match all values; trailing empty fields may be omitted. For
  229. example
  230. .B -W ignore::DeprecationWarning
  231. ignores all DeprecationWarning warnings.
  232. The
  233. .I action
  234. field is as explained above but only applies to warnings that match
  235. the remaining fields.
  236. The
  237. .I message
  238. field must match the whole printed warning message; this match is
  239. case-insensitive.
  240. The
  241. .I category
  242. field matches the warning category (ex: "DeprecationWarning"). This must be a
  243. class name; the match test whether the actual warning category of the message
  244. is a subclass of the specified warning category.
  245. The
  246. .I module
  247. field matches the (fully-qualified) module name; this match is case-sensitive.
  248. The
  249. .I lineno
  250. field matches the line number, where zero matches all line numbers and is thus
  251. equivalent to an omitted line number.
  252. Multiple
  253. .B -W
  254. options can be given; when a warning matches more than one option, the action
  255. for the last matching option is performed. Invalid
  256. .B -W
  257. options are ignored (though, a warning message is printed about invalid options
  258. when the first warning is issued).
  259. Warnings can also be controlled using the
  260. .B PYTHONWARNINGS
  261. environment variable and from within a Python program using the warnings
  262. module. For example, the warnings.filterwarnings() function can be used to use
  263. a regular expression on the warning message.
  264. .TP
  265. .BI "\-X " option
  266. Set implementation specific option. The following options are available:
  267. -X faulthandler: enable faulthandler
  268. -X showrefcount: output the total reference count and number of used
  269. memory blocks when the program finishes or after each statement in the
  270. interactive interpreter. This only works on debug builds
  271. -X tracemalloc: start tracing Python memory allocations using the
  272. tracemalloc module. By default, only the most recent frame is stored in a
  273. traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a
  274. traceback limit of NFRAME frames
  275. -X importtime: show how long each import takes. It shows module name,
  276. cumulative time (including nested imports) and self time (excluding
  277. nested imports). Note that its output may be broken in multi-threaded
  278. application. Typical usage is python3 -X importtime -c 'import asyncio'
  279. -X dev: enable CPython's "development mode", introducing additional runtime
  280. checks which are too expensive to be enabled by default. It will not be
  281. more verbose than the default if the code is correct: new warnings are
  282. only emitted when an issue is detected. Effect of the developer mode:
  283. * Add default warning filter, as -W default
  284. * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks() C function
  285. * Enable the faulthandler module to dump the Python traceback on a crash
  286. * Enable asyncio debug mode
  287. * Set the dev_mode attribute of sys.flags to True
  288. * io.IOBase destructor logs close() exceptions
  289. -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default
  290. locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would
  291. otherwise activate automatically). See PYTHONUTF8 for more details
  292. -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the
  293. given directory instead of to the code tree.
  294. .TP
  295. .B \-x
  296. Skip the first line of the source. This is intended for a DOS
  297. specific hack only. Warning: the line numbers in error messages will
  298. be off by one!
  299. .SH INTERPRETER INTERFACE
  300. The interpreter interface resembles that of the UNIX shell: when
  301. called with standard input connected to a tty device, it prompts for
  302. commands and executes them until an EOF is read; when called with a
  303. file name argument or with a file as standard input, it reads and
  304. executes a
  305. .I script
  306. from that file;
  307. when called with
  308. .B \-c
  309. .IR command ,
  310. it executes the Python statement(s) given as
  311. .IR command .
  312. Here
  313. .I command
  314. may contain multiple statements separated by newlines.
  315. Leading whitespace is significant in Python statements!
  316. In non-interactive mode, the entire input is parsed before it is
  317. executed.
  318. .PP
  319. If available, the script name and additional arguments thereafter are
  320. passed to the script in the Python variable
  321. .IR sys.argv ,
  322. which is a list of strings (you must first
  323. .I import sys
  324. to be able to access it).
  325. If no script name is given,
  326. .I sys.argv[0]
  327. is an empty string; if
  328. .B \-c
  329. is used,
  330. .I sys.argv[0]
  331. contains the string
  332. .I '-c'.
  333. Note that options interpreted by the Python interpreter itself
  334. are not placed in
  335. .IR sys.argv .
  336. .PP
  337. In interactive mode, the primary prompt is `>>>'; the second prompt
  338. (which appears when a command is not complete) is `...'.
  339. The prompts can be changed by assignment to
  340. .I sys.ps1
  341. or
  342. .IR sys.ps2 .
  343. The interpreter quits when it reads an EOF at a prompt.
  344. When an unhandled exception occurs, a stack trace is printed and
  345. control returns to the primary prompt; in non-interactive mode, the
  346. interpreter exits after printing the stack trace.
  347. The interrupt signal raises the
  348. .I Keyboard\%Interrupt
  349. exception; other UNIX signals are not caught (except that SIGPIPE is
  350. sometimes ignored, in favor of the
  351. .I IOError
  352. exception). Error messages are written to stderr.
  353. .SH FILES AND DIRECTORIES
  354. These are subject to difference depending on local installation
  355. conventions; ${prefix} and ${exec_prefix} are installation-dependent
  356. and should be interpreted as for GNU software; they may be the same.
  357. The default for both is \fI/usr/local\fP.
  358. .IP \fI${exec_prefix}/bin/python\fP
  359. Recommended location of the interpreter.
  360. .PP
  361. .I ${prefix}/lib/python<version>
  362. .br
  363. .I ${exec_prefix}/lib/python<version>
  364. .RS
  365. Recommended locations of the directories containing the standard
  366. modules.
  367. .RE
  368. .PP
  369. .I ${prefix}/include/python<version>
  370. .br
  371. .I ${exec_prefix}/include/python<version>
  372. .RS
  373. Recommended locations of the directories containing the include files
  374. needed for developing Python extensions and embedding the
  375. interpreter.
  376. .RE
  377. .SH ENVIRONMENT VARIABLES
  378. .IP PYTHONHOME
  379. Change the location of the standard Python libraries. By default, the
  380. libraries are searched in ${prefix}/lib/python<version> and
  381. ${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
  382. are installation-dependent directories, both defaulting to
  383. \fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value
  384. replaces both ${prefix} and ${exec_prefix}. To specify different values
  385. for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
  386. .IP PYTHONPATH
  387. Augments the default search path for module files.
  388. The format is the same as the shell's $PATH: one or more directory
  389. pathnames separated by colons.
  390. Non-existent directories are silently ignored.
  391. The default search path is installation dependent, but generally
  392. begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
  393. The default search path is always appended to $PYTHONPATH.
  394. If a script argument is given, the directory containing the script is
  395. inserted in the path in front of $PYTHONPATH.
  396. The search path can be manipulated from within a Python program as the
  397. variable
  398. .IR sys.path .
  399. .IP PYTHONPLATLIBDIR
  400. Override sys.platlibdir.
  401. .IP PYTHONSTARTUP
  402. If this is the name of a readable file, the Python commands in that
  403. file are executed before the first prompt is displayed in interactive
  404. mode.
  405. The file is executed in the same name space where interactive commands
  406. are executed so that objects defined or imported in it can be used
  407. without qualification in the interactive session.
  408. You can also change the prompts
  409. .I sys.ps1
  410. and
  411. .I sys.ps2
  412. in this file.
  413. .IP PYTHONOPTIMIZE
  414. If this is set to a non-empty string it is equivalent to specifying
  415. the \fB\-O\fP option. If set to an integer, it is equivalent to
  416. specifying \fB\-O\fP multiple times.
  417. .IP PYTHONDEBUG
  418. If this is set to a non-empty string it is equivalent to specifying
  419. the \fB\-d\fP option. If set to an integer, it is equivalent to
  420. specifying \fB\-d\fP multiple times.
  421. .IP PYTHONDONTWRITEBYTECODE
  422. If this is set to a non-empty string it is equivalent to specifying
  423. the \fB\-B\fP option (don't try to write
  424. .I .pyc
  425. files).
  426. .IP PYTHONINSPECT
  427. If this is set to a non-empty string it is equivalent to specifying
  428. the \fB\-i\fP option.
  429. .IP PYTHONIOENCODING
  430. If this is set before running the interpreter, it overrides the encoding used
  431. for stdin/stdout/stderr, in the syntax
  432. .IB encodingname ":" errorhandler
  433. The
  434. .IB errorhandler
  435. part is optional and has the same meaning as in str.encode. For stderr, the
  436. .IB errorhandler
  437. part is ignored; the handler will always be \'backslashreplace\'.
  438. .IP PYTHONNOUSERSITE
  439. If this is set to a non-empty string it is equivalent to specifying the
  440. \fB\-s\fP option (Don't add the user site directory to sys.path).
  441. .IP PYTHONUNBUFFERED
  442. If this is set to a non-empty string it is equivalent to specifying
  443. the \fB\-u\fP option.
  444. .IP PYTHONVERBOSE
  445. If this is set to a non-empty string it is equivalent to specifying
  446. the \fB\-v\fP option. If set to an integer, it is equivalent to
  447. specifying \fB\-v\fP multiple times.
  448. .IP PYTHONWARNINGS
  449. If this is set to a comma-separated string it is equivalent to
  450. specifying the \fB\-W\fP option for each separate value.
  451. .IP PYTHONHASHSEED
  452. If this variable is set to "random", a random value is used to seed the hashes
  453. of str and bytes objects.
  454. If PYTHONHASHSEED is set to an integer value, it is used as a fixed seed for
  455. generating the hash() of the types covered by the hash randomization. Its
  456. purpose is to allow repeatable hashing, such as for selftests for the
  457. interpreter itself, or to allow a cluster of python processes to share hash
  458. values.
  459. The integer must be a decimal number in the range [0,4294967295]. Specifying
  460. the value 0 will disable hash randomization.
  461. .IP PYTHONMALLOC
  462. Set the Python memory allocators and/or install debug hooks. The available
  463. memory allocators are
  464. .IR malloc
  465. and
  466. .IR pymalloc .
  467. The available debug hooks are
  468. .IR debug ,
  469. .IR malloc_debug ,
  470. and
  471. .IR pymalloc_debug .
  472. .IP
  473. When Python is compiled in debug mode, the default is
  474. .IR pymalloc_debug
  475. and the debug hooks are automatically used. Otherwise, the default is
  476. .IR pymalloc .
  477. .IP PYTHONMALLOCSTATS
  478. If set to a non-empty string, Python will print statistics of the pymalloc
  479. memory allocator every time a new pymalloc object arena is created, and on
  480. shutdown.
  481. .IP
  482. This variable is ignored if the
  483. .RB $ PYTHONMALLOC
  484. environment variable is used to force the
  485. .BR malloc (3)
  486. allocator of the C library, or if Python is configured without pymalloc support.
  487. .IP PYTHONASYNCIODEBUG
  488. If this environment variable is set to a non-empty string, enable the debug
  489. mode of the asyncio module.
  490. .IP PYTHONTRACEMALLOC
  491. If this environment variable is set to a non-empty string, start tracing
  492. Python memory allocations using the tracemalloc module.
  493. .IP
  494. The value of the variable is the maximum number of frames stored in a
  495. traceback of a trace. For example,
  496. .IB PYTHONTRACEMALLOC=1
  497. stores only the most recent frame.
  498. .IP PYTHONFAULTHANDLER
  499. If this environment variable is set to a non-empty string,
  500. .IR faulthandler.enable()
  501. is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS
  502. and SIGILL signals to dump the Python traceback.
  503. .IP
  504. This is equivalent to the \fB-X faulthandler\fP option.
  505. .IP PYTHONEXECUTABLE
  506. If this environment variable is set,
  507. .IB sys.argv[0]
  508. will be set to its value instead of the value got through the C runtime. Only
  509. works on Mac OS X.
  510. .IP PYTHONUSERBASE
  511. Defines the user base directory, which is used to compute the path of the user
  512. .IR site-packages
  513. directory and Distutils installation paths for
  514. .IR "python setup\.py install \-\-user" .
  515. .IP PYTHONPROFILEIMPORTTIME
  516. If this environment variable is set to a non-empty string, Python will
  517. show how long each import takes. This is exactly equivalent to setting
  518. \fB\-X importtime\fP on the command line.
  519. .IP PYTHONBREAKPOINT
  520. If this environment variable is set to 0, it disables the default debugger. It
  521. can be set to the callable of your debugger of choice.
  522. .SS Debug-mode variables
  523. Setting these variables only has an effect in a debug build of Python, that is,
  524. if Python was configured with the
  525. \fB\--with-pydebug\fP build option.
  526. .IP PYTHONTHREADDEBUG
  527. If this environment variable is set, Python will print threading debug info.
  528. The feature is deprecated in Python 3.10 and will be removed in Python 3.12.
  529. .IP PYTHONDUMPREFS
  530. If this environment variable is set, Python will dump objects and reference
  531. counts still alive after shutting down the interpreter.
  532. .SH AUTHOR
  533. The Python Software Foundation: https://www.python.org/psf/
  534. .SH INTERNET RESOURCES
  535. Main website: https://www.python.org/
  536. .br
  537. Documentation: https://docs.python.org/
  538. .br
  539. Developer resources: https://devguide.python.org/
  540. .br
  541. Downloads: https://www.python.org/downloads/
  542. .br
  543. Module repository: https://pypi.org/
  544. .br
  545. Newsgroups: comp.lang.python, comp.lang.python.announce
  546. .SH LICENSING
  547. Python is distributed under an Open Source license. See the file
  548. "LICENSE" in the Python source distribution for information on terms &
  549. conditions for accessing and otherwise using Python and for a
  550. DISCLAIMER OF ALL WARRANTIES.