Debian Codegraph @

upstream/opensuse-tumbleweed/man1/python3.10.1

raw
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 .B \-X
70 .I option
71 ]
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. This terminates the option list (following options
169 are passed as arguments to the module).
170 .TP
171 .B \-O
172 Remove assert statements and any code conditional on the value of
173 __debug__; augment the filename for compiled (bytecode) files by
174 adding .opt-1 before the .pyc extension.
175 .TP
176 .B \-OO
177 Do \fB-O\fP and also discard docstrings; change the filename for
178 compiled (bytecode) files by adding .opt-2 before the .pyc extension.
179 .TP
180 .B \-q
181 Do not print the version and copyright messages. These messages are
182 also suppressed in non-interactive mode.
183 .TP
184 .B \-s
185 Don't add user site directory to sys.path.
186 .TP
187 .B \-S
188 Disable the import of the module
189 .I site
190 and the site-dependent manipulations of
191 .I sys.path
192 that it entails. Also disable these manipulations if
193 .I site
194 is explicitly imported later.
195 .TP
196 .B \-u
197 Force the stdout and stderr streams to be unbuffered.
198 This option has no effect on the stdin stream.
199 .TP
200 .B \-v
201 Print a message each time a module is initialized, showing the place
202 (filename or built-in module) from which it is loaded. When given
203 twice, print a message for each file that is checked for when
204 searching for a module. Also provides information on module cleanup
205 at exit.
206 .TP
207 .B \-V ", " \-\-version
208 Prints the Python version number of the executable and exits. When given
209 twice, print more information about the build.
210
211 .TP
212 .BI "\-W " argument
213 Warning control. Python's warning machinery by default prints warning messages
214 to
215 .IR sys.stderr .
216
217 The simplest settings apply a particular action unconditionally to all warnings
218 emitted by a process (even those that are otherwise ignored by default):
219
220 -Wdefault # Warn once per call location
221 -Werror # Convert to exceptions
222 -Walways # Warn every time
223 -Wmodule # Warn once per calling module
224 -Wonce # Warn once per Python process
225 -Wignore # Never warn
226
227 The action names can be abbreviated as desired and the interpreter will resolve
228 them to the appropriate action name. For example,
229 .B -Wi
230 is the same as
231 .B -Wignore .
232
233 The full form of argument is:
234 .IB action:message:category:module:lineno
235
236 Empty fields match all values; trailing empty fields may be omitted. For
237 example
238 .B -W ignore::DeprecationWarning
239 ignores all DeprecationWarning warnings.
240
241 The
242 .I action
243 field is as explained above but only applies to warnings that match
244 the remaining fields.
245
246 The
247 .I message
248 field must match the whole printed warning message; this match is
249 case-insensitive.
250
251 The
252 .I category
253 field matches the warning category (ex: "DeprecationWarning"). This must be a
254 class name; the match test whether the actual warning category of the message
255 is a subclass of the specified warning category.
256
257 The
258 .I module
259 field matches the (fully-qualified) module name; this match is case-sensitive.
260
261 The
262 .I lineno
263 field matches the line number, where zero matches all line numbers and is thus
264 equivalent to an omitted line number.
265
266 Multiple
267 .B -W
268 options can be given; when a warning matches more than one option, the action
269 for the last matching option is performed. Invalid
270 .B -W
271 options are ignored (though, a warning message is printed about invalid options
272 when the first warning is issued).
273
274 Warnings can also be controlled using the
275 .B PYTHONWARNINGS
276 environment variable and from within a Python program using the warnings
277 module. For example, the warnings.filterwarnings() function can be used to use
278 a regular expression on the warning message.
279
280 .TP
281 .BI "\-X " option
282 Set implementation specific option. The following options are available:
283
284 -X faulthandler: enable faulthandler
285
286 -X showrefcount: output the total reference count and number of used
287 memory blocks when the program finishes or after each statement in the
288 interactive interpreter. This only works on debug builds
289
290 -X tracemalloc: start tracing Python memory allocations using the
291 tracemalloc module. By default, only the most recent frame is stored in a
292 traceback of a trace. Use -X tracemalloc=NFRAME to start tracing with a
293 traceback limit of NFRAME frames
294
295 -X importtime: show how long each import takes. It shows module name,
296 cumulative time (including nested imports) and self time (excluding
297 nested imports). Note that its output may be broken in multi-threaded
298 application. Typical usage is python3 -X importtime -c 'import asyncio'
299
300 -X dev: enable CPython's "development mode", introducing additional runtime
301 checks which are too expensive to be enabled by default. It will not be
302 more verbose than the default if the code is correct: new warnings are
303 only emitted when an issue is detected. Effect of the developer mode:
304 * Add default warning filter, as -W default
305 * Install debug hooks on memory allocators: see the PyMem_SetupDebugHooks()
306 C function
307 * Enable the faulthandler module to dump the Python traceback on a crash
308 * Enable asyncio debug mode
309 * Set the dev_mode attribute of sys.flags to True
310 * io.IOBase destructor logs close() exceptions
311
312 -X utf8: enable UTF-8 mode for operating system interfaces, overriding the default
313 locale-aware mode. -X utf8=0 explicitly disables UTF-8 mode (even when it would
314 otherwise activate automatically). See PYTHONUTF8 for more details
315
316 -X pycache_prefix=PATH: enable writing .pyc files to a parallel tree rooted at the
317 given directory instead of to the code tree.
318
319 -X warn_default_encoding: enable opt-in EncodingWarning for 'encoding=None'
320
321 -X int_max_str_digits=number: limit the size of int<->str conversions.
322 This helps avoid denial of service attacks when parsing untrusted data.
323 The default is sys.int_info.default_max_str_digits. 0 disables.
324
325 .TP
326 .B \-x
327 Skip the first line of the source. This is intended for a DOS
328 specific hack only. Warning: the line numbers in error messages will
329 be off by one!
330 .SH INTERPRETER INTERFACE
331 The interpreter interface resembles that of the UNIX shell: when
332 called with standard input connected to a tty device, it prompts for
333 commands and executes them until an EOF is read; when called with a
334 file name argument or with a file as standard input, it reads and
335 executes a
336 .I script
337 from that file;
338 when called with
339 .B \-c
340 .IR command ,
341 it executes the Python statement(s) given as
342 .IR command .
343 Here
344 .I command
345 may contain multiple statements separated by newlines.
346 Leading whitespace is significant in Python statements!
347 In non-interactive mode, the entire input is parsed before it is
348 executed.
349 .PP
350 If available, the script name and additional arguments thereafter are
351 passed to the script in the Python variable
352 .IR sys.argv ,
353 which is a list of strings (you must first
354 .I import sys
355 to be able to access it).
356 If no script name is given,
357 .I sys.argv[0]
358 is an empty string; if
359 .B \-c
360 is used,
361 .I sys.argv[0]
362 contains the string
363 .I '-c'.
364 Note that options interpreted by the Python interpreter itself
365 are not placed in
366 .IR sys.argv .
367 .PP
368 In interactive mode, the primary prompt is `>>>'; the second prompt
369 (which appears when a command is not complete) is `...'.
370 The prompts can be changed by assignment to
371 .I sys.ps1
372 or
373 .IR sys.ps2 .
374 The interpreter quits when it reads an EOF at a prompt.
375 When an unhandled exception occurs, a stack trace is printed and
376 control returns to the primary prompt; in non-interactive mode, the
377 interpreter exits after printing the stack trace.
378 The interrupt signal raises the
379 .I Keyboard\%Interrupt
380 exception; other UNIX signals are not caught (except that SIGPIPE is
381 sometimes ignored, in favor of the
382 .I IOError
383 exception). Error messages are written to stderr.
384 .SH FILES AND DIRECTORIES
385 These are subject to difference depending on local installation
386 conventions; ${prefix} and ${exec_prefix} are installation-dependent
387 and should be interpreted as for GNU software; they may be the same.
388 The default for both is \fI/usr/local\fP.
389 .IP \fI${exec_prefix}/bin/python\fP
390 Recommended location of the interpreter.
391 .PP
392 .I ${prefix}/lib/python<version>
393 .br
394 .I ${exec_prefix}/lib/python<version>
395 .RS
396 Recommended locations of the directories containing the standard
397 modules.
398 .RE
399 .PP
400 .I ${prefix}/include/python<version>
401 .br
402 .I ${exec_prefix}/include/python<version>
403 .RS
404 Recommended locations of the directories containing the include files
405 needed for developing Python extensions and embedding the
406 interpreter.
407 .RE
408 .SH ENVIRONMENT VARIABLES
409 .IP PYTHONHOME
410 Change the location of the standard Python libraries. By default, the
411 libraries are searched in ${prefix}/lib/python<version> and
412 ${exec_prefix}/lib/python<version>, where ${prefix} and ${exec_prefix}
413 are installation-dependent directories, both defaulting to
414 \fI/usr/local\fP. When $PYTHONHOME is set to a single directory, its value
415 replaces both ${prefix} and ${exec_prefix}. To specify different values
416 for these, set $PYTHONHOME to ${prefix}:${exec_prefix}.
417 .IP PYTHONPATH
418 Augments the default search path for module files.
419 The format is the same as the shell's $PATH: one or more directory
420 pathnames separated by colons.
421 Non-existent directories are silently ignored.
422 The default search path is installation dependent, but generally
423 begins with ${prefix}/lib/python<version> (see PYTHONHOME above).
424 The default search path is always appended to $PYTHONPATH.
425 If a script argument is given, the directory containing the script is
426 inserted in the path in front of $PYTHONPATH.
427 The search path can be manipulated from within a Python program as the
428 variable
429 .IR sys.path .
430 .IP PYTHONPLATLIBDIR
431 Override sys.platlibdir.
432 .IP PYTHONSTARTUP
433 If this is the name of a readable file, the Python commands in that
434 file are executed before the first prompt is displayed in interactive
435 mode.
436 The file is executed in the same name space where interactive commands
437 are executed so that objects defined or imported in it can be used
438 without qualification in the interactive session.
439 You can also change the prompts
440 .I sys.ps1
441 and
442 .I sys.ps2
443 in this file.
444 .IP PYTHONOPTIMIZE
445 If this is set to a non-empty string it is equivalent to specifying
446 the \fB\-O\fP option. If set to an integer, it is equivalent to
447 specifying \fB\-O\fP multiple times.
448 .IP PYTHONDEBUG
449 If this is set to a non-empty string it is equivalent to specifying
450 the \fB\-d\fP option. If set to an integer, it is equivalent to
451 specifying \fB\-d\fP multiple times.
452 .IP PYTHONDONTWRITEBYTECODE
453 If this is set to a non-empty string it is equivalent to specifying
454 the \fB\-B\fP option (don't try to write
455 .I .pyc
456 files).
457 .IP PYTHONINSPECT
458 If this is set to a non-empty string it is equivalent to specifying
459 the \fB\-i\fP option.
460 .IP PYTHONIOENCODING
461 If this is set before running the interpreter, it overrides the encoding used
462 for stdin/stdout/stderr, in the syntax
463 .IB encodingname ":" errorhandler
464 The
465 .IB errorhandler
466 part is optional and has the same meaning as in str.encode. For stderr, the
467 .IB errorhandler
468 part is ignored; the handler will always be \'backslashreplace\'.
469 .IP PYTHONNOUSERSITE
470 If this is set to a non-empty string it is equivalent to specifying the
471 \fB\-s\fP option (Don't add the user site directory to sys.path).
472 .IP PYTHONUNBUFFERED
473 If this is set to a non-empty string it is equivalent to specifying
474 the \fB\-u\fP option.
475 .IP PYTHONVERBOSE
476 If this is set to a non-empty string it is equivalent to specifying
477 the \fB\-v\fP option. If set to an integer, it is equivalent to
478 specifying \fB\-v\fP multiple times.
479 .IP PYTHONWARNINGS
480 If this is set to a comma-separated string it is equivalent to
481 specifying the \fB\-W\fP option for each separate value.
482 .IP PYTHONHASHSEED
483 If this variable is set to "random", a random value is used to seed the hashes
484 of str and bytes objects.
485
486 If PYTHONHASHSEED is set to an integer value, it is used as a fixed seed for
487 generating the hash() of the types covered by the hash randomization. Its
488 purpose is to allow repeatable hashing, such as for selftests for the
489 interpreter itself, or to allow a cluster of python processes to share hash
490 values.
491
492 The integer must be a decimal number in the range [0,4294967295]. Specifying
493 the value 0 will disable hash randomization.
494 .IP PYTHONINTMAXSTRDIGITS
495 Limit the maximum digit characters in an int value
496 when converting from a string and when converting an int back to a str.
497 A value of 0 disables the limit. Conversions to or from bases 2, 4, 8,
498 16, and 32 are never limited.
499 .IP PYTHONMALLOC
500 Set the Python memory allocators and/or install debug hooks. The available
501 memory allocators are
502 .IR malloc
503 and
504 .IR pymalloc .
505 The available debug hooks are
506 .IR debug ,
507 .IR malloc_debug ,
508 and
509 .IR pymalloc_debug .
510 .IP
511 When Python is compiled in debug mode, the default is
512 .IR pymalloc_debug
513 and the debug hooks are automatically used. Otherwise, the default is
514 .IR pymalloc .
515 .IP PYTHONMALLOCSTATS
516 If set to a non-empty string, Python will print statistics of the pymalloc
517 memory allocator every time a new pymalloc object arena is created, and on
518 shutdown.
519 .IP
520 This variable is ignored if the
521 .RB $ PYTHONMALLOC
522 environment variable is used to force the
523 .BR malloc (3)
524 allocator of the C library, or if Python is configured without pymalloc support.
525 .IP PYTHONASYNCIODEBUG
526 If this environment variable is set to a non-empty string, enable the debug
527 mode of the asyncio module.
528 .IP PYTHONTRACEMALLOC
529 If this environment variable is set to a non-empty string, start tracing
530 Python memory allocations using the tracemalloc module.
531 .IP
532 The value of the variable is the maximum number of frames stored in a
533 traceback of a trace. For example,
534 .IB PYTHONTRACEMALLOC=1
535 stores only the most recent frame.
536 .IP PYTHONFAULTHANDLER
537 If this environment variable is set to a non-empty string,
538 .IR faulthandler.enable()
539 is called at startup: install a handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS
540 and SIGILL signals to dump the Python traceback.
541 .IP
542 This is equivalent to the \fB-X faulthandler\fP option.
543 .IP PYTHONEXECUTABLE
544 If this environment variable is set,
545 .IB sys.argv[0]
546 will be set to its value instead of the value got through the C runtime. Only
547 works on Mac OS X.
548 .IP PYTHONUSERBASE
549 Defines the user base directory, which is used to compute the path of the user
550 .IR site-packages
551 directory and Distutils installation paths for
552 .IR "python setup\.py install \-\-user" .
553 .IP PYTHONPROFILEIMPORTTIME
554 If this environment variable is set to a non-empty string, Python will
555 show how long each import takes. This is exactly equivalent to setting
556 \fB\-X importtime\fP on the command line.
557 .IP PYTHONBREAKPOINT
558 If this environment variable is set to 0, it disables the default debugger. It
559 can be set to the callable of your debugger of choice.
560 .SS Debug-mode variables
561 Setting these variables only has an effect in a debug build of Python, that is,
562 if Python was configured with the
563 \fB\--with-pydebug\fP build option.
564 .IP PYTHONTHREADDEBUG
565 If this environment variable is set, Python will print threading debug info.
566 The feature is deprecated in Python 3.10 and will be removed in Python 3.12.
567 .IP PYTHONDUMPREFS
568 If this environment variable is set, Python will dump objects and reference
569 counts still alive after shutting down the interpreter.
570 .SH AUTHOR
571 The Python Software Foundation: https://www.python.org/psf/
572 .SH INTERNET RESOURCES
573 Main website: https://www.python.org/
574 .br
575 Documentation: https://docs.python.org/
576 .br
577 Developer resources: https://devguide.python.org/
578 .br
579 Downloads: https://www.python.org/downloads/
580 .br
581 Module repository: https://pypi.org/
582 .br
583 Newsgroups: comp.lang.python, comp.lang.python.announce
584 .SH LICENSING
585 Python is distributed under an Open Source license. See the file
586 "LICENSE" in the Python source distribution for information on terms &
587 conditions for accessing and otherwise using Python and for a
588 DISCLAIMER OF ALL WARRANTIES.