Debian Codegraph @

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