Debian Codegraph @

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