Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man1/python3.1 @ 68:5028fdace37b

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