Merge remote-tracking branch 'upstream/master' into doc-8264

This commit is contained in:
Fidget-Spinner 2021-01-01 23:08:09 +08:00
commit d7399d585b
650 changed files with 21084 additions and 11506 deletions

View File

@ -12,7 +12,7 @@ steps:
inputs:
versionSpec: '>=3.6'
- script: python -m pip install sphinx==2.2.0 blurb python-docs-theme
- script: python -m pip install sphinx==3.2.1 blurb python-docs-theme
displayName: 'Install build dependencies'
- ${{ if ne(parameters.latex, 'true') }}:

7
.github/CODEOWNERS vendored
View File

@ -19,6 +19,7 @@ Objects/frameobject.c @markshannon
Objects/call.c @markshannon
Python/ceval.c @markshannon
Python/compile.c @markshannon
Python/ast_opt.c @isidentical
# Hashing
**/*hashlib* @python/crypto-team @tiran
@ -84,6 +85,12 @@ Include/pytime.h @pganssle @abalkin
/Lib/test/test_peg_generator/ @pablogsal @lysnikolaou
/Grammar/python.gram @pablogsal @lysnikolaou
# AST
Python/ast.c @isidentical
Parser/asdl.py @isidentical
Parser/asdl_c.py @isidentical
Lib/ast.py @isidentical
# SQLite 3
**/*sqlite* @berkerpeksag

View File

@ -7,3 +7,7 @@ updates:
labels:
- "skip issue"
- "skip news"
target_branch:
- "master"
- "3.9"
- "3.8"

19
.github/problem-matchers/msvc.json vendored Normal file
View File

@ -0,0 +1,19 @@
{
"__comment": "Taken from vscode's vs/workbench/contrib/tasks/common/problemMatcher.ts msCompile rule",
"problemMatcher": [
{
"owner": "msvc-problem-matcher",
"pattern": [
{
"regexp": "^(?:\\s+\\d+\\>)?([^\\s].*)\\((\\d+),?(\\d+)?(?:,\\d+,\\d+)?\\)\\s*:\\s+(error|warning|info)\\s+(\\w{1,2}\\d+)\\s*:\\s*(.*)$",
"file": 1,
"line": 2,
"column": 3,
"severity": 4,
"code": 5,
"message": 6
}
]
}
]
}

View File

@ -28,7 +28,7 @@ jobs:
- name: Check for source changes
id: check
run: |
if [ -z "GITHUB_BASE_REF" ]; then
if [ -z "$GITHUB_BASE_REF" ]; then
echo '::set-output name=run_tests::true'
else
git fetch origin $GITHUB_BASE_REF --depth=1
@ -75,6 +75,8 @@ jobs:
fi
- name: Check exported libpython symbols
run: make smelly
- name: Check limited ABI symbols
run: make check-limited-abi
build_win32:
name: 'Windows (x86)'
@ -97,6 +99,8 @@ jobs:
if: needs.check_source.outputs.run_tests == 'true'
steps:
- uses: actions/checkout@v2
- name: Register MSVC problem matcher
run: echo "::add-matcher::.github/problem-matchers/msvc.json"
- name: Build CPython
run: .\PCbuild\build.bat -e -p x64
- name: Display build info
@ -135,7 +139,7 @@ jobs:
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v2.1.2
uses: actions/cache@v2.1.3
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

View File

@ -32,7 +32,7 @@ jobs:
run: sudo ./.github/workflows/posix-deps-apt.sh
- name: 'Restore OpenSSL build'
id: cache-openssl
uses: actions/cache@v2.1.2
uses: actions/cache@v2.1.3
with:
path: ./multissl/openssl/${{ env.OPENSSL_VER }}
key: ${{ runner.os }}-multissl-openssl-${{ env.OPENSSL_VER }}

View File

@ -38,7 +38,7 @@ jobs:
- name: 'Build documentation'
run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W --keep-going -j4" doctest html
- name: 'Upload'
uses: actions/upload-artifact@v2.2.0
uses: actions/upload-artifact@v2.2.1
with:
name: doc-html
path: Doc/build/html

19
.github/workflows/stale.yml vendored Normal file
View File

@ -0,0 +1,19 @@
name: Mark stale pull requests
on:
schedule:
- cron: "0 0 * * *"
jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v3
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity.'
stale-pr-label: 'stale'
days-before-stale: 30
days-before-close: -1

View File

@ -192,6 +192,8 @@ script:
- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then ./python Tools/scripts/patchcheck.py --travis $TRAVIS_PULL_REQUEST; fi
# Check that all symbols exported by libpython start with "Py" or "_Py"
- make smelly
# Check that all symbols in the limited abi are present
- make check-limited-abi
# `-r -w` implicitly provided through `make buildbottest`.
- |
if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then

View File

@ -202,6 +202,7 @@ dist:
check:
$(PYTHON) tools/rstlint.py -i tools -i $(VENVDIR) -i README.rst
$(PYTHON) tools/rstlint.py ../Misc/NEWS.d/next/
serve:
$(PYTHON) ../Tools/scripts/serve.py build/html

View File

@ -57,7 +57,7 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception.
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

View File

@ -15,8 +15,7 @@ sys.path.append(os.path.abspath('includes'))
extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
'pyspecific', 'c_annotations', 'escape4chm',
'asdl_highlight', 'peg_highlight']
'asdl_highlight', 'peg_highlight', 'glossary_search']
doctest_global_setup = '''
try:

780
Doc/data/stable_abi.dat Normal file
View File

@ -0,0 +1,780 @@
# File generated by 'make regen-limited-abi'
# This is NOT an authoritative list of stable ABI symbols
PyArg_Parse
PyArg_ParseTuple
PyArg_ParseTupleAndKeywords
PyArg_UnpackTuple
PyArg_VaParse
PyArg_VaParseTupleAndKeywords
PyArg_ValidateKeywordArguments
PyBaseObject_Type
PyBool_FromLong
PyBool_Type
PyByteArrayIter_Type
PyByteArray_AsString
PyByteArray_Concat
PyByteArray_FromObject
PyByteArray_FromStringAndSize
PyByteArray_Resize
PyByteArray_Size
PyByteArray_Type
PyBytesIter_Type
PyBytes_AsString
PyBytes_AsStringAndSize
PyBytes_Concat
PyBytes_ConcatAndDel
PyBytes_DecodeEscape
PyBytes_FromFormat
PyBytes_FromFormatV
PyBytes_FromObject
PyBytes_FromString
PyBytes_FromStringAndSize
PyBytes_Repr
PyBytes_Size
PyBytes_Type
PyCFunction_Call
PyCFunction_GetFlags
PyCFunction_GetFunction
PyCFunction_GetSelf
PyCFunction_NewEx
PyCFunction_Type
PyCMethod_New
PyCallIter_New
PyCallIter_Type
PyCallable_Check
PyCapsule_GetContext
PyCapsule_GetDestructor
PyCapsule_GetName
PyCapsule_GetPointer
PyCapsule_Import
PyCapsule_IsValid
PyCapsule_New
PyCapsule_SetContext
PyCapsule_SetDestructor
PyCapsule_SetName
PyCapsule_SetPointer
PyCapsule_Type
PyClassMethodDescr_Type
PyCodec_BackslashReplaceErrors
PyCodec_Decode
PyCodec_Decoder
PyCodec_Encode
PyCodec_Encoder
PyCodec_IgnoreErrors
PyCodec_IncrementalDecoder
PyCodec_IncrementalEncoder
PyCodec_KnownEncoding
PyCodec_LookupError
PyCodec_NameReplaceErrors
PyCodec_Register
PyCodec_RegisterError
PyCodec_ReplaceErrors
PyCodec_StreamReader
PyCodec_StreamWriter
PyCodec_StrictErrors
PyCodec_Unregister
PyCodec_XMLCharRefReplaceErrors
PyComplex_FromDoubles
PyComplex_ImagAsDouble
PyComplex_RealAsDouble
PyComplex_Type
PyDescr_NewClassMethod
PyDescr_NewGetSet
PyDescr_NewMember
PyDescr_NewMethod
PyDictItems_Type
PyDictIterItem_Type
PyDictIterKey_Type
PyDictIterValue_Type
PyDictKeys_Type
PyDictProxy_New
PyDictProxy_Type
PyDictRevIterItem_Type
PyDictRevIterKey_Type
PyDictRevIterValue_Type
PyDictValues_Type
PyDict_Clear
PyDict_Contains
PyDict_Copy
PyDict_DelItem
PyDict_DelItemString
PyDict_GetItem
PyDict_GetItemString
PyDict_GetItemWithError
PyDict_Items
PyDict_Keys
PyDict_Merge
PyDict_MergeFromSeq2
PyDict_New
PyDict_Next
PyDict_SetItem
PyDict_SetItemString
PyDict_Size
PyDict_Type
PyDict_Update
PyDict_Values
PyEllipsis_Type
PyEnum_Type
PyErr_BadArgument
PyErr_BadInternalCall
PyErr_CheckSignals
PyErr_Clear
PyErr_Display
PyErr_ExceptionMatches
PyErr_Fetch
PyErr_Format
PyErr_FormatV
PyErr_GetExcInfo
PyErr_GivenExceptionMatches
PyErr_NewException
PyErr_NewExceptionWithDoc
PyErr_NoMemory
PyErr_NormalizeException
PyErr_Occurred
PyErr_Print
PyErr_PrintEx
PyErr_ProgramText
PyErr_ResourceWarning
PyErr_Restore
PyErr_SetExcInfo
PyErr_SetFromErrno
PyErr_SetFromErrnoWithFilename
PyErr_SetFromErrnoWithFilenameObject
PyErr_SetFromErrnoWithFilenameObjects
PyErr_SetImportError
PyErr_SetImportErrorSubclass
PyErr_SetInterrupt
PyErr_SetNone
PyErr_SetObject
PyErr_SetString
PyErr_SyntaxLocation
PyErr_SyntaxLocationEx
PyErr_WarnEx
PyErr_WarnExplicit
PyErr_WarnFormat
PyErr_WriteUnraisable
PyEval_AcquireLock
PyEval_AcquireThread
PyEval_CallFunction
PyEval_CallMethod
PyEval_CallObjectWithKeywords
PyEval_EvalCode
PyEval_EvalCodeEx
PyEval_EvalFrame
PyEval_EvalFrameEx
PyEval_GetBuiltins
PyEval_GetFrame
PyEval_GetFuncDesc
PyEval_GetFuncName
PyEval_GetGlobals
PyEval_GetLocals
PyEval_InitThreads
PyEval_ReleaseLock
PyEval_ReleaseThread
PyEval_RestoreThread
PyEval_SaveThread
PyEval_ThreadsInitialized
PyExc_ArithmeticError
PyExc_AssertionError
PyExc_AttributeError
PyExc_BaseException
PyExc_BlockingIOError
PyExc_BrokenPipeError
PyExc_BufferError
PyExc_BytesWarning
PyExc_ChildProcessError
PyExc_ConnectionAbortedError
PyExc_ConnectionError
PyExc_ConnectionRefusedError
PyExc_ConnectionResetError
PyExc_DeprecationWarning
PyExc_EOFError
PyExc_EnvironmentError
PyExc_Exception
PyExc_FileExistsError
PyExc_FileNotFoundError
PyExc_FloatingPointError
PyExc_FutureWarning
PyExc_GeneratorExit
PyExc_IOError
PyExc_ImportError
PyExc_ImportWarning
PyExc_IndentationError
PyExc_IndexError
PyExc_InterruptedError
PyExc_IsADirectoryError
PyExc_KeyError
PyExc_KeyboardInterrupt
PyExc_LookupError
PyExc_MemoryError
PyExc_ModuleNotFoundError
PyExc_NameError
PyExc_NotADirectoryError
PyExc_NotImplementedError
PyExc_OSError
PyExc_OverflowError
PyExc_PendingDeprecationWarning
PyExc_PermissionError
PyExc_ProcessLookupError
PyExc_RecursionError
PyExc_ReferenceError
PyExc_ResourceWarning
PyExc_RuntimeError
PyExc_RuntimeWarning
PyExc_StopAsyncIteration
PyExc_StopIteration
PyExc_SyntaxError
PyExc_SyntaxWarning
PyExc_SystemError
PyExc_SystemExit
PyExc_TabError
PyExc_TimeoutError
PyExc_TypeError
PyExc_UnboundLocalError
PyExc_UnicodeDecodeError
PyExc_UnicodeEncodeError
PyExc_UnicodeError
PyExc_UnicodeTranslateError
PyExc_UnicodeWarning
PyExc_UserWarning
PyExc_ValueError
PyExc_Warning
PyExc_ZeroDivisionError
PyExceptionClass_Name
PyException_GetCause
PyException_GetContext
PyException_GetTraceback
PyException_SetCause
PyException_SetContext
PyException_SetTraceback
PyFile_FromFd
PyFile_GetLine
PyFile_WriteObject
PyFile_WriteString
PyFilter_Type
PyFloat_AsDouble
PyFloat_FromDouble
PyFloat_FromString
PyFloat_GetInfo
PyFloat_GetMax
PyFloat_GetMin
PyFloat_Type
PyFrame_GetCode
PyFrame_GetLineNumber
PyFrozenSet_New
PyFrozenSet_Type
PyGC_Collect
PyGILState_Ensure
PyGILState_GetThisThreadState
PyGILState_Release
PyGetSetDescr_Type
PyImport_AddModule
PyImport_AddModuleObject
PyImport_AppendInittab
PyImport_ExecCodeModule
PyImport_ExecCodeModuleEx
PyImport_ExecCodeModuleObject
PyImport_ExecCodeModuleWithPathnames
PyImport_GetImporter
PyImport_GetMagicNumber
PyImport_GetMagicTag
PyImport_GetModule
PyImport_GetModuleDict
PyImport_Import
PyImport_ImportFrozenModule
PyImport_ImportFrozenModuleObject
PyImport_ImportModule
PyImport_ImportModuleLevel
PyImport_ImportModuleLevelObject
PyImport_ImportModuleNoBlock
PyImport_ReloadModule
PyIndex_Check
PyInterpreterState_Clear
PyInterpreterState_Delete
PyInterpreterState_Get
PyInterpreterState_GetDict
PyInterpreterState_GetID
PyInterpreterState_New
PyIter_Check
PyIter_Next
PyIter_Send
PyListIter_Type
PyListRevIter_Type
PyList_Append
PyList_AsTuple
PyList_GetItem
PyList_GetSlice
PyList_Insert
PyList_New
PyList_Reverse
PyList_SetItem
PyList_SetSlice
PyList_Size
PyList_Sort
PyList_Type
PyLongRangeIter_Type
PyLong_AsDouble
PyLong_AsLong
PyLong_AsLongAndOverflow
PyLong_AsLongLong
PyLong_AsLongLongAndOverflow
PyLong_AsSize_t
PyLong_AsSsize_t
PyLong_AsUnsignedLong
PyLong_AsUnsignedLongLong
PyLong_AsUnsignedLongLongMask
PyLong_AsUnsignedLongMask
PyLong_AsVoidPtr
PyLong_FromDouble
PyLong_FromLong
PyLong_FromLongLong
PyLong_FromSize_t
PyLong_FromSsize_t
PyLong_FromString
PyLong_FromUnsignedLong
PyLong_FromUnsignedLongLong
PyLong_FromVoidPtr
PyLong_GetInfo
PyLong_Type
PyMap_Type
PyMapping_Check
PyMapping_GetItemString
PyMapping_HasKey
PyMapping_HasKeyString
PyMapping_Items
PyMapping_Keys
PyMapping_Length
PyMapping_SetItemString
PyMapping_Size
PyMapping_Values
PyMarshal_ReadObjectFromString
PyMarshal_WriteLongToFile
PyMarshal_WriteObjectToFile
PyMarshal_WriteObjectToString
PyMem_Free
PyMem_Malloc
PyMem_Realloc
PyMemberDescr_Type
PyMember_GetOne
PyMember_SetOne
PyMemoryView_FromMemory
PyMemoryView_FromObject
PyMemoryView_GetContiguous
PyMemoryView_Type
PyMethodDescr_Type
PyModuleDef_Init
PyModuleDef_Type
PyModule_AddFunctions
PyModule_AddIntConstant
PyModule_AddObject
PyModule_AddObjectRef
PyModule_AddStringConstant
PyModule_AddType
PyModule_Create2
PyModule_ExecDef
PyModule_FromDefAndSpec2
PyModule_GetDef
PyModule_GetDict
PyModule_GetFilename
PyModule_GetFilenameObject
PyModule_GetName
PyModule_GetNameObject
PyModule_GetState
PyModule_New
PyModule_NewObject
PyModule_SetDocString
PyModule_Type
PyNumber_Absolute
PyNumber_Add
PyNumber_And
PyNumber_AsSsize_t
PyNumber_Check
PyNumber_Divmod
PyNumber_Float
PyNumber_FloorDivide
PyNumber_InPlaceAdd
PyNumber_InPlaceAnd
PyNumber_InPlaceFloorDivide
PyNumber_InPlaceLshift
PyNumber_InPlaceMatrixMultiply
PyNumber_InPlaceMultiply
PyNumber_InPlaceOr
PyNumber_InPlacePower
PyNumber_InPlaceRemainder
PyNumber_InPlaceRshift
PyNumber_InPlaceSubtract
PyNumber_InPlaceTrueDivide
PyNumber_InPlaceXor
PyNumber_Index
PyNumber_Invert
PyNumber_Long
PyNumber_Lshift
PyNumber_MatrixMultiply
PyNumber_Multiply
PyNumber_Negative
PyNumber_Or
PyNumber_Positive
PyNumber_Power
PyNumber_Remainder
PyNumber_Rshift
PyNumber_Subtract
PyNumber_ToBase
PyNumber_TrueDivide
PyNumber_Xor
PyOS_AfterFork
PyOS_AfterFork_Child
PyOS_AfterFork_Parent
PyOS_BeforeFork
PyOS_FSPath
PyOS_InterruptOccurred
PyOS_double_to_string
PyOS_getsig
PyOS_mystricmp
PyOS_mystrnicmp
PyOS_setsig
PyOS_snprintf
PyOS_string_to_double
PyOS_strtol
PyOS_strtoul
PyOS_vsnprintf
PyObject_ASCII
PyObject_AsFileDescriptor
PyObject_Bytes
PyObject_Call
PyObject_CallFunction
PyObject_CallFunctionObjArgs
PyObject_CallMethod
PyObject_CallMethodObjArgs
PyObject_CallNoArgs
PyObject_CallObject
PyObject_Calloc
PyObject_ClearWeakRefs
PyObject_DelItem
PyObject_DelItemString
PyObject_Dir
PyObject_Format
PyObject_Free
PyObject_GC_Del
PyObject_GC_IsFinalized
PyObject_GC_IsTracked
PyObject_GC_Track
PyObject_GC_UnTrack
PyObject_GenericGetAttr
PyObject_GenericGetDict
PyObject_GenericSetAttr
PyObject_GenericSetDict
PyObject_GetAttr
PyObject_GetAttrString
PyObject_GetItem
PyObject_GetIter
PyObject_HasAttr
PyObject_HasAttrString
PyObject_Hash
PyObject_HashNotImplemented
PyObject_Init
PyObject_InitVar
PyObject_IsInstance
PyObject_IsSubclass
PyObject_IsTrue
PyObject_Length
PyObject_Malloc
PyObject_Not
PyObject_Realloc
PyObject_Repr
PyObject_RichCompare
PyObject_RichCompareBool
PyObject_SelfIter
PyObject_SetAttr
PyObject_SetAttrString
PyObject_SetItem
PyObject_Size
PyObject_Str
PyObject_Type
PyProperty_Type
PyRangeIter_Type
PyRange_Type
PyReversed_Type
PySeqIter_New
PySeqIter_Type
PySequence_Check
PySequence_Concat
PySequence_Contains
PySequence_Count
PySequence_DelItem
PySequence_DelSlice
PySequence_Fast
PySequence_GetItem
PySequence_GetSlice
PySequence_In
PySequence_InPlaceConcat
PySequence_InPlaceRepeat
PySequence_Index
PySequence_Length
PySequence_List
PySequence_Repeat
PySequence_SetItem
PySequence_SetSlice
PySequence_Size
PySequence_Tuple
PySetIter_Type
PySet_Add
PySet_Clear
PySet_Contains
PySet_Discard
PySet_New
PySet_Pop
PySet_Size
PySet_Type
PySlice_AdjustIndices
PySlice_GetIndices
PySlice_GetIndicesEx
PySlice_New
PySlice_Type
PySlice_Unpack
PyState_AddModule
PyState_FindModule
PyState_RemoveModule
PyStructSequence_GetItem
PyStructSequence_New
PyStructSequence_NewType
PyStructSequence_SetItem
PySuper_Type
PySys_AddWarnOption
PySys_AddWarnOptionUnicode
PySys_AddXOption
PySys_FormatStderr
PySys_FormatStdout
PySys_GetObject
PySys_GetXOptions
PySys_HasWarnOptions
PySys_ResetWarnOptions
PySys_SetArgv
PySys_SetArgvEx
PySys_SetObject
PySys_SetPath
PySys_WriteStderr
PySys_WriteStdout
PyThreadState_Clear
PyThreadState_Delete
PyThreadState_Get
PyThreadState_GetDict
PyThreadState_GetFrame
PyThreadState_GetID
PyThreadState_GetInterpreter
PyThreadState_New
PyThreadState_SetAsyncExc
PyThreadState_Swap
PyThread_GetInfo
PyThread_ReInitTLS
PyThread_acquire_lock
PyThread_acquire_lock_timed
PyThread_allocate_lock
PyThread_create_key
PyThread_delete_key
PyThread_delete_key_value
PyThread_exit_thread
PyThread_free_lock
PyThread_get_key_value
PyThread_get_stacksize
PyThread_get_thread_ident
PyThread_get_thread_native_id
PyThread_init_thread
PyThread_release_lock
PyThread_set_key_value
PyThread_set_stacksize
PyThread_start_new_thread
PyThread_tss_alloc
PyThread_tss_create
PyThread_tss_delete
PyThread_tss_free
PyThread_tss_get
PyThread_tss_is_created
PyThread_tss_set
PyTraceBack_Here
PyTraceBack_Print
PyTraceBack_Type
PyTupleIter_Type
PyTuple_GetItem
PyTuple_GetSlice
PyTuple_New
PyTuple_Pack
PyTuple_SetItem
PyTuple_Size
PyTuple_Type
PyType_ClearCache
PyType_FromModuleAndSpec
PyType_FromSpec
PyType_FromSpecWithBases
PyType_GenericAlloc
PyType_GenericNew
PyType_GetFlags
PyType_GetModule
PyType_GetModuleState
PyType_GetSlot
PyType_IsSubtype
PyType_Modified
PyType_Ready
PyType_Type
PyUnicodeDecodeError_Create
PyUnicodeDecodeError_GetEncoding
PyUnicodeDecodeError_GetEnd
PyUnicodeDecodeError_GetObject
PyUnicodeDecodeError_GetReason
PyUnicodeDecodeError_GetStart
PyUnicodeDecodeError_SetEnd
PyUnicodeDecodeError_SetReason
PyUnicodeDecodeError_SetStart
PyUnicodeEncodeError_GetEncoding
PyUnicodeEncodeError_GetEnd
PyUnicodeEncodeError_GetObject
PyUnicodeEncodeError_GetReason
PyUnicodeEncodeError_GetStart
PyUnicodeEncodeError_SetEnd
PyUnicodeEncodeError_SetReason
PyUnicodeEncodeError_SetStart
PyUnicodeIter_Type
PyUnicodeTranslateError_GetEnd
PyUnicodeTranslateError_GetObject
PyUnicodeTranslateError_GetReason
PyUnicodeTranslateError_GetStart
PyUnicodeTranslateError_SetEnd
PyUnicodeTranslateError_SetReason
PyUnicodeTranslateError_SetStart
PyUnicode_Append
PyUnicode_AppendAndDel
PyUnicode_AsASCIIString
PyUnicode_AsCharmapString
PyUnicode_AsDecodedObject
PyUnicode_AsDecodedUnicode
PyUnicode_AsEncodedObject
PyUnicode_AsEncodedString
PyUnicode_AsEncodedUnicode
PyUnicode_AsLatin1String
PyUnicode_AsRawUnicodeEscapeString
PyUnicode_AsUCS4
PyUnicode_AsUCS4Copy
PyUnicode_AsUTF16String
PyUnicode_AsUTF32String
PyUnicode_AsUTF8AndSize
PyUnicode_AsUTF8String
PyUnicode_AsUnicodeEscapeString
PyUnicode_AsWideChar
PyUnicode_AsWideCharString
PyUnicode_BuildEncodingMap
PyUnicode_Compare
PyUnicode_CompareWithASCIIString
PyUnicode_Concat
PyUnicode_Contains
PyUnicode_Count
PyUnicode_Decode
PyUnicode_DecodeASCII
PyUnicode_DecodeCharmap
PyUnicode_DecodeFSDefault
PyUnicode_DecodeFSDefaultAndSize
PyUnicode_DecodeLatin1
PyUnicode_DecodeLocale
PyUnicode_DecodeLocaleAndSize
PyUnicode_DecodeRawUnicodeEscape
PyUnicode_DecodeUTF16
PyUnicode_DecodeUTF16Stateful
PyUnicode_DecodeUTF32
PyUnicode_DecodeUTF32Stateful
PyUnicode_DecodeUTF7
PyUnicode_DecodeUTF7Stateful
PyUnicode_DecodeUTF8
PyUnicode_DecodeUTF8Stateful
PyUnicode_DecodeUnicodeEscape
PyUnicode_EncodeFSDefault
PyUnicode_EncodeLocale
PyUnicode_FSConverter
PyUnicode_FSDecoder
PyUnicode_Find
PyUnicode_FindChar
PyUnicode_Format
PyUnicode_FromEncodedObject
PyUnicode_FromFormat
PyUnicode_FromFormatV
PyUnicode_FromObject
PyUnicode_FromOrdinal
PyUnicode_FromString
PyUnicode_FromStringAndSize
PyUnicode_FromWideChar
PyUnicode_GetDefaultEncoding
PyUnicode_GetLength
PyUnicode_GetSize
PyUnicode_InternFromString
PyUnicode_InternImmortal
PyUnicode_InternInPlace
PyUnicode_IsIdentifier
PyUnicode_Join
PyUnicode_Partition
PyUnicode_RPartition
PyUnicode_RSplit
PyUnicode_ReadChar
PyUnicode_Replace
PyUnicode_Resize
PyUnicode_RichCompare
PyUnicode_Split
PyUnicode_Splitlines
PyUnicode_Substring
PyUnicode_Tailmatch
PyUnicode_Translate
PyUnicode_Type
PyUnicode_WriteChar
PyWeakref_GetObject
PyWeakref_NewProxy
PyWeakref_NewRef
PyWrapperDescr_Type
PyWrapper_New
PyZip_Type
Py_AddPendingCall
Py_AtExit
Py_BuildValue
Py_BytesMain
Py_CompileString
Py_DecRef
Py_DecodeLocale
Py_EncodeLocale
Py_EndInterpreter
Py_EnterRecursiveCall
Py_Exit
Py_FatalError
Py_FileSystemDefaultEncodeErrors
Py_FileSystemDefaultEncoding
Py_Finalize
Py_FinalizeEx
Py_FrozenMain
Py_GenericAlias
Py_GenericAliasType
Py_GetBuildInfo
Py_GetCompiler
Py_GetCopyright
Py_GetExecPrefix
Py_GetPath
Py_GetPlatform
Py_GetPrefix
Py_GetProgramFullPath
Py_GetProgramName
Py_GetPythonHome
Py_GetRecursionLimit
Py_GetVersion
Py_HasFileSystemDefaultEncoding
Py_IncRef
Py_Initialize
Py_InitializeEx
Py_IsInitialized
Py_LeaveRecursiveCall
Py_Main
Py_MakePendingCalls
Py_NewInterpreter
Py_NewRef
Py_ReprEnter
Py_ReprLeave
Py_SetPath
Py_SetProgramName
Py_SetPythonHome
Py_SetRecursionLimit
Py_SymtableString
Py_UTF8Mode
Py_VaBuildValue
Py_XNewRef

View File

@ -83,7 +83,7 @@ Following is a result of running the code:
$ python3 prog.py --help
usage: prog.py [-h]
optional arguments:
options:
-h, --help show this help message and exit
$ python3 prog.py --verbose
usage: prog.py [-h]
@ -130,7 +130,7 @@ And running the code:
positional arguments:
echo
optional arguments:
options:
-h, --help show this help message and exit
$ python3 prog.py foo
foo
@ -172,7 +172,7 @@ And we get:
positional arguments:
echo echo the string you use here
optional arguments:
options:
-h, --help show this help message and exit
Now, how about doing something even more useful::
@ -241,7 +241,7 @@ And the output:
$ python3 prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]
optional arguments:
options:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
@ -289,7 +289,7 @@ And the output:
$ python3 prog.py --help
usage: prog.py [-h] [--verbose]
optional arguments:
options:
-h, --help show this help message and exit
--verbose increase output verbosity
@ -332,7 +332,7 @@ And here goes:
$ python3 prog.py --help
usage: prog.py [-h] [-v]
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbose increase output verbosity
@ -440,7 +440,7 @@ And the output:
positional arguments:
square display a square of a given number
optional arguments:
options:
-h, --help show this help message and exit
-v {0,1,2}, --verbosity {0,1,2}
increase output verbosity
@ -468,7 +468,8 @@ verbosity argument (check the output of ``python --help``)::
print(answer)
We have introduced another action, "count",
to count the number of occurrences of a specific optional arguments:
to count the number of occurrences of specific options.
.. code-block:: shell-session
@ -489,7 +490,7 @@ to count the number of occurrences of a specific optional arguments:
positional arguments:
square display a square of a given number
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python3 prog.py 4 -vvv
@ -626,7 +627,7 @@ Output:
x the base
y the exponent
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbosity
$ python3 prog.py 4 2 -v
@ -750,7 +751,7 @@ but not both at the same time:
x the base
y the exponent
optional arguments:
options:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet

View File

@ -934,32 +934,42 @@ here is a pure Python equivalent:
if doc is None and fget is not None:
doc = fget.__doc__
self.__doc__ = doc
self._name = ''
def __set_name__(self, owner, name):
self._name = name
def __get__(self, obj, objtype=None):
if obj is None:
return self
if self.fget is None:
raise AttributeError("unreadable attribute")
raise AttributeError(f'unreadable attribute {self._name}')
return self.fget(obj)
def __set__(self, obj, value):
if self.fset is None:
raise AttributeError("can't set attribute")
raise AttributeError(f"can't set attribute {self._name}")
self.fset(obj, value)
def __delete__(self, obj):
if self.fdel is None:
raise AttributeError("can't delete attribute")
raise AttributeError(f"can't delete attribute {self._name}")
self.fdel(obj)
def getter(self, fget):
return type(self)(fget, self.fset, self.fdel, self.__doc__)
prop = type(self)(fget, self.fset, self.fdel, self.__doc__)
prop._name = self._name
return prop
def setter(self, fset):
return type(self)(self.fget, fset, self.fdel, self.__doc__)
prop = type(self)(self.fget, fset, self.fdel, self.__doc__)
prop._name = self._name
return prop
def deleter(self, fdel):
return type(self)(self.fget, self.fset, fdel, self.__doc__)
prop = type(self)(self.fget, self.fset, fdel, self.__doc__)
prop._name = self._name
return prop
.. testcode::
:hide:

View File

@ -336,6 +336,7 @@ The :mod:`abc` module also provides the following functions:
.. versionadded:: 3.4
.. function:: update_abstractmethods(cls)
A function to recalculate an abstract class's abstraction status. This
function should be called if a class's abstract methods have been
implemented or changed after it was created. Usually, this function should
@ -343,7 +344,7 @@ The :mod:`abc` module also provides the following functions:
Returns *cls*, to allow usage as a class decorator.
If *cls* is not an instance of ABCMeta, does nothing.
If *cls* is not an instance of :class:`ABCMeta`, does nothing.
.. note::

View File

@ -57,7 +57,7 @@ be run at the command line and provides useful help messages:
positional arguments:
N an integer for the accumulator
optional arguments:
options:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
@ -217,14 +217,14 @@ The help for this program will display ``myprogram.py`` as the program name
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo help
@ -235,7 +235,7 @@ To change this default behavior, another value can be supplied using the
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
options:
-h, --help show this help message and exit
Note that the program name, whether determined from ``sys.argv[0]`` or from the
@ -249,7 +249,7 @@ specifier.
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
@ -269,7 +269,7 @@ arguments it contains::
positional arguments:
bar bar help
optional arguments:
options:
-h, --help show this help message and exit
--foo [FOO] foo help
@ -284,7 +284,7 @@ The default message can be overridden with the ``usage=`` keyword argument::
positional arguments:
bar bar help
optional arguments:
options:
-h, --help show this help message and exit
--foo [FOO] foo help
@ -307,7 +307,7 @@ various arguments::
A foo that bars
optional arguments:
options:
-h, --help show this help message and exit
By default, the description will be line-wrapped so that it fits within the
@ -329,7 +329,7 @@ argument to :class:`ArgumentParser`::
A foo that bars
optional arguments:
options:
-h, --help show this help message and exit
And that's how you'd foo a bar
@ -403,7 +403,7 @@ epilog_ texts in command-line help messages::
this description was indented weird but that is okay
optional arguments:
options:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
@ -432,7 +432,7 @@ should not be line-wrapped::
exactly the way
I want it
optional arguments:
options:
-h, --help show this help message and exit
:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
@ -454,7 +454,7 @@ default values to each of the argument help messages::
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
@ -473,7 +473,7 @@ as the regular formatter does)::
positional arguments:
float
optional arguments:
options:
-h, --help show this help message and exit
--foo int
@ -592,7 +592,7 @@ older arguments with the same option string. To get this behavior, the value
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
@ -623,7 +623,7 @@ help will be printed:
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO foo help
@ -636,7 +636,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
options:
--foo FOO foo help
The help option is typically ``-h/--help``. The exception to this is
@ -649,7 +649,7 @@ the help options::
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
options:
+h, ++help show this help message and exit
@ -696,7 +696,7 @@ The add_argument() method
* const_ - A constant value required by some action_ and nargs_ selections.
* default_ - The value produced if the argument is absent from the
command line.
command line and if it is absent from the namespace object.
* type_ - The type to which the command-line argument should be converted.
@ -1006,6 +1006,14 @@ was not present at the command line::
>>> parser.parse_args([])
Namespace(foo=42)
If the target namespace already has an attribute set, the action *default*
will not over write it::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
Namespace(foo=101)
If the ``default`` value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any type_
conversion argument, if provided, before setting the attribute on the
@ -1042,63 +1050,70 @@ command-line argument was not present::
type
^^^^
By default, :class:`ArgumentParser` objects read command-line arguments in as simple
By default, the parser reads command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, like a :class:`float` or :class:`int`. The
``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed. Common built-in
types and functions can be used directly as the value of the ``type`` argument::
interpreted as another type, such as a :class:`float` or :class:`int`. The
``type`` keyword for :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed.
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=open)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<_io.TextIOWrapper name='temp.txt' encoding='UTF-8'>, foo=2)
If the type_ keyword is used with the default_ keyword, the type converter
is only applied if the default is a string.
See the section on the default_ keyword argument for information on when the
``type`` argument is applied to default arguments.
The argument to ``type`` can be any callable that accepts a single string.
If the function raises :exc:`ArgumentTypeError`, :exc:`TypeError`, or
:exc:`ValueError`, the exception is caught and a nicely formatted error
message is displayed. No other exception types are handled.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the ``mode=``, ``bufsize=``, ``encoding=`` and
``errors=`` arguments of the :func:`open` function. For example,
``FileType('w')`` can be used to create a writable file::
Common built-in types and functions can be used as type converters:
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<_io.TextIOWrapper name='out.txt' encoding='UTF-8'>)
.. testcode::
``type=`` can take any callable that takes a single string argument and returns
the converted value::
import argparse
import pathlib
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
parser = argparse.ArgumentParser()
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('source_file', type=open)
parser.add_argument('dest_file', type=argparse.FileType('w', encoding='latin-1'))
parser.add_argument('datapath', type=pathlib.Path)
User defined functions can be used as well:
.. doctest::
>>> def hyphenated(string):
... return '-'.join([word[:4] for word in string.casefold().split()])
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
>>> parser = argparse.ArgumentParser()
>>> _ = parser.add_argument('short_title', type=hyphenated)
>>> parser.parse_args(['"The Tale of Two Cities"'])
Namespace(short_title='"the-tale-of-two-citi')
The choices_ keyword argument may be more convenient for type checkers that
simply check against a range of values::
The :func:`bool` function is not recommended as a type converter. All it does
is convert empty strings to ``False`` and non-empty strings to ``True``.
This is usually not what is desired.
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=range(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
In general, the ``type`` keyword is a convenience that should only be used for
simple conversions that can only raise one of the three supported exceptions.
Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.
See the choices_ section for more details.
For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the ``type`` keyword. An
:exc:`~json.JSONDecodeError` would not be well formatted and a
:exc:`FileNotFound` exception would not be handled at all.
Even :class:`~argparse.FileType` has its limitations for use with the ``type``
keyword. If one argument uses *FileType* and then a subsequent argument fails,
an error is reported but the file is not automatically closed. In this case, it
would be better to wait until after the parser has run and then use the
:keyword:`with`-statement to manage the files.
For type checkers that simply check against a fixed set of values, consider
using the choices_ keyword instead.
choices
@ -1133,20 +1148,14 @@ container should match the type_ specified::
Any container can be passed as the *choices* value, so :class:`list` objects,
:class:`set` objects, and custom containers are all supported.
This includes :class:`enum.Enum`, which could be used to restrain
argument's choices; if we reuse previous rock/paper/scissors game example,
this could be as follows::
>>> from enum import Enum
>>> class GameMove(Enum):
... ROCK = 'rock'
... PAPER = 'paper'
... SCISSORS = 'scissors'
...
>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', type=GameMove, choices=GameMove)
>>> parser.parse_args(['rock'])
Namespace(move=<GameMove.ROCK: 'rock'>)
Use of :class:`enum.Enum` is not recommended because it is difficult to
control its appearance in usage, help, and error messages.
Formatted choices overrides the default *metavar* which is normally derived
from *dest*. This is usually what you want because the user never sees the
*dest* parameter. If this display isn't desirable (perhaps because there are
many choices), just specify an explicit metavar_.
required
@ -1194,7 +1203,7 @@ argument::
positional arguments:
bar one of the bars to be frobbled
optional arguments:
options:
-h, --help show this help message and exit
--foo foo the bars before frobbling
@ -1212,7 +1221,7 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
options:
-h, --help show this help message and exit
As the help string supports %-formatting, if you want a literal ``%`` to appear
@ -1226,7 +1235,7 @@ setting the ``help`` value to ``argparse.SUPPRESS``::
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
options:
-h, --help show this help message and exit
@ -1253,7 +1262,7 @@ will be referred to as ``FOO``. An example::
positional arguments:
bar
optional arguments:
options:
-h, --help show this help message and exit
--foo FOO
@ -1270,7 +1279,7 @@ An alternative name can be specified with ``metavar``::
positional arguments:
XXX
optional arguments:
options:
-h, --help show this help message and exit
--foo YYY
@ -1288,7 +1297,7 @@ arguments::
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]
optional arguments:
options:
-h, --help show this help message and exit
-x X X
--foo bar baz
@ -1692,7 +1701,7 @@ Sub-commands
a a help
b b help
optional arguments:
options:
-h, --help show this help message and exit
--foo foo help
@ -1702,13 +1711,13 @@ Sub-commands
positional arguments:
bar bar help
optional arguments:
options:
-h, --help show this help message and exit
>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
optional arguments:
options:
-h, --help show this help message and exit
--baz {X,Y,Z} baz help
@ -1725,7 +1734,7 @@ Sub-commands
>>> parser.parse_args(['-h'])
usage: [-h] {foo,bar} ...
optional arguments:
options:
-h, --help show this help message and exit
subcommands:

View File

@ -1576,7 +1576,7 @@ and classes for traversing abstract syntax trees:
Safely evaluate an expression node or a string containing a Python literal or
container display. The string or node provided may only consist of the
following Python literal structures: strings, bytes, numbers, tuples, lists,
dicts, sets, booleans, and ``None``.
dicts, sets, booleans, ``None`` and ``Ellipsis``.
This can be used for safely evaluating strings containing Python values from
untrusted sources without the need to parse the values oneself. It is not
@ -1588,6 +1588,10 @@ and classes for traversing abstract syntax trees:
sufficiently large/complex string due to stack depth limitations
in Python's AST compiler.
It can raise :exc:`ValueError`, :exc:`TypeError`, :exc:`SyntaxError`,
:exc:`MemoryError` and :exc:`RecursionError` depending on the malformed
input.
.. versionchanged:: 3.2
Now allows bytes and set literals.

View File

@ -321,7 +321,7 @@ Creating Futures and Tasks
.. versionadded:: 3.5.2
.. method:: loop.create_task(coro, \*, name=None)
.. method:: loop.create_task(coro, *, name=None)
Schedule the execution of a :ref:`coroutine`.
Return a :class:`Task` object.
@ -356,7 +356,7 @@ Opening network connections
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_connection(protocol_factory, \
host=None, port=None, \*, ssl=None, \
host=None, port=None, *, ssl=None, \
family=0, proto=0, flags=0, sock=None, \
local_addr=None, server_hostname=None, \
ssl_handshake_timeout=None, \
@ -482,7 +482,7 @@ Opening network connections
that can be used directly in async/await code.
.. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \
local_addr=None, remote_addr=None, \*, \
local_addr=None, remote_addr=None, *, \
family=0, proto=0, flags=0, \
reuse_address=None, reuse_port=None, \
allow_broadcast=None, sock=None)
@ -559,7 +559,7 @@ Opening network connections
Added support for Windows.
.. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
path=None, \*, ssl=None, sock=None, \
path=None, *, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
Create a Unix connection.
@ -592,7 +592,7 @@ Creating network servers
^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_server(protocol_factory, \
host=None, port=None, \*, \
host=None, port=None, *, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, \
sock=None, backlog=100, ssl=None, \
@ -683,7 +683,7 @@ Creating network servers
.. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \
\*, sock=None, backlog=100, ssl=None, \
*, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, start_serving=True)
Similar to :meth:`loop.create_server` but works with the
@ -708,7 +708,7 @@ Creating network servers
The *path* parameter can now be a :class:`~pathlib.Path` object.
.. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \
sock, \*, ssl=None, ssl_handshake_timeout=None)
sock, *, ssl=None, ssl_handshake_timeout=None)
Wrap an already accepted connection into a transport/protocol pair.
@ -773,7 +773,7 @@ TLS Upgrade
^^^^^^^^^^^
.. coroutinemethod:: loop.start_tls(transport, protocol, \
sslcontext, \*, server_side=False, \
sslcontext, *, server_side=False, \
server_hostname=None, ssl_handshake_timeout=None)
Upgrade an existing transport-based connection to TLS.
@ -806,7 +806,7 @@ TLS Upgrade
Watching file descriptors
^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: loop.add_reader(fd, callback, \*args)
.. method:: loop.add_reader(fd, callback, *args)
Start monitoring the *fd* file descriptor for read availability and
invoke *callback* with the specified arguments once *fd* is available for
@ -816,7 +816,7 @@ Watching file descriptors
Stop monitoring the *fd* file descriptor for read availability.
.. method:: loop.add_writer(fd, callback, \*args)
.. method:: loop.add_writer(fd, callback, *args)
Start monitoring the *fd* file descriptor for write availability and
invoke *callback* with the specified arguments once *fd* is available for
@ -930,7 +930,7 @@ convenient.
:meth:`loop.create_server` and :func:`start_server`.
.. coroutinemethod:: loop.sock_sendfile(sock, file, offset=0, count=None, \
\*, fallback=True)
*, fallback=True)
Send a file using high-performance :mod:`os.sendfile` if possible.
Return the total number of bytes sent.
@ -964,7 +964,7 @@ convenient.
DNS
^^^
.. coroutinemethod:: loop.getaddrinfo(host, port, \*, family=0, \
.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=0, \
type=0, proto=0, flags=0)
Asynchronous version of :meth:`socket.getaddrinfo`.
@ -1029,7 +1029,7 @@ Working with pipes
Unix signals
^^^^^^^^^^^^
.. method:: loop.add_signal_handler(signum, callback, \*args)
.. method:: loop.add_signal_handler(signum, callback, *args)
Set *callback* as the handler for the *signum* signal.
@ -1064,7 +1064,7 @@ Unix signals
Executing code in thread or process pools
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. awaitablemethod:: loop.run_in_executor(executor, func, \*args)
.. awaitablemethod:: loop.run_in_executor(executor, func, *args)
Arrange for *func* to be called in the specified executor.
@ -1184,10 +1184,13 @@ Allows customizing how exceptions are handled in the event loop.
* 'message': Error message;
* 'exception' (optional): Exception object;
* 'future' (optional): :class:`asyncio.Future` instance;
* 'task' (optional): :class:`asyncio.Task` instance;
* 'handle' (optional): :class:`asyncio.Handle` instance;
* 'protocol' (optional): :ref:`Protocol <asyncio-protocol>` instance;
* 'transport' (optional): :ref:`Transport <asyncio-transport>` instance;
* 'socket' (optional): :class:`socket.socket` instance.
* 'socket' (optional): :class:`socket.socket` instance;
* 'asyncgen' (optional): Asynchronous generator that caused
the exception.
.. note::
@ -1234,9 +1237,9 @@ async/await code consider using the high-level
subprocesses. See :ref:`Subprocess Support on Windows
<asyncio-windows-subprocess>` for details.
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, \*args, \
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, \*\*kwargs)
stderr=subprocess.PIPE, **kwargs)
Create a subprocess from one or more string arguments specified by
*args*.
@ -1316,9 +1319,9 @@ async/await code consider using the high-level
conforms to the :class:`asyncio.SubprocessTransport` base class and
*protocol* is an object instantiated by the *protocol_factory*.
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, \*, \
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, *, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, \*\*kwargs)
stderr=subprocess.PIPE, **kwargs)
Create a subprocess from *cmd*, which can be a :class:`str` or a
:class:`bytes` string encoded to the

View File

@ -31,7 +31,7 @@ Future Functions
.. versionadded:: 3.5
.. function:: ensure_future(obj, \*, loop=None)
.. function:: ensure_future(obj, *, loop=None)
Return:
@ -58,7 +58,7 @@ Future Functions
The function accepts any :term:`awaitable` object.
.. function:: wrap_future(future, \*, loop=None)
.. function:: wrap_future(future, *, loop=None)
Wrap a :class:`concurrent.futures.Future` object in a
:class:`asyncio.Future` object.
@ -67,7 +67,7 @@ Future Functions
Future Object
=============
.. class:: Future(\*, loop=None)
.. class:: Future(*, loop=None)
A Future represents an eventual result of an asynchronous
operation. Not thread-safe.

View File

@ -159,7 +159,7 @@ implementation used by the asyncio event loop:
.. class:: AbstractChildWatcher
.. method:: add_child_handler(pid, callback, \*args)
.. method:: add_child_handler(pid, callback, *args)
Register a new child handler.

View File

@ -23,7 +23,7 @@ See also the `Examples`_ section below.
Queue
=====
.. class:: Queue(maxsize=0, \*, loop=None)
.. class:: Queue(maxsize=0)
A first in, first out (FIFO) queue.
@ -36,9 +36,6 @@ Queue
the queue is always known and can be returned by calling the
:meth:`qsize` method.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
This class is :ref:`not thread safe <asyncio-multithreading>`.

View File

@ -48,9 +48,9 @@ The following top-level asyncio functions can be used to create
and work with streams:
.. coroutinefunction:: open_connection(host=None, port=None, \*, \
loop=None, limit=None, ssl=None, family=0, \
proto=0, flags=0, sock=None, local_addr=None, \
.. coroutinefunction:: open_connection(host=None, port=None, *, \
limit=None, ssl=None, family=0, proto=0, \
flags=0, sock=None, local_addr=None, \
server_hostname=None, ssl_handshake_timeout=None)
Establish a network connection and return a pair of
@ -59,9 +59,6 @@ and work with streams:
The returned *reader* and *writer* objects are instances of
:class:`StreamReader` and :class:`StreamWriter` classes.
The *loop* argument is optional and can always be determined
automatically when this function is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
is set to 64 KiB.
@ -74,7 +71,7 @@ and work with streams:
The *ssl_handshake_timeout* parameter.
.. coroutinefunction:: start_server(client_connected_cb, host=None, \
port=None, \*, loop=None, limit=None, \
port=None, *, limit=None, \
family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, sock=None, \
backlog=100, ssl=None, reuse_address=None, \
@ -92,9 +89,6 @@ and work with streams:
:ref:`coroutine function <coroutine>`; if it is a coroutine function,
it will be automatically scheduled as a :class:`Task`.
The *loop* argument is optional and can always be determined
automatically when this method is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
is set to 64 KiB.
@ -109,9 +103,9 @@ and work with streams:
.. rubric:: Unix Sockets
.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, \
limit=None, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
.. coroutinefunction:: open_unix_connection(path=None, *, limit=None, \
ssl=None, sock=None, server_hostname=None, \
ssl_handshake_timeout=None)
Establish a Unix socket connection and return a pair of
``(reader, writer)``.
@ -132,9 +126,8 @@ and work with streams:
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \
\*, loop=None, limit=None, sock=None, \
backlog=100, ssl=None, ssl_handshake_timeout=None, \
start_serving=True)
*, limit=None, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, start_serving=True)
Start a Unix socket server.
@ -192,7 +185,7 @@ StreamReader
can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data.
.. coroutinemethod:: readuntil(separator=b'\\n')
.. coroutinemethod:: readuntil(separator=b'\n')
Read data from the stream until *separator* is found.

View File

@ -61,9 +61,8 @@ See also the `Examples`_ subsection.
Creating Subprocesses
=====================
.. coroutinefunction:: create_subprocess_exec(program, \*args, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \
stdout=None, stderr=None, limit=None, **kwds)
Create a subprocess.
@ -76,13 +75,9 @@ Creating Subprocesses
See the documentation of :meth:`loop.subprocess_exec` for other
parameters.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
stdout=None, stderr=None, limit=None, **kwds)
Run the *cmd* shell command.
@ -104,10 +99,6 @@ Creating Subprocesses
escape whitespace and special shell characters in strings that are going
to be used to construct shell commands.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. note::
Subprocesses are available for Windows if a :class:`ProactorEventLoop` is

View File

@ -36,7 +36,7 @@ asyncio has the following basic synchronization primitives:
Lock
====
.. class:: Lock(\*, loop=None)
.. class:: Lock()
Implements a mutex lock for asyncio tasks. Not thread-safe.
@ -63,9 +63,6 @@ Lock
finally:
lock.release()
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. coroutinemethod:: acquire()
Acquire the lock.
@ -96,7 +93,7 @@ Lock
Event
=====
.. class:: Event(\*, loop=None)
.. class:: Event()
An event object. Not thread-safe.
@ -104,14 +101,10 @@ Event
that some event has happened.
An Event object manages an internal flag that can be set to *true*
with the :meth:`set` method and reset to *false* with the
:meth:`clear` method. The :meth:`wait` method blocks until the
with the :meth:`~Event.set` method and reset to *false* with the
:meth:`clear` method. The :meth:`~Event.wait` method blocks until the
flag is set to *true*. The flag is set to *false* initially.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_sync_event:
Example::
@ -142,7 +135,7 @@ Event
Wait until the event is set.
If the event is set, return ``True`` immediately.
Otherwise block until another task calls :meth:`set`.
Otherwise block until another task calls :meth:`~Event.set`.
.. method:: set()
@ -155,8 +148,8 @@ Event
Clear (unset) the event.
Tasks awaiting on :meth:`wait` will now block until the
:meth:`set` method is called again.
Tasks awaiting on :meth:`~Event.wait` will now block until the
:meth:`~Event.set` method is called again.
.. method:: is_set()
@ -166,7 +159,7 @@ Event
Condition
=========
.. class:: Condition(lock=None, \*, loop=None)
.. class:: Condition(lock=None)
A Condition object. Not thread-safe.
@ -184,10 +177,6 @@ Condition
``None``. In the latter case a new Lock object is created
automatically.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
The preferred way to use a Condition is an :keyword:`async with`
statement::
@ -270,7 +259,7 @@ Condition
Semaphore
=========
.. class:: Semaphore(value=1, \*, loop=None)
.. class:: Semaphore(value=1)
A Semaphore object. Not thread-safe.
@ -284,10 +273,6 @@ Semaphore
internal counter (``1`` by default). If the given value is
less than ``0`` a :exc:`ValueError` is raised.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
The preferred way to use a Semaphore is an :keyword:`async with`
statement::
@ -332,7 +317,7 @@ Semaphore
BoundedSemaphore
================
.. class:: BoundedSemaphore(value=1, \*, loop=None)
.. class:: BoundedSemaphore(value=1)
A bounded semaphore object. Not thread-safe.
@ -340,10 +325,6 @@ BoundedSemaphore
a :exc:`ValueError` in :meth:`~Semaphore.release` if it
increases the internal counter above the initial *value*.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
---------

View File

@ -210,7 +210,7 @@ is :meth:`loop.run_in_executor`.
Running an asyncio Program
==========================
.. function:: run(coro, \*, debug=False)
.. function:: run(coro, *, debug=False)
Execute the :term:`coroutine` *coro* and return the result.
@ -247,7 +247,7 @@ Running an asyncio Program
Creating Tasks
==============
.. function:: create_task(coro, \*, name=None)
.. function:: create_task(coro, *, name=None)
Wrap the *coro* :ref:`coroutine <coroutine>` into a :class:`Task`
and schedule its execution. Return the Task object.
@ -283,7 +283,7 @@ Creating Tasks
Sleeping
========
.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
.. coroutinefunction:: sleep(delay, result=None)
Block for *delay* seconds.
@ -293,9 +293,6 @@ Sleeping
``sleep()`` always suspends the current task, allowing other tasks
to run.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_sleep:
Example of coroutine displaying the current date every second
@ -319,7 +316,7 @@ Sleeping
Running Tasks Concurrently
==========================
.. awaitablefunction:: gather(\*aws, loop=None, return_exceptions=False)
.. awaitablefunction:: gather(*aws, return_exceptions=False)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
sequence *concurrently*.
@ -348,9 +345,6 @@ Running Tasks Concurrently
cancellation of one submitted Task/Future to cause other
Tasks/Futures to be cancelled.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_gather:
Example::
@ -403,7 +397,7 @@ Running Tasks Concurrently
Shielding From Cancellation
===========================
.. awaitablefunction:: shield(aw, \*, loop=None)
.. awaitablefunction:: shield(aw)
Protect an :ref:`awaitable object <asyncio-awaitables>`
from being :meth:`cancelled <Task.cancel>`.
@ -436,14 +430,11 @@ Shielding From Cancellation
except CancelledError:
res = None
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Timeouts
========
.. coroutinefunction:: wait_for(aw, timeout, \*, loop=None)
.. coroutinefunction:: wait_for(aw, timeout)
Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
to complete with a timeout.
@ -466,9 +457,6 @@ Timeouts
If the wait is cancelled, the future *aw* is also cancelled.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_waitfor:
Example::
@ -500,8 +488,7 @@ Timeouts
Waiting Primitives
==================
.. coroutinefunction:: wait(aws, \*, loop=None, timeout=None,\
return_when=ALL_COMPLETED)
.. coroutinefunction:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
iterable concurrently and block until the condition specified
@ -553,10 +540,6 @@ Waiting Primitives
``wait()`` directly is deprecated as it leads to
:ref:`confusing behavior <asyncio_example_wait_coroutine>`.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
.. _asyncio_example_wait_coroutine:
.. note::
@ -590,7 +573,7 @@ Waiting Primitives
deprecated.
.. function:: as_completed(aws, \*, loop=None, timeout=None)
.. function:: as_completed(aws, *, timeout=None)
Run :ref:`awaitable objects <asyncio-awaitables>` in the *aws*
iterable concurrently. Return an iterator of coroutines.
@ -600,9 +583,6 @@ Waiting Primitives
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
all Futures are done.
.. deprecated-removed:: 3.8 3.10
The *loop* parameter.
Example::
for coro in as_completed(aws):
@ -613,7 +593,7 @@ Waiting Primitives
Running in Threads
==================
.. coroutinefunction:: to_thread(func, /, \*args, \*\*kwargs)
.. coroutinefunction:: to_thread(func, /, *args, **kwargs)
Asynchronously run function *func* in a separate thread.
@ -743,7 +723,7 @@ Introspection
Task Object
===========
.. class:: Task(coro, \*, loop=None, name=None)
.. class:: Task(coro, *, loop=None, name=None)
A :class:`Future-like <Future>` object that runs a Python
:ref:`coroutine <coroutine>`. Not thread-safe.
@ -909,7 +889,7 @@ Task Object
See the documentation of :meth:`Future.remove_done_callback`
for more details.
.. method:: get_stack(\*, limit=None)
.. method:: get_stack(*, limit=None)
Return the list of stack frames for this Task.
@ -930,7 +910,7 @@ Task Object
stack are returned, but the oldest frames of a traceback are
returned. (This matches the behavior of the traceback module.)
.. method:: print_stack(\*, limit=None, file=None)
.. method:: print_stack(*, limit=None, file=None)
Print the stack or traceback for this Task.

View File

@ -199,7 +199,7 @@ The modern interface provides:
.. versionadded:: 3.4
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
.. function:: a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\v')
Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *b* and
return the decoded :class:`bytes`.

View File

@ -266,7 +266,6 @@ Below are some examples of typical usage of the :mod:`bz2` module.
Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@ -275,11 +274,9 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c) # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d # Check equality to original object after round-trip
True
@ -287,7 +284,6 @@ Using :func:`compress` and :func:`decompress` to demonstrate round-trip compress
Using :class:`BZ2Compressor` for incremental compression:
>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
... """Yield incremental blocks of chunksize bytes."""
... for _ in range(chunks):
@ -310,7 +306,6 @@ while ordered, repetitive data usually yields a high compression ratio.
Writing and reading a bzip2-compressed file in binary mode:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
@ -319,14 +314,11 @@ Writing and reading a bzip2-compressed file in binary mode:
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
... # Write compressed data to file
... unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
... # Decompress data from file
... content = f.read()
>>> content == data # Check equality to original object after round-trip
True

View File

@ -148,7 +148,7 @@ runtime.
Public functions
----------------
.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, \*, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way. Return a true value if all the files compiled successfully,
@ -231,7 +231,7 @@ Public functions
Added *stripdir*, *prependdir*, *limit_sl_dest* and *hardlink_dupes* arguments.
Default value of *maxlevels* was changed from ``10`` to ``sys.getrecursionlimit()``
.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, \*, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)
Compile the file with path *fullname*. Return a true value if the file
compiled successfully, and a false value otherwise.

View File

@ -67,7 +67,7 @@ Executor Objects
.. versionchanged:: 3.5
Added the *chunksize* argument.
.. method:: shutdown(wait=True, \*, cancel_futures=False)
.. method:: shutdown(wait=True, *, cancel_futures=False)
Signal the executor that it should free any resources that it is using
when the currently pending futures are done executing. Calls to

View File

@ -26,7 +26,7 @@ See also :pep:`567` for additional details.
Context Variables
-----------------
.. class:: ContextVar(name, [\*, default])
.. class:: ContextVar(name, [*, default])
This class is used to declare a new Context Variable, e.g.::
@ -146,7 +146,7 @@ Manual Context Management
Context implements the :class:`collections.abc.Mapping` interface.
.. method:: run(callable, \*args, \*\*kwargs)
.. method:: run(callable, *args, **kwargs)
Execute ``callable(*args, **kwargs)`` code in the context object
the *run* method is called on. Return the result of the execution

View File

@ -2508,7 +2508,7 @@ other data types containing pointer type fields.
Arrays and pointers
^^^^^^^^^^^^^^^^^^^
.. class:: Array(\*args)
.. class:: Array(*args)
Abstract base class for arrays.

View File

@ -1219,7 +1219,7 @@ Instance methods:
.. method:: datetime.replace(year=self.year, month=self.month, day=self.day, \
hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, \
tzinfo=self.tzinfo, * fold=0)
tzinfo=self.tzinfo, *, fold=0)
Return a datetime with the same attributes, except for those attributes given
new values by whichever keyword arguments are specified. Note that
@ -1783,7 +1783,7 @@ Other constructor:
Instance methods:
.. method:: time.replace(hour=self.hour, minute=self.minute, second=self.second, \
microsecond=self.microsecond, tzinfo=self.tzinfo, * fold=0)
microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)
Return a :class:`.time` with the same value, except for those attributes given
new values by whichever keyword arguments are specified. Note that

View File

@ -149,7 +149,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
contains a good example of its use.
.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
.. function:: context_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in context diff format.
@ -279,7 +279,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
emu
.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\\n')
.. function:: unified_diff(a, b, fromfile='', tofile='', fromfiledate='', tofiledate='', n=3, lineterm='\n')
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in unified diff format.
@ -321,7 +321,7 @@ diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
See :ref:`difflib-interface` for a more detailed example.
.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\\n')
.. function:: diff_bytes(dfunc, a, b, fromfile=b'', tofile=b'', fromfiledate=b'', tofiledate=b'', n=3, lineterm=b'\n')
Compare *a* and *b* (lists of bytes objects) using *dfunc*; yield a
sequence of delta lines (also bytes) in the format returned by *dfunc*.

View File

@ -708,7 +708,8 @@ iterations of the loop.
.. opcode:: RERAISE
Re-raises the exception currently on top of the stack.
Re-raises the exception currently on top of the stack. If oparg is non-zero,
restores ``f_lasti`` of the current frame to its value when the exception was raised.
.. versionadded:: 3.9

View File

@ -719,7 +719,10 @@ above.
An example's doctest directives modify doctest's behavior for that single
example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
For example, this test passes::
For example, this test passes:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
@ -728,19 +731,28 @@ For example, this test passes::
Without the directive it would fail, both because the actual output doesn't have
two blanks before the single-digit list elements, and because the actual output
is on a single line. This test also passes, and also requires a directive to do
so::
so:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by
commas::
commas:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
If multiple directive comments are used for a single example, then they are
combined::
combined:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(20))) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
@ -748,7 +760,10 @@ combined::
As the previous example shows, you can add ``...`` lines to your example
containing only directives. This can be useful when an example is too long for
a directive to comfortably fit on the same line::
a directive to comfortably fit on the same line:
.. doctest::
:no-trim-doctest-flags:
>>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40)))
... # doctest: +ELLIPSIS
@ -793,18 +808,23 @@ instead. Another is to do ::
There are others, but you get the idea.
Another bad idea is to print things that embed an object address, like ::
Another bad idea is to print things that embed an object address, like
>>> id(1.0) # certain to fail some of the time
.. doctest::
>>> id(1.0) # certain to fail some of the time # doctest: +SKIP
7948648
>>> class C: pass
>>> C() # the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>
>>> C() # the default repr() for instances embeds an address # doctest: +SKIP
<C object at 0x00AC18F0>
The :const:`ELLIPSIS` directive gives a nice approach for the last example::
The :const:`ELLIPSIS` directive gives a nice approach for the last example:
>>> C() #doctest: +ELLIPSIS
<__main__.C instance at 0x...>
.. doctest::
:no-trim-doctest-flags:
>>> C() # doctest: +ELLIPSIS
<C object at 0x...>
Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for float formatting,

View File

@ -116,7 +116,7 @@ Currently the email package provides only one concrete content manager,
decoding the payload to unicode. The default error handler is
``replace``.
.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8' \
.. method:: set_content(msg, <'str'>, subtype="plain", charset='utf-8', \
cte=None, \
disposition=None, filename=None, cid=None, \
params=None, headers=None)

View File

@ -116,7 +116,7 @@ Here is the :class:`Header` class description:
if *s* is a byte string.
.. method:: encode(splitchars=';, \\t', maxlinelen=None, linesep='\\n')
.. method:: encode(splitchars=';, \t', maxlinelen=None, linesep='\n')
Encode a message header into an RFC-compliant format, possibly wrapping
long lines and encapsulating non-ASCII parts in base64 or quoted-printable

View File

@ -289,7 +289,7 @@ variant, :attr:`~.BaseHeader.max_count` is set to 1.
A :class:`ParameterizedMIMEHeader` class that handles the
:mailheader:`Content-Disposition` header.
.. attribute:: content-disposition
.. attribute:: content_disposition
``inline`` and ``attachment`` are the only valid values in common use.

View File

@ -210,7 +210,7 @@ added matters. To illustrate::
:meth:`register_defect` method.
.. attribute:: mangle_from\_
.. attribute:: mangle_from_
If :const:`True`, lines starting with *"From "* in the body are
escaped by putting a ``>`` in front of them. This parameter is used when

View File

@ -67,10 +67,12 @@ helper, :class:`auto`.
.. class:: auto
Instances are replaced with an appropriate value for Enum members. By default, the initial value starts at 1.
Instances are replaced with an appropriate value for Enum members.
:class:`StrEnum` defaults to the lower-cased version of the member name,
while other Enums default to 1 and increase from there.
.. versionadded:: 3.6 ``Flag``, ``IntFlag``, ``auto``
.. versionadded:: 3.10 ``StrEnum``
Creating an Enum
----------------
@ -1164,6 +1166,15 @@ and raise an error if the two do not match::
In Python 2 code the :attr:`_order_` attribute is necessary as definition
order is lost before it can be recorded.
_Private__names
"""""""""""""""
Private names are not converted to Enum members, but remain normal attributes.
.. versionchanged:: 3.10
``Enum`` member type
""""""""""""""""""""

View File

@ -90,8 +90,13 @@ The following exceptions are used mostly as base classes for other exceptions.
.. method:: with_traceback(tb)
This method sets *tb* as the new traceback for the exception and returns
the exception object. It is usually used in exception handling code like
this::
the exception object. It was more commonly used before the exception
chaining features of :pep:`3134` became available. The following example
shows how we can convert an instance of ``SomeException`` into an
instance of ``OtherException`` while preserving the traceback. Once
raised, the current frame is pushed onto the traceback of the
``OtherException``, as would have happened to the traceback of the
original ``SomeException`` had we allowed it to propagate to the caller.
try:
...

View File

@ -75,7 +75,7 @@ patterns.
.. function:: filter(names, pattern)
Return the subset of the list of *names* that match *pattern*. It is the same as
Construct a list from those elements of the iterable *names* that match *pattern*. It is the same as
``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.

View File

@ -478,14 +478,15 @@ are always available. They are listed here in alphabetical order.
dictionaries as global and local namespace. If the *globals* dictionary is
present and does not contain a value for the key ``__builtins__``, a
reference to the dictionary of the built-in module :mod:`builtins` is
inserted under that key before *expression* is parsed. This means that
*expression* normally has full access to the standard :mod:`builtins`
module and restricted environments are propagated. If the *locals*
dictionary is omitted it defaults to the *globals* dictionary. If both
dictionaries are omitted, the expression is executed with the *globals* and
*locals* in the environment where :func:`eval` is called. Note, *eval()*
does not have access to the :term:`nested scopes <nested scope>` (non-locals) in the
enclosing environment.
inserted under that key before *expression* is parsed. That way you can
control what builtins are available to the executed code by inserting your
own ``__builtins__`` dictionary into *globals* before passing it to
:func:`eval`. If the *locals* dictionary is omitted it defaults to the
*globals* dictionary. If both dictionaries are omitted, the expression is
executed with the *globals* and *locals* in the environment where
:func:`eval` is called. Note, *eval()* does not have access to the
:term:`nested scopes <nested scope>` (non-locals) in the enclosing
environment.
The return value is the result of
the evaluated expression. Syntax errors are reported as exceptions. Example:
@ -1340,7 +1341,7 @@ are always available. They are listed here in alphabetical order.
supported.
.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout, flush=False)
.. function:: print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)
Print *objects* to the text stream *file*, separated by *sep* and followed
by *end*. *sep*, *end*, *file* and *flush*, if present, must be given as keyword

View File

@ -62,16 +62,26 @@ The :mod:`functools` module defines the following functions:
Example::
class DataSet:
def __init__(self, sequence_of_numbers):
self._data = sequence_of_numbers
self._data = tuple(sequence_of_numbers)
@cached_property
def stdev(self):
return statistics.stdev(self._data)
@cached_property
def variance(self):
return statistics.variance(self._data)
The mechanics of :func:`cached_property` are somewhat different from
:func:`property`. A regular property blocks attribute writes unless a
setter is defined. In contrast, a *cached_property* allows writes.
The *cached_property* decorator only runs on lookups and only when an
attribute of the same name doesn't exist. When it does run, the
*cached_property* writes to the attribute with the same name. Subsequent
attribute reads and writes take precedence over the *cached_property*
method and it works like a normal attribute.
The cached value can be cleared by deleting the attribute. This
allows the *cached_property* method to run again.
Note, this decorator interferes with the operation of :pep:`412`
key-sharing dictionaries. This means that instance dictionaries

View File

@ -93,7 +93,7 @@ Cookie Objects
:meth:`value_decode` are inverses on the range of *value_decode*.
.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\\r\\n')
.. method:: BaseCookie.output(attrs=None, header='Set-Cookie:', sep='\r\n')
Return a string representation suitable to be sent as HTTP headers. *attrs* and
*header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used

View File

@ -115,8 +115,9 @@ Every distribution includes some metadata, which you can extract using the
>>> wheel_metadata = metadata('wheel') # doctest: +SKIP
The keys of the returned data structure [#f1]_ name the metadata keywords, and
their values are returned unparsed from the distribution metadata::
The keys of the returned data structure, a ``PackageMetadata``,
name the metadata keywords, and
the values are returned unparsed from the distribution metadata::
>>> wheel_metadata['Requires-Python'] # doctest: +SKIP
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
@ -206,9 +207,9 @@ Thus, an alternative way to get the version number is through the
There are all kinds of additional metadata available on the ``Distribution``
instance::
>>> d.metadata['Requires-Python'] # doctest: +SKIP
>>> dist.metadata['Requires-Python'] # doctest: +SKIP
'>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
>>> d.metadata['License'] # doctest: +SKIP
>>> dist.metadata['License'] # doctest: +SKIP
'MIT'
The full set of available metadata is not described here. See :pep:`566`
@ -259,9 +260,3 @@ a custom finder, return instances of this derived ``Distribution`` in the
.. rubric:: Footnotes
.. [#f1] Technically, the returned distribution metadata object is an
:class:`email.message.EmailMessage`
instance, but this is an implementation detail, and not part of the
stable API. You should only use dictionary-like methods and syntax
to access the metadata contents.

View File

@ -1138,7 +1138,7 @@ find and load modules.
directory for ``''`` (i.e. the empty string).
.. class:: FileFinder(path, \*loader_details)
.. class:: FileFinder(path, *loader_details)
A concrete implementation of :class:`importlib.abc.PathEntryFinder` which
caches results from the file system.
@ -1181,7 +1181,7 @@ find and load modules.
Clear out the internal cache.
.. classmethod:: path_hook(\*loader_details)
.. classmethod:: path_hook(*loader_details)
A class method which returns a closure for use on :attr:`sys.path_hooks`.
An instance of :class:`FileFinder` is returned by the closure using the

View File

@ -556,7 +556,7 @@ The Signature object represents the call signature of a callable object and its
return annotation. To retrieve a Signature object, use the :func:`signature`
function.
.. function:: signature(callable, \*, follow_wrapped=True)
.. function:: signature(callable, *, follow_wrapped=True, globalns=None, localns=None)
Return a :class:`Signature` object for the given ``callable``::
@ -581,6 +581,9 @@ function.
Raises :exc:`ValueError` if no signature can be provided, and
:exc:`TypeError` if that type of object is not supported.
``globalns`` and ``localns`` are passed into
:func:`typing.get_type_hints` when resolving the annotations.
A slash(/) in the signature of a function denotes that the parameters prior
to it are positional-only. For more info, see
:ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.
@ -590,14 +593,23 @@ function.
``callable`` specifically (``callable.__wrapped__`` will not be used to
unwrap decorated callables.)
.. versionadded:: 3.10
``globalns`` and ``localns`` parameters.
.. note::
Some callables may not be introspectable in certain implementations of
Python. For example, in CPython, some built-in functions defined in
C provide no metadata about their arguments.
.. note::
.. class:: Signature(parameters=None, \*, return_annotation=Signature.empty)
Will first try to resolve the annotations, but when it fails and
encounters with an error while that operation, the annotations will be
returned unchanged (as strings).
.. class:: Signature(parameters=None, *, return_annotation=Signature.empty)
A Signature object represents the call signature of a function and its return
annotation. For each parameter accepted by the function it stores a
@ -668,11 +680,12 @@ function.
>>> str(new_sig)
"(a, b) -> 'new return anno'"
.. classmethod:: Signature.from_callable(obj, \*, follow_wrapped=True)
.. classmethod:: Signature.from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)
Return a :class:`Signature` (or its subclass) object for a given callable
``obj``. Pass ``follow_wrapped=False`` to get a signature of ``obj``
without unwrapping its ``__wrapped__`` chain.
without unwrapping its ``__wrapped__`` chain. ``globalns`` and
``localns`` will be used as the namespaces when resolving annotations.
This method simplifies subclassing of :class:`Signature`::
@ -683,8 +696,11 @@ function.
.. versionadded:: 3.5
.. versionadded:: 3.10
``globalns`` and ``localns`` parameters.
.. class:: Parameter(name, kind, \*, default=Parameter.empty, annotation=Parameter.empty)
.. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)
Parameter objects are *immutable*. Instead of modifying a Parameter object,
you can use :meth:`Parameter.replace` to create a modified copy.

View File

@ -964,7 +964,7 @@ Text I/O
.. versionadded:: 3.7
.. class:: StringIO(initial_value='', newline='\\n')
.. class:: StringIO(initial_value='', newline='\n')
A text stream using an in-memory text buffer. It inherits
:class:`TextIOBase`.

View File

@ -55,6 +55,7 @@ Iterator Arguments Results
:func:`filterfalse` pred, seq elements of seq where pred(elem) is false ``filterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8``
:func:`groupby` iterable[, key] sub-iterators grouped by value of key(v)
:func:`islice` seq, [start,] stop [, step] elements from seq[start:stop:step] ``islice('ABCDEFG', 2, None) --> C D E F G``
:func:`pairwise` iterable (p[0], p[1]), (p[1], p[2]) ``pairwise('ABCDEFG') --> AB BC CD DE EF FG``
:func:`starmap` func, seq func(\*seq[0]), func(\*seq[1]), ... ``starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000``
:func:`takewhile` pred, seq seq[0], seq[1], until pred fails ``takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4``
:func:`tee` it, n it1, it2, ... itn splits one iterator into n
@ -475,6 +476,22 @@ loops that truncate the stream.
If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
then the step defaults to one.
.. function:: pairwise(iterable)
Return successive overlapping pairs taken from the input *iterable*.
The number of 2-tuples in the output iterator will be one fewer than the
number of inputs. It will be empty if the input iterable has fewer than
two values.
Roughly equivalent to::
def pairwise(iterable):
# pairwise('ABCDEFG') --> AB BC CD DE EF FG
a, b = tee(iterable)
next(b, None)
return zip(a, b)
.. function:: permutations(iterable, r=None)
@ -565,7 +582,7 @@ loops that truncate the stream.
Before :func:`product` runs, it completely consumes the input iterables,
keeping pools of values in memory to generate the products. Accordingly,
it only useful with finite inputs.
it is only useful with finite inputs.
.. function:: repeat(object[, times])
@ -755,7 +772,7 @@ which incur interpreter overhead.
"Count how many times the predicate is true"
return sum(map(pred, iterable))
def padnone(iterable):
def pad_none(iterable):
"""Returns the sequence elements and then returns None indefinitely.
Useful for emulating the behavior of the built-in map() function.
@ -769,6 +786,18 @@ which incur interpreter overhead.
def dotproduct(vec1, vec2):
return sum(map(operator.mul, vec1, vec2))
def convolve(signal, kernel):
# See: https://betterexplained.com/articles/intuitive-convolution/
# convolve(data, [0.25, 0.25, 0.25, 0.25]) --> Moving average (blur)
# convolve(data, [1, -1]) --> 1st finite difference (1st derivative)
# convolve(data, [1, -2, 1]) --> 2nd finite difference (2nd derivative)
kernel = tuple(kernel)[::-1]
n = len(kernel)
window = collections.deque([0], maxlen=n) * n
for x in chain(signal, repeat(0, n-1)):
window.append(x)
yield sum(map(operator.mul, kernel, window))
def flatten(list_of_lists):
"Flatten one level of nesting"
return chain.from_iterable(list_of_lists)
@ -782,12 +811,6 @@ which incur interpreter overhead.
return starmap(func, repeat(args))
return starmap(func, repeat(args, times))
def pairwise(iterable):
"s -> (s0,s1), (s1,s2), (s2, s3), ..."
a, b = tee(iterable)
next(b, None)
return zip(a, b)
def grouper(iterable, n, fillvalue=None):
"Collect data into fixed-length chunks or blocks"
# grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
@ -809,7 +832,7 @@ which incur interpreter overhead.
nexts = cycle(islice(nexts, num_active))
def partition(pred, iterable):
'Use a predicate to partition entries into false entries and true entries'
"Use a predicate to partition entries into false entries and true entries"
# partition(is_odd, range(10)) --> 0 2 4 6 8 and 1 3 5 7 9
t1, t2 = tee(iterable)
return filterfalse(pred, t1), filter(pred, t2)
@ -881,7 +904,7 @@ which incur interpreter overhead.
def random_product(*args, repeat=1):
"Random selection from itertools.product(*args, **kwds)"
pools = [tuple(pool) for pool in args] * repeat
return tuple(random.choice(pool) for pool in pools)
return tuple(map(random.choice, pools))
def random_permutation(iterable, r=None):
"Random selection from itertools.permutations(iterable, r)"
@ -900,11 +923,11 @@ which incur interpreter overhead.
"Random selection from itertools.combinations_with_replacement(iterable, r)"
pool = tuple(iterable)
n = len(pool)
indices = sorted(random.randrange(n) for i in range(r))
indices = sorted(random.choices(range(n), k=r))
return tuple(pool[i] for i in indices)
def nth_combination(iterable, r, index):
'Equivalent to list(combinations(iterable, r))[index]'
"Equivalent to list(combinations(iterable, r))[index]"
pool = tuple(iterable)
n = len(pool)
if r < 0 or r > n:

View File

@ -1096,8 +1096,8 @@ functions.
suitable value.
.. versionchanged:: 3.7
The *level* parameter was defaulted to level ``CRITICAL``. See Issue
#28524 for more information about this change.
The *level* parameter was defaulted to level ``CRITICAL``. See
:issue:`28524` for more information about this change.
.. function:: addLevelName(level, levelName)
@ -1174,7 +1174,9 @@ functions.
| | to ``'a'``. |
+--------------+---------------------------------------------+
| *format* | Use the specified format string for the |
| | handler. |
| | handler. Defaults to attributes |
| | ``levelname``, ``name`` and ``message`` |
| | separated by colons. |
+--------------+---------------------------------------------+
| *datefmt* | Use the specified date/time format, as |
| | accepted by :func:`time.strftime`. |

View File

@ -33,7 +33,7 @@ from multiple threads, it is necessary to protect it with a lock.
Reading and writing compressed files
------------------------------------
.. function:: open(filename, mode="rb", \*, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)
.. function:: open(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)
Open an LZMA-compressed file in binary or text mode, returning a :term:`file
object`.
@ -69,7 +69,7 @@ Reading and writing compressed files
Accepts a :term:`path-like object`.
.. class:: LZMAFile(filename=None, mode="r", \*, format=None, check=-1, preset=None, filters=None)
.. class:: LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)
Open an LZMA-compressed file in binary mode.

View File

@ -2661,6 +2661,46 @@ The :mod:`multiprocessing.dummy` module
:mod:`multiprocessing.dummy` replicates the API of :mod:`multiprocessing` but is
no more than a wrapper around the :mod:`threading` module.
.. currentmodule:: multiprocessing.pool
In particular, the ``Pool`` function provided by :mod:`multiprocessing.dummy`
returns an instance of :class:`ThreadPool`, which is a subclass of
:class:`Pool` that supports all the same method calls but uses a pool of
worker threads rather than worker processes.
.. class:: ThreadPool([processes[, initializer[, initargs]]])
A thread pool object which controls a pool of worker threads to which jobs
can be submitted. :class:`ThreadPool` instances are fully interface
compatible with :class:`Pool` instances, and their resources must also be
properly managed, either by using the pool as a context manager or by
calling :meth:`~multiprocessing.pool.Pool.close` and
:meth:`~multiprocessing.pool.Pool.terminate` manually.
*processes* is the number of worker threads to use. If *processes* is
``None`` then the number returned by :func:`os.cpu_count` is used.
If *initializer* is not ``None`` then each worker process will call
``initializer(*initargs)`` when it starts.
Unlike :class:`Pool`, *maxtasksperchild* and *context* cannot be provided.
.. note::
A :class:`ThreadPool` shares the same interface as :class:`Pool`, which
is designed around a pool of processes and predates the introduction of
the :class:`concurrent.futures` module. As such, it inherits some
operations that don't make sense for a pool backed by threads, and it
has its own type for representing the status of asynchronous jobs,
:class:`AsyncResult`, that is not understood by any other libraries.
Users should generally prefer to use
:class:`concurrent.futures.ThreadPoolExecutor`, which has a simpler
interface that was designed around threads from the start, and which
returns :class:`concurrent.futures.Future` instances that are
compatible with many other libraries, including :mod:`asyncio`.
.. _multiprocessing-programming:

View File

@ -32,7 +32,7 @@ Notes on the availability of these functions:
objects, and result in an object of the same type, if a path or file name is
returned.
* On VxWorks, os.fork, os.execv and os.spawn*p* are not supported.
* On VxWorks, os.popen, os.fork, os.execv and os.spawn*p* are not supported.
.. note::
@ -1991,7 +1991,7 @@ features:
Accepts a :term:`path-like object`.
.. function:: lstat(path, \*, dir_fd=None)
.. function:: lstat(path, *, dir_fd=None)
Perform the equivalent of an :c:func:`lstat` system call on the given path.
Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
@ -2498,7 +2498,7 @@ features:
On the first, uncached call, a system call is required on Windows but
not on Unix.
.. method:: is_dir(\*, follow_symlinks=True)
.. method:: is_dir(*, follow_symlinks=True)
Return ``True`` if this entry is a directory or a symbolic link pointing
to a directory; return ``False`` if the entry is or points to any other
@ -2522,7 +2522,7 @@ features:
This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
but :exc:`FileNotFoundError` is caught and not raised.
.. method:: is_file(\*, follow_symlinks=True)
.. method:: is_file(*, follow_symlinks=True)
Return ``True`` if this entry is a file or a symbolic link pointing to a
file; return ``False`` if the entry is or points to a directory or other
@ -2552,7 +2552,7 @@ features:
This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
but :exc:`FileNotFoundError` is caught and not raised.
.. method:: stat(\*, follow_symlinks=True)
.. method:: stat(*, follow_symlinks=True)
Return a :class:`stat_result` object for this entry. This method
follows symbolic links by default; to stat a symbolic link add the
@ -2584,7 +2584,7 @@ features:
for :class:`bytes` paths on Windows.
.. function:: stat(path, \*, dir_fd=None, follow_symlinks=True)
.. function:: stat(path, *, dir_fd=None, follow_symlinks=True)
Get the status of a file or a file descriptor. Perform the equivalent of a
:c:func:`stat` system call on the given path. *path* may be specified as

View File

@ -213,7 +213,7 @@ The :mod:`pickle` module provides the following constants:
The :mod:`pickle` module provides the following functions to make the pickling
process more convenient:
.. function:: dump(obj, file, protocol=None, \*, fix_imports=True, buffer_callback=None)
.. function:: dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)
Write the pickled representation of the object *obj* to the open
:term:`file object` *file*. This is equivalent to
@ -225,7 +225,7 @@ process more convenient:
.. versionchanged:: 3.8
The *buffer_callback* argument was added.
.. function:: dumps(obj, protocol=None, \*, fix_imports=True, buffer_callback=None)
.. function:: dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)
Return the pickled representation of the object *obj* as a :class:`bytes` object,
instead of writing it to a file.
@ -236,7 +236,7 @@ process more convenient:
.. versionchanged:: 3.8
The *buffer_callback* argument was added.
.. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
.. function:: load(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
Read the pickled representation of an object from the open :term:`file object`
*file* and return the reconstituted object hierarchy specified therein.
@ -252,7 +252,7 @@ process more convenient:
.. versionchanged:: 3.8
The *buffers* argument was added.
.. function:: loads(data, /, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
.. function:: loads(data, /, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
Return the reconstituted object hierarchy of the pickled representation
*data* of an object. *data* must be a :term:`bytes-like object`.
@ -296,7 +296,7 @@ The :mod:`pickle` module defines three exceptions:
The :mod:`pickle` module exports three classes, :class:`Pickler`,
:class:`Unpickler` and :class:`PickleBuffer`:
.. class:: Pickler(file, protocol=None, \*, fix_imports=True, buffer_callback=None)
.. class:: Pickler(file, protocol=None, *, fix_imports=True, buffer_callback=None)
This takes a binary file for writing a pickle data stream.
@ -391,7 +391,7 @@ The :mod:`pickle` module exports three classes, :class:`Pickler`,
Use :func:`pickletools.optimize` if you need more compact pickles.
.. class:: Unpickler(file, \*, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
.. class:: Unpickler(file, *, fix_imports=True, encoding="ASCII", errors="strict", buffers=None)
This takes a binary file for reading a pickle data stream.

View File

@ -17,6 +17,8 @@ The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
shell for :func:`os.system` and :func:`os.popen` is required.
.. availability:: Unix. Not available on VxWorks.
The :mod:`pipes` module defines the following class:

View File

@ -253,3 +253,41 @@ Unix Platforms
using :program:`gcc`.
The file is read and scanned in chunks of *chunksize* bytes.
Linux Platforms
---------------
.. function:: freedesktop_os_release()
Get operating system identification from ``os-release`` file and return
it as a dict. The ``os-release`` file is a `freedesktop.org standard
<https://www.freedesktop.org/software/systemd/man/os-release.html>`_ and
is available in most Linux distributions. A noticeable exception is
Android and Android-based distributions.
Raises :exc:`OSError` or subclass when neither ``/etc/os-release`` nor
``/usr/lib/os-release`` can be read.
On success, the function returns a dictionary where keys and values are
strings. Values have their special characters like ``"`` and ``$``
unquoted. The fields ``NAME``, ``ID``, and ``PRETTY_NAME`` are always
defined according to the standard. All other fields are optional. Vendors
may include additional fields.
Note that fields like ``NAME``, ``VERSION``, and ``VARIANT`` are strings
suitable for presentation to users. Programs should use fields like
``ID``, ``ID_LIKE``, ``VERSION_ID``, or ``VARIANT_ID`` to identify
Linux distributions.
Example::
def get_like_distro():
info = platform.freedesktop_os_release()
ids = [info["ID"]]
if "ID_LIKE" in info:
# ids are space separated and ordered by precedence
ids.extend(info["ID_LIKE"].split())
return ids
.. versionadded:: 3.10

View File

@ -52,7 +52,7 @@ or :class:`datetime.datetime` objects.
This module defines the following functions:
.. function:: load(fp, \*, fmt=None, dict_type=dict)
.. function:: load(fp, *, fmt=None, dict_type=dict)
Read a plist file. *fp* should be a readable and binary file object.
Return the unpacked root object (which usually is a
@ -80,7 +80,7 @@ This module defines the following functions:
.. versionadded:: 3.4
.. function:: loads(data, \*, fmt=None, dict_type=dict)
.. function:: loads(data, *, fmt=None, dict_type=dict)
Load a plist from a bytes object. See :func:`load` for an explanation of
the keyword arguments.
@ -88,7 +88,7 @@ This module defines the following functions:
.. versionadded:: 3.4
.. function:: dump(value, fp, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
.. function:: dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
Write *value* to a plist file. *Fp* should be a writable, binary
file object.
@ -116,7 +116,7 @@ This module defines the following functions:
.. versionadded:: 3.4
.. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False)
.. function:: dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)
Return *value* as a plist-formatted bytes object. See
the documentation for :func:`dump` for an explanation of the keyword

View File

@ -665,14 +665,14 @@ The ``errors`` module has the following attributes:
.. data:: codes
A dictionary mapping numeric error codes to their string descriptions.
A dictionary mapping string descriptions to their error codes.
.. versionadded:: 3.2
.. data:: messages
A dictionary mapping string descriptions to their error codes.
A dictionary mapping numeric error codes to their string descriptions.
.. versionadded:: 3.2

View File

@ -135,6 +135,15 @@ Functions for integers
values. Formerly it used a style like ``int(random()*n)`` which could produce
slightly uneven distributions.
.. deprecated:: 3.10
The automatic conversion of non-integer types to equivalent integers is
deprecated. Currently ``randrange(10.0)`` is losslessly converted to
``randrange(10)``. In the future, this will raise a :exc:`TypeError`.
.. deprecated:: 3.10
The exception raised for non-integral values such as ``range(10.5)``
will be changed from :exc:`ValueError` to :exc:`TypeError`.
.. function:: randint(a, b)
Return a random integer *N* such that ``a <= N <= b``. Alias for
@ -142,10 +151,11 @@ Functions for integers
.. function:: getrandbits(k)
Returns a Python integer with *k* random bits. This method is supplied with
the MersenneTwister generator and some other generators may also provide it
as an optional part of the API. When available, :meth:`getrandbits` enables
:meth:`randrange` to handle arbitrarily large ranges.
Returns a non-negative Python integer with *k* random bits. This method
is supplied with the MersenneTwister generator and some other generators
may also provide it as an optional part of the API. When available,
:meth:`getrandbits` enables :meth:`randrange` to handle arbitrarily large
ranges.
.. versionchanged:: 3.9
This method now accepts zero for *k*.

View File

@ -218,7 +218,7 @@ Directory and files operations
copy the file more efficiently. See
:ref:`shutil-platform-dependent-efficient-copy-operations` section.
.. function:: ignore_patterns(\*patterns)
.. function:: ignore_patterns(*patterns)
This factory function creates a function that can be used as a callable for
:func:`copytree`\'s *ignore* argument, ignoring files and directories that

View File

@ -907,11 +907,9 @@ The :mod:`socket` module also offers various network-related services:
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 2-byte swap operation.
.. deprecated:: 3.7
In case *x* does not fit in 16-bit unsigned integer, but does fit in a
positive C int, it is silently truncated to 16-bit unsigned integer.
This silent truncation feature is deprecated, and will raise an
exception in future versions of Python.
.. versionchanged:: 3.10
Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned
integer.
.. function:: htonl(x)
@ -927,11 +925,9 @@ The :mod:`socket` module also offers various network-related services:
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 2-byte swap operation.
.. deprecated:: 3.7
In case *x* does not fit in 16-bit unsigned integer, but does fit in a
positive C int, it is silently truncated to 16-bit unsigned integer.
This silent truncation feature is deprecated, and will raise an
exception in future versions of Python.
.. versionchanged:: 3.10
Raises :exc:`OverflowError` if *x* does not fit in a 16-bit unsigned
integer.
.. function:: inet_aton(ip_string)

View File

@ -198,7 +198,9 @@ Module functions and constants
*detect_types* defaults to 0 (i. e. off, no type detection), you can set it to
any combination of :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` to turn
type detection on.
type detection on. Due to SQLite behaviour, types can't be detected for generated
fields (for example ``max(data)``), even when *detect_types* parameter is set. In
such case, the returned type is :class:`str`.
By default, *check_same_thread* is :const:`True` and only the creating thread may
use the connection. If set :const:`False`, the returned connection may be shared
@ -544,7 +546,7 @@ Connection Objects
con.close()
.. method:: backup(target, *, pages=0, progress=None, name="main", sleep=0.250)
.. method:: backup(target, *, pages=-1, progress=None, name="main", sleep=0.250)
This method makes a backup of a SQLite database even while it's being accessed
by other clients, or concurrently by the same connection. The copy will be

View File

@ -156,10 +156,11 @@ However, for reading convenience, most of the examples show sorted sequences.
.. versionadded:: 3.8
.. function:: harmonic_mean(data)
.. function:: harmonic_mean(data, weights=None)
Return the harmonic mean of *data*, a sequence or iterable of
real-valued numbers.
real-valued numbers. If *weights* is omitted or *None*, then
equal weighting is assumed.
The harmonic mean, sometimes called the subcontrary mean, is the
reciprocal of the arithmetic :func:`mean` of the reciprocals of the
@ -179,17 +180,17 @@ However, for reading convenience, most of the examples show sorted sequences.
>>> harmonic_mean([40, 60])
48.0
Suppose an investor purchases an equal value of shares in each of
three companies, with P/E (price/earning) ratios of 2.5, 3 and 10.
What is the average P/E ratio for the investor's portfolio?
Suppose a car travels 40 km/hr for 5 km, and when traffic clears,
speeds-up to 60 km/hr for the remaining 30 km of the journey. What
is the average speed?
.. doctest::
>>> harmonic_mean([2.5, 3, 10]) # For an equal investment portfolio.
3.6
>>> harmonic_mean([40, 60], weights=[5, 30])
56.0
:exc:`StatisticsError` is raised if *data* is empty, or any element
is less than zero.
:exc:`StatisticsError` is raised if *data* is empty, any element
is less than zero, or if the weighted sum isn't positive.
The current algorithm has an early-out when it encounters a zero
in the input. This means that the subsequent inputs are not tested
@ -197,6 +198,8 @@ However, for reading convenience, most of the examples show sorted sequences.
.. versionadded:: 3.6
.. versionchanged:: 3.8
Added support for *weights*.
.. function:: median(data)

View File

@ -499,7 +499,7 @@ class`. In addition, it provides a few more methods:
.. versionadded:: 3.10
.. method:: int.to_bytes(length, byteorder, \*, signed=False)
.. method:: int.to_bytes(length, byteorder, *, signed=False)
Return an array of bytes representing an integer.
@ -531,7 +531,7 @@ class`. In addition, it provides a few more methods:
.. versionadded:: 3.2
.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False)
.. classmethod:: int.from_bytes(bytes, byteorder, *, signed=False)
Return the integer represented by the given array of bytes.
@ -5353,8 +5353,8 @@ types, where they are relevant. Some of these are not reported by the
.. method:: class.__subclasses__
Each class keeps a list of weak references to its immediate subclasses. This
method returns a list of all those references still alive.
Example::
method returns a list of all those references still alive. The list is in
definition order. Example::
>>> int.__subclasses__()
[<class 'bool'>]

View File

@ -384,10 +384,10 @@ following:
The ``'#'`` option causes the "alternate form" to be used for the
conversion. The alternate form is defined differently for different
types. This option is only valid for integer, float, complex and
Decimal types. For integers, when binary, octal, or hexadecimal output
types. This option is only valid for integer, float and complex
types. For integers, when binary, octal, or hexadecimal output
is used, this option adds the prefix respective ``'0b'``, ``'0o'``, or
``'0x'`` to the output value. For floats, complex and Decimal the
``'0x'`` to the output value. For float and complex the
alternate form causes the result of the conversion to always contain a
decimal-point character, even if no digits follow it. Normally, a
decimal-point character appears in the result of these conversions
@ -476,20 +476,36 @@ with the floating point presentation types listed below (except
``'n'`` and ``None``). When doing so, :func:`float` is used to convert the
integer to a floating point number before formatting.
The available presentation types for floating point and decimal values are:
The available presentation types for :class:`float` and
:class:`~decimal.Decimal` values are:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'e'`` | Exponent notation. Prints the number in scientific |
| | notation using the letter 'e' to indicate the exponent. |
| | The default precision is ``6``. |
| ``'e'`` | Scientific notation. For a given precision ``p``, |
| | formats the number in scientific notation with the |
| | letter 'e' separating the coefficient from the exponent. |
| | The coefficient has one digit before and ``p`` digits |
| | after the decimal point, for a total of ``p + 1`` |
| | significant digits. With no precision given, uses a |
| | precision of ``6`` digits after the decimal point for |
| | :class:`float`, and shows all coefficient digits |
| | for :class:`~decimal.Decimal`. If no digits follow the |
| | decimal point, the decimal point is also removed unless |
| | the ``#`` option is used. |
+---------+----------------------------------------------------------+
| ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an |
| | upper case 'E' as the separator character. |
| ``'E'`` | Scientific notation. Same as ``'e'`` except it uses |
| | an upper case 'E' as the separator character. |
+---------+----------------------------------------------------------+
| ``'f'`` | Fixed-point notation. Displays the number as a |
| | fixed-point number. The default precision is ``6``. |
| ``'f'`` | Fixed-point notation. For a given precision ``p``, |
| | formats the number as a decimal number with exactly |
| | ``p`` digits following the decimal point. With no |
| | precision given, uses a precision of ``6`` digits after |
| | the decimal point for :class:`float`, and uses a |
| | precision large enough to show all coefficient digits |
| | for :class:`~decimal.Decimal`. If no digits follow the |
| | decimal point, the decimal point is also removed unless |
| | the ``#`` option is used. |
+---------+----------------------------------------------------------+
| ``'F'`` | Fixed-point notation. Same as ``'f'``, but converts |
| | ``nan`` to ``NAN`` and ``inf`` to ``INF``. |
@ -498,6 +514,8 @@ The available presentation types for floating point and decimal values are:
| | this rounds the number to ``p`` significant digits and |
| | then formats the result in either fixed-point format |
| | or in scientific notation, depending on its magnitude. |
| | A precision of ``0`` is treated as equivalent to a |
| | precision of ``1``. |
| | |
| | The precise rules are as follows: suppose that the |
| | result formatted with presentation type ``'e'`` and |
@ -512,13 +530,19 @@ The available presentation types for floating point and decimal values are:
| | removed if there are no remaining digits following it, |
| | unless the ``'#'`` option is used. |
| | |
| | With no precision given, uses a precision of ``6`` |
| | significant digits for :class:`float`. For |
| | :class:`~decimal.Decimal`, the coefficient of the result |
| | is formed from the coefficient digits of the value; |
| | scientific notation is used for values smaller than |
| | ``1e-6`` in absolute value and values where the place |
| | value of the least significant digit is larger than 1, |
| | and fixed-point notation is used otherwise. |
| | |
| | Positive and negative infinity, positive and negative |
| | zero, and nans, are formatted as ``inf``, ``-inf``, |
| | ``0``, ``-0`` and ``nan`` respectively, regardless of |
| | the precision. |
| | |
| | A precision of ``0`` is treated as equivalent to a |
| | precision of ``1``. The default precision is ``6``. |
+---------+----------------------------------------------------------+
| ``'G'`` | General format. Same as ``'g'`` except switches to |
| | ``'E'`` if the number gets too large. The |
@ -531,12 +555,18 @@ The available presentation types for floating point and decimal values are:
| ``'%'`` | Percentage. Multiplies the number by 100 and displays |
| | in fixed (``'f'``) format, followed by a percent sign. |
+---------+----------------------------------------------------------+
| None | Similar to ``'g'``, except that fixed-point notation, |
| | when used, has at least one digit past the decimal point.|
| | The default precision is as high as needed to represent |
| | the particular value. The overall effect is to match the |
| | output of :func:`str` as altered by the other format |
| | modifiers. |
| None | For :class:`float` this is the same as ``'g'``, except |
| | that when fixed-point notation is used to format the |
| | result, it always includes at least one digit past the |
| | decimal point. The precision used is as large as needed |
| | to represent the given value faithfully. |
| | |
| | For :class:`~decimal.Decimal`, this is the same as |
| | either ``'g'`` or ``'G'`` depending on the value of |
| | ``context.capitals`` for the current decimal context. |
| | |
| | The overall effect is to match the output of :func:`str` |
| | as altered by the other format modifiers. |
+---------+----------------------------------------------------------+

View File

@ -339,7 +339,7 @@ functions.
stderr=None, preexec_fn=None, close_fds=True, shell=False, \
cwd=None, env=None, universal_newlines=None, \
startupinfo=None, creationflags=0, restore_signals=True, \
start_new_session=False, pass_fds=(), \*, group=None, \
start_new_session=False, pass_fds=(), *, group=None, \
extra_groups=None, user=None, umask=-1, \
encoding=None, errors=None, text=None, pipesize=-1)
@ -1187,8 +1187,9 @@ calls these functions.
The arguments shown above are merely some common ones.
The full function signature is largely the same as that of :func:`run` -
most arguments are passed directly through to that interface.
However, explicitly passing ``input=None`` to inherit the parent's
standard input file handle is not supported.
One API deviation from :func:`run` behavior exists: passing ``input=None``
will behave the same as ``input=b''`` (or ``input=''``, depending on other
arguments) rather than using the parent's standard input file handle.
By default, this function will return the data as encoded bytes. The actual
encoding of the output data may depend on the command being invoked, so the
@ -1281,7 +1282,7 @@ be used directly:
becomes::
output=check_output("dmesg | grep hda", shell=True)
output = check_output("dmesg | grep hda", shell=True)
Replacing :func:`os.system`

View File

@ -160,6 +160,8 @@ Examining Symbol Tables
Return ``True`` if the symbol is annotated.
.. versionadded:: 3.6
.. method:: is_free()
Return ``True`` if the symbol is referenced in its block, but not assigned

View File

@ -32,7 +32,7 @@ can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
Notice that on Windows, it's a much smaller set.
.. function:: get_config_vars(\*args)
.. function:: get_config_vars(*args)
With no arguments, return a dictionary of all configuration variables
relevant for the current platform.

View File

@ -37,7 +37,7 @@ Some facts and figures:
Added support for :mod:`lzma` compression.
.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs)
.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)
Return a :class:`TarFile` object for the pathname *name*. For detailed
information on :class:`TarFile` objects and the keyword arguments that are

View File

@ -453,7 +453,7 @@ The :mod:`test.support` module defines the following functions:
Define match test with regular expression *patterns*.
.. function:: run_unittest(\*classes)
.. function:: run_unittest(*classes)
Execute :class:`unittest.TestCase` subclasses passed to the function. The
function scans the classes for methods starting with the prefix ``test_``
@ -1599,7 +1599,7 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes
.. versionadded:: 3.8
.. function:: check_warnings(\*filters, quiet=True)
.. function:: check_warnings(*filters, quiet=True)
A convenience wrapper for :func:`warnings.catch_warnings()` that makes it
easier to test that a warning was correctly raised. It is approximately

View File

@ -91,6 +91,9 @@ The different font weights and slants are:
Return the names of defined fonts.
.. function:: nametofont(name)
.. function:: nametofont(name, root=None)
Return a :class:`Font` representation of a tk named font.
.. versionchanged:: 3.10
The *root* parameter was added.

View File

@ -280,6 +280,10 @@ Standard names are defined for the following types:
.. versionadded:: 3.9
.. versionchanged:: 3.9.2
This type can now be subclassed.
.. data:: Union
The type of :ref:`union type expressions<types-union>`.

View File

@ -262,9 +262,10 @@ the *new_callable* argument to :func:`patch`.
this is a new Mock (created on first access). See the
:attr:`return_value` attribute.
* *unsafe*: By default if any attribute starts with *assert* or
*assret* will raise an :exc:`AttributeError`. Passing ``unsafe=True``
will allow access to these attributes.
* *unsafe*: By default, accessing any attribute with name starting with
*assert*, *assret*, *asert*, *aseert* or *assrt* will raise an
:exc:`AttributeError`. Passing ``unsafe=True`` will allow access to
these attributes.
.. versionadded:: 3.5

View File

@ -491,7 +491,7 @@ Available Functions
Available Context Managers
--------------------------
.. class:: catch_warnings(\*, record=False, module=None)
.. class:: catch_warnings(*, record=False, module=None)
A context manager that copies and, upon exit, restores the warnings filter
and the :func:`showwarning` function.

View File

@ -791,7 +791,7 @@ integer handle, and also disconnect the Windows handle from the handle object.
.. method:: PyHKEY.__enter__()
PyHKEY.__exit__(\*exc_info)
PyHKEY.__exit__(*exc_info)
The HKEY object implements :meth:`~object.__enter__` and
:meth:`~object.__exit__` and thus supports the context protocol for the

View File

@ -174,7 +174,7 @@ module documentation. This section lists the differences between the API and
The :meth:`toxml` method now preserves the attribute order specified
by the user.
.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None, \
.. method:: Node.toprettyxml(indent="\t", newl="\n", encoding=None, \
standalone=None)
Return a pretty-printed version of the document. *indent* specifies the

View File

@ -483,7 +483,7 @@ Path Objects
Path objects expose the following features of :mod:`pathlib.Path`
objects:
Path objects are traversable using the ``/`` operator.
Path objects are traversable using the ``/`` operator or ``joinpath``.
.. attribute:: Path.name
@ -532,6 +532,19 @@ Path objects are traversable using the ``/`` operator.
Read the current file as bytes.
.. method:: Path.joinpath(*other)
Return a new Path object with each of the *other* arguments
joined. The following are equivalent::
>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'
.. versionchanged:: 3.10
Prior to 3.10, ``joinpath`` was undocumented and accepted
exactly one parameter.
.. _pyzipfile-objects:

View File

@ -121,7 +121,7 @@ zipimporter Objects
.. method:: get_code(fullname)
Return the code object for the specified module. Raise
:exc:`ZipImportError` if the module couldn't be found.
:exc:`ZipImportError` if the module couldn't be imported.
.. method:: get_data(pathname)
@ -137,7 +137,7 @@ zipimporter Objects
Return the value ``__file__`` would be set to if the specified module
was imported. Raise :exc:`ZipImportError` if the module couldn't be
found.
imported.
.. versionadded:: 3.1
@ -159,14 +159,13 @@ zipimporter Objects
.. method:: load_module(fullname)
Load the module specified by *fullname*. *fullname* must be the fully
qualified (dotted) module name. It returns the imported module, or raises
:exc:`ZipImportError` if it wasn't found.
qualified (dotted) module name. Returns the imported module on success,
raises :exc:`ZipImportError` on failure.
.. deprecated:: 3.10
Use :meth:`exec_module` instead.
.. attribute:: archive
The file name of the importer's associated ZIP file, without a possible

View File

@ -254,7 +254,8 @@ present, must be last; it matches any exception. For an except clause with an
expression, that expression is evaluated, and the clause matches the exception
if the resulting object is "compatible" with the exception. An object is
compatible with an exception if it is the class or a base class of the exception
object or a tuple containing an item compatible with the exception.
object, or a tuple containing an item that is the class or a base class of
the exception object.
If no except clause matches the exception, the search for an exception handler
continues in the surrounding code and on the invocation stack. [#]_
@ -301,9 +302,27 @@ Before an except clause's suite is executed, details about the exception are
stored in the :mod:`sys` module and can be accessed via :func:`sys.exc_info`.
:func:`sys.exc_info` returns a 3-tuple consisting of the exception class, the
exception instance and a traceback object (see section :ref:`types`) identifying
the point in the program where the exception occurred. :func:`sys.exc_info`
values are restored to their previous values (before the call) when returning
from a function that handled an exception.
the point in the program where the exception occurred. The details about the
exception accessed via :func:`sys.exc_info` are restored to their previous values
when leaving an exception handler::
>>> print(sys.exc_info())
(None, None, None)
>>> try:
... raise TypeError
... except:
... print(sys.exc_info())
... try:
... raise ValueError
... except:
... print(sys.exc_info())
... print(sys.exc_info())
...
(<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
(<class 'ValueError'>, ValueError(), <traceback object at 0x10efad040>)
(<class 'TypeError'>, TypeError(), <traceback object at 0x10efad080>)
>>> print(sys.exc_info())
(None, None, None)
.. index::
keyword: else
@ -796,12 +815,12 @@ The :keyword:`!async for` statement
.. productionlist:: python-grammar
async_for_stmt: "async" `for_stmt`
An :term:`asynchronous iterable` is able to call asynchronous code in its
*iter* implementation, and :term:`asynchronous iterator` can call asynchronous
code in its *next* method.
An :term:`asynchronous iterable` provides an ``__aiter__`` method that directly
returns an :term:`asynchronous iterator`, which can call asynchronous code in
its ``__anext__`` method.
The ``async for`` statement allows convenient iteration over asynchronous
iterators.
iterables.
The following code::

View File

@ -217,7 +217,6 @@ Ellipsis
There are two types of integers:
Integers (:class:`int`)
These represent numbers in an unlimited range, subject to available (virtual)
memory only. For the purpose of shift and mask operations, a binary
representation is assumed, and negative numbers are represented in a variant of

View File

@ -13,7 +13,8 @@ In particular, ``&`` followed by a symbol, token or parenthesized
group indicates a positive lookahead (i.e., is required to match but
not consumed), while ``!`` indicates a negative lookahead (i.e., is
required _not_ to match). We use the ``|`` separator to mean PEG's
"ordered choice" (written as ``/`` in traditional PEG grammars).
"ordered choice" (written as ``/`` in traditional PEG grammars). See
:pep:`617` for more details on the grammar's syntax.
.. literalinclude:: ../../Grammar/python.gram
:language: peg

View File

@ -950,7 +950,7 @@ Names listed in a :keyword:`global` statement must not be used in the same code
block textually preceding that :keyword:`!global` statement.
Names listed in a :keyword:`global` statement must not be defined as formal
parameters or in a :keyword:`for` loop control target, :keyword:`class`
parameters, or as targets in :keyword:`with` statements or :keyword:`except` clauses, or in a :keyword:`for` target list, :keyword:`class`
definition, function definition, :keyword:`import` statement, or variable
annotation.

View File

@ -0,0 +1,57 @@
# -*- coding: utf-8 -*-
"""
glossary_search.py
~~~~~~~~~~~~~~~~
Feature search results for glossary items prominently.
:license: Python license.
"""
from os import path
from sphinx.addnodes import glossary
from sphinx.util import logging
from docutils.nodes import definition_list_item
import json
logger = logging.getLogger(__name__)
def process_glossary_nodes(app, doctree, fromdocname):
if app.builder.format != 'html':
return
terms = {}
for node in doctree.traverse(glossary):
for glossary_item in node.traverse(definition_list_item):
term = glossary_item[0].astext().lower()
definition = glossary_item[1]
rendered = app.builder.render_partial(definition)
terms[term] = {
'title': glossary_item[0].astext(),
'body': rendered['html_body']
}
if hasattr(app.env, 'glossary_terms'):
app.env.glossary_terms.update(terms)
else:
app.env.glossary_terms = terms
def on_build_finish(app, exc):
if not hasattr(app.env, 'glossary_terms'):
return
if not app.env.glossary_terms:
return
logger.info('Writing glossary.json', color='green')
with open(path.join(app.outdir, '_static', 'glossary.json'), 'w') as f:
json.dump(app.env.glossary_terms, f)
def setup(app):
app.connect('doctree-resolved', process_glossary_nodes)
app.connect('build-finished', on_build_finish)
return {'version': '0.1', 'parallel_read_safe': True}

View File

@ -394,6 +394,11 @@ class DeprecatedRemoved(Directive):
translatable=False)
node.append(para)
env = self.state.document.settings.env
# deprecated pre-Sphinx-2 method
if hasattr(env, 'note_versionchange'):
env.note_versionchange('deprecated', version[0], node, self.lineno)
# new method
else:
env.get_domain('changeset').note_changeset(node)
return [node] + messages

View File

@ -13,6 +13,7 @@ import os
import re
import sys
import getopt
from string import ascii_letters
from os.path import join, splitext, abspath, exists
from collections import defaultdict
@ -128,6 +129,81 @@ def check_leaked_markup(fn, lines):
yield lno+1, 'possibly leaked markup: %r' % line
def hide_literal_blocks(lines):
"""Tool to remove literal blocks from given lines.
It yields empty lines in place of blocks, so line numbers are
still meaningful.
"""
in_block = False
for line in lines:
if line.endswith("::\n"):
in_block = True
elif in_block:
if line == "\n" or line.startswith(" "):
line = "\n"
else:
in_block = False
yield line
def type_of_explicit_markup(line):
if re.match(fr'\.\. {all_directives}::', line):
return 'directive'
if re.match(r'\.\. \[[0-9]+\] ', line):
return 'footnote'
if re.match(r'\.\. \[[^\]]+\] ', line):
return 'citation'
if re.match(r'\.\. _.*[^_]: ', line):
return 'target'
if re.match(r'\.\. \|[^\|]*\| ', line):
return 'substitution_definition'
return 'comment'
def hide_comments(lines):
"""Tool to remove comments from given lines.
It yields empty lines in place of comments, so line numbers are
still meaningfull.
"""
in_multiline_comment = False
for line in lines:
if line == "..\n":
in_multiline_comment = True
elif in_multiline_comment:
if line == "\n" or line.startswith(" "):
line = "\n"
else:
in_multiline_comment = False
if line.startswith(".. ") and type_of_explicit_markup(line) == 'comment':
line = "\n"
yield line
@checker(".rst", severity=2)
def check_missing_surrogate_space_on_plural(fn, lines):
r"""Check for missing 'backslash-space' between a code sample a letter.
Good: ``Point``\ s
Bad: ``Point``s
"""
in_code_sample = False
check_next_one = False
for lno, line in enumerate(hide_comments(hide_literal_blocks(lines))):
tokens = line.split("``")
for token_no, token in enumerate(tokens):
if check_next_one:
if token[0] in ascii_letters:
yield lno + 1, f"Missing backslash-space between code sample and {token!r}."
check_next_one = False
if token_no == len(tokens) - 1:
continue
if in_code_sample:
check_next_one = True
in_code_sample = not in_code_sample
def main(argv):
usage = '''\
Usage: %s [-v] [-f] [-s sev] [-i path]* [path]

View File

@ -0,0 +1,48 @@
{% extends "!search.html" %}
{% block extrahead %}
{{ super() }}
<script type="text/javascript">
var GLOSSARY_PAGE = 'glossary.html';
jQuery(function() {
$.getJSON("_static/glossary.json", function(glossary) {
var RESULT_TEMPLATE = '<div style="display: none" class="admonition seealso" id="glossary-result">' +
' <p class="topic-title">' +
' <a class="glossary-title" href="#"></a>' +
' </p>' +
' <div class="glossary-body"></div>' +
'</div>';
$("#search-results").prepend(RESULT_TEMPLATE);
var params = $.getQueryParameters();
if (params.q) {
var search_param = params.q[0].toLowerCase();
var glossary_item = glossary[search_param];
if (glossary_item) {
var resultDiv = $("#glossary-result");
// set up the title text with a link to the glossary page
resultDiv.find(".glossary-title").text('Glossary: ' + glossary_item.title);
var link_target = search_param.replace(/ /g, '-');
resultDiv.find(".glossary-title").attr(
'href', GLOSSARY_PAGE + '#term-' + link_target
);
// rewrite any anchor links (to other glossary terms)
// to have a full reference to the glossary page
var body = $(glossary_item.body).children();
body.find("a[href^='#']").each(function() {
var current_url = $(this).attr('href');
$(this).attr('href', GLOSSARY_PAGE + current_url);
});
resultDiv.find(".glossary-body").html(body);
resultDiv.show();
} else {
$("#glossary-result").hide('');
}
}
});
});
</script>
{% endblock %}

View File

@ -78,7 +78,7 @@ objects:
Return the number of times *x* appears in the list.
.. method:: list.sort(key=None, reverse=False)
.. method:: list.sort(*, key=None, reverse=False)
:noindex:
Sort the items of the list in place (the arguments can be used for sort

View File

@ -281,17 +281,17 @@ chaining exceptions. For example::
This can be useful when you are transforming exceptions. For example::
>>> def func():
... raise IOError
... raise ConnectionError
...
>>> try:
... func()
... except IOError as exc:
... except ConnectionError as exc:
... raise RuntimeError('Failed to open database') from exc
...
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
File "<stdin>", line 2, in func
OSError
ConnectionError
<BLANKLINE>
The above exception was the direct cause of the following exception:
<BLANKLINE>
@ -300,7 +300,7 @@ This can be useful when you are transforming exceptions. For example::
RuntimeError: Failed to open database
Exception chaining happens automatically when an exception is raised inside an
:keyword:`except` or :keyword:`finally` section. Exception chaining can be
:keyword:`except` or :keyword:`finally` section. This can be
disabled by using ``from None`` idiom:
>>> try:

View File

@ -329,11 +329,16 @@ equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
If you're not using the :keyword:`with` keyword, then you should call
``f.close()`` to close the file and immediately free up any system
resources used by it. If you don't explicitly close a file, Python's
garbage collector will eventually destroy the object and close the
open file for you, but the file may stay open for a while. Another
risk is that different Python implementations will do this clean-up at
different times.
resources used by it.
.. warning::
Calling ``f.write()`` without using the :keyword:`!with` keyword or calling
``f.close()`` **might** result in the arguments
of ``f.write()`` not being completely written to the disk, even if the
program exits successfully.
..
See also https://bugs.python.org/issue17852
After a file object is closed, either by a :keyword:`with` statement
or by calling ``f.close()``, attempts to use the file object will

View File

@ -23,8 +23,8 @@ available for application-local distributions.
As specified in :pep:`11`, a Python release only supports a Windows platform
while Microsoft considers the platform under extended support. This means that
Python |version| supports Windows Vista and newer. If you require Windows XP
support then please install Python 3.4.
Python |version| supports Windows 8.1 and newer. If you require Windows 7
support, please install Python 3.8.
There are a number of different installers available for Windows, each with
certain benefits and downsides.

View File

@ -179,6 +179,21 @@ codecs
Add a :func:`codecs.unregister` function to unregister a codec search function.
(Contributed by Hai Shi in :issue:`41842`.)
collections.abc
---------------
The ``__args__`` of the :ref:`parameterized generic <types-genericalias>` for
:class:`collections.abc.Callable` are now consistent with :data:`typing.Callable`.
:class:`collections.abc.Callable` generic now flattens type parameters, similar
to what :data:`typing.Callable` currently does. This means that
``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of
``(int, str, str)``; previously this was ``([int, str], str)``. To allow this
change, :class:`types.GenericAlias` can now be subclassed, and a subclass will
be returned when subscripting the :class:`collections.abc.Callable` type. Note
that a :exc:`TypeError` may be raised for invalid forms of parameterizing
:class:`collections.abc.Callable` which may have passed silently in Python 3.9.
(Contributed by Ken Jin in :issue:`42195`.)
contextlib
----------
@ -223,6 +238,11 @@ inspect
When a module does not define ``__loader__``, fall back to ``__spec__.loader``.
(Contributed by Brett Cannon in :issue:`42133`.)
Added *globalns* and *localns* parameters in :func:`~inspect.signature` and
:meth:`inspect.Signature.from_callable` to retrieve the annotations in given
local and global namespaces.
(Contributed by Batuhan Taskaya in :issue:`41960`.)
linecache
---------
@ -254,6 +274,14 @@ Added negative indexing support to :attr:`PurePath.parents
<pathlib.PurePath.parents>`.
(Contributed by Yaroslav Pankovych in :issue:`21041`)
platform
--------
Added :func:`platform.freedesktop_os_release()` to retrieve operation system
identification from `freedesktop.org os-release
<https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file.
(Contributed by Christian Heimes in :issue:`28468`)
py_compile
----------
@ -386,7 +414,8 @@ Optimizations
with ``gcc`` by up to 30%. See `this article
<https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_
for more details. (Contributed by Victor Stinner and Pablo Galindo in
:issue:`38980`)
:issue:`38980`.)
* Function parameters and their annotations are no longer computed at runtime,
but rather at compilation time. They are stored as a tuple of strings at the
@ -413,6 +442,21 @@ Deprecated
as appropriate to help identify code which needs updating during
this transition.
* The various ``load_module()`` methods of :mod:`importlib` have been
documented as deprecated since Python 3.6, but will now also trigger
a :exc:`DeprecationWarning`. Use
:meth:`~importlib.abc.Loader.exec_module` instead.
(Contributed by Brett Cannon in :issue:`26131`.)
* :meth:`zimport.zipimporter.load_module` has been deprecated in
preference for :meth:`~zipimport.zipimporter.exec_module`.
(Contributed by Brett Cannon in :issue:`26131`.)
* The use of :meth:`~importlib.abc.Loader.load_module` by the import
system now triggers an :exc:`ImportWarning` as
:meth:`~importlib.abc.Loader.exec_module` is preferred.
(Contributed by Brett Cannon in :issue:`26131`.)
* ``sqlite3.OptimizedUnicode`` has been undocumented and obsolete since Python
3.3, when it was made an alias to :class:`str`. It is now deprecated,
scheduled for removal in Python 3.12.
@ -456,6 +500,11 @@ Removed
into their code.
(Contributed by Dong-hee Na and Terry J. Reedy in :issue:`42299`.)
* Removed the :c:func:`PyModule_GetWarningsModule` function that was useless
now due to the _warnings module was converted to a builtin module in 2.6.
(Contributed by Hai Shi in :issue:`42599`.)
Porting to Python 3.10
======================
@ -472,6 +521,28 @@ Changes in the Python API
have been renamed to *exc*.
(Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.)
* :mod:`atexit`: At Python exit, if a callback registered with
:func:`atexit.register` fails, its exception is now logged. Previously, only
some exceptions were logged, and the last exception was always silently
ignored.
(Contributed by Victor Stinner in :issue:`42639`.)
* :class:`collections.abc.Callable` generic now flattens type parameters, similar
to what :data:`typing.Callable` currently does. This means that
``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of
``(int, str, str)``; previously this was ``([int, str], str)``. Code which
accesses the arguments via :func:`typing.get_args` or ``__args__`` need to account
for this change. Furthermore, :exc:`TypeError` may be raised for invalid forms
of parameterizing :class:`collections.abc.Callable` which may have passed
silently in Python 3.9.
(Contributed by Ken Jin in :issue:`42195`.)
* :meth:`socket.htons` and :meth:`socket.ntohs` now raise :exc:`OverflowError`
instead of :exc:`DeprecationWarning` if the given parameter will not fit in
a 16-bit unsigned integer.
(Contributed by Erlend E. Aasland in :issue:`42393`.)
CPython bytecode changes
========================
@ -490,6 +561,12 @@ Build Changes
* :mod:`sqlite3` requires SQLite 3.7.3 or higher.
(Contributed by Sergey Fedoseev and Erlend E. Aasland :issue:`40744`.)
* The :mod:`atexit` module must now always be built as a built-in module.
(Contributed by Victor Stinner in :issue:`42639`.)
* Added ``--disable-test-modules`` option to the ``configure`` script:
don't build nor install test modules.
(Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in :issue:`27640`.)
C API Changes
@ -587,6 +664,13 @@ Porting to Python 3.10
:ref:`Python Path Configuration. <init-path-config>`.
(Contributed by Victor Stinner in :issue:`42260`.)
* :c:func:`PyList_SET_ITEM`, :c:func:`PyTuple_SET_ITEM` and
:c:func:`PyCell_SET` macros can no longer be used as l-value or r-value.
For example, ``x = PyList_SET_ITEM(a, b, c)`` and
``PyList_SET_ITEM(a, b, c) = x`` now fail with a compiler error. It prevents
bugs like ``if (PyList_SET_ITEM (a, b, c) < 0) ...`` test.
(Contributed by Zackery Spytz and Victor Stinner in :issue:`30459`.)
Deprecated
----------

View File

@ -2113,9 +2113,6 @@ Changes in the C API
(Contributed by Antoine Pitrou in :issue:`32388`.)
* The :c:func:`PyCode_New` has a new parameter in the second position (*posonlyargcount*)
to support :pep:`570`, indicating the number of positional-only arguments.
* The functions :c:func:`PyNode_AddChild` and :c:func:`PyParser_AddToken` now accept
two additional ``int`` arguments *end_lineno* and *end_col_offset*.

View File

@ -1483,3 +1483,36 @@ and to match the behavior of static type checkers specified in the PEP.
TypeError: unhashable type: 'set'
(Contributed by Yurii Karabas in :issue:`42345`.)
macOS 11.0 (Big Sur) and Apple Silicon Mac support
--------------------------------------------------
As of 3.9.1, Python now fully supports building and running on macOS 11.0
(Big Sur) and on Apple Silicon Macs (based on the ``ARM64`` architecture).
A new universal build variant, ``universal2``, is now available to natively
support both ``ARM64`` and ``Intel 64`` in one set of executables. Binaries
can also now be built on current versions of macOS to be deployed on a range
of older macOS versions (tested to 10.9) while making some newer OS
functions and options conditionally available based on the operating system
version in use at runtime ("weaklinking").
(Contributed by Ronald Oussoren and Lawrence D'Anna in :issue:`41100`.)
Notable changes in Python 3.9.2
===============================
collections.abc
---------------
:class:`collections.abc.Callable` generic now flattens type parameters, similar
to what :data:`typing.Callable` currently does. This means that
``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of
``(int, str, str)``; previously this was ``([int, str], str)``. To allow this
change, :class:`types.GenericAlias` can now be subclassed, and a subclass will
be returned when subscripting the :class:`collections.abc.Callable` type.
Code which accesses the arguments via :func:`typing.get_args` or ``__args__``
need to account for this change. A :exc:`DeprecationWarning` may be emitted for
invalid forms of parameterizing :class:`collections.abc.Callable` which may have
passed silently in Python 3.9.1. This :exc:`DeprecationWarning` will
become a :exc:`TypeError` in Python 3.10.
(Contributed by Ken Jin in :issue:`42195`.)

View File

@ -52,18 +52,18 @@ type_expressions[asdl_expr_seq*]:
| a[asdl_expr_seq*]=','.expression+ {a}
statements[asdl_stmt_seq*]: a=statement+ { (asdl_stmt_seq*)_PyPegen_seq_flatten(p, a) }
statement[asdl_stmt_seq*]: a=compound_stmt { (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) } | a[asdl_stmt_seq*]=simple_stmt { a }
statement[asdl_stmt_seq*]: a=compound_stmt { (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) } | a[asdl_stmt_seq*]=simple_stmts { a }
statement_newline[asdl_stmt_seq*]:
| a=compound_stmt NEWLINE { (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) }
| simple_stmt
| simple_stmts
| NEWLINE { (asdl_stmt_seq*)_PyPegen_singleton_seq(p, CHECK(stmt_ty, _Py_Pass(EXTRA))) }
| ENDMARKER { _PyPegen_interactive_exit(p) }
simple_stmt[asdl_stmt_seq*]:
| a=small_stmt !';' NEWLINE { (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) } # Not needed, there for speedup
| a[asdl_stmt_seq*]=';'.small_stmt+ [';'] NEWLINE { a }
simple_stmts[asdl_stmt_seq*]:
| a=simple_stmt !';' NEWLINE { (asdl_stmt_seq*)_PyPegen_singleton_seq(p, a) } # Not needed, there for speedup
| a[asdl_stmt_seq*]=';'.simple_stmt+ [';'] NEWLINE { a }
# NOTE: assignment MUST precede expression, else parsing a simple assignment
# will throw a SyntaxError.
small_stmt[stmt_ty] (memo):
simple_stmt[stmt_ty] (memo):
| assignment
| e=star_expressions { _Py_Expr(e, EXTRA) }
| &'return' return_stmt
@ -308,7 +308,7 @@ class_def_raw[stmt_ty]:
block[asdl_stmt_seq*] (memo):
| NEWLINE INDENT a=statements DEDENT { a }
| simple_stmt
| simple_stmts
| invalid_block
star_expressions[expr_ty]:
@ -646,7 +646,7 @@ invalid_arguments:
RAISE_SYNTAX_ERROR_KNOWN_LOCATION(a, "Generator expression must be parenthesized") }
| a=args ',' args { _PyPegen_arguments_parsing_error(p, a) }
invalid_kwarg:
| a=expression '=' {
| expression a='=' {
RAISE_SYNTAX_ERROR_KNOWN_LOCATION(
a, "expression cannot contain assignment, perhaps you meant \"==\"?") }
invalid_named_expression:

View File

@ -1,5 +1,5 @@
/* Bytes (String) object interface */
/* Bytes object interface */
#ifndef Py_BYTESOBJECT_H
#define Py_BYTESOBJECT_H
@ -10,23 +10,20 @@ extern "C" {
#include <stdarg.h>
/*
Type PyBytesObject represents a character string. An extra zero byte is
Type PyBytesObject represents a byte string. An extra zero byte is
reserved at the end to ensure it is zero-terminated, but a size is
present so strings with null bytes in them can be represented. This
is an immutable object type.
There are functions to create new string objects, to test
an object for string-ness, and to get the
string value. The latter function returns a null pointer
There are functions to create new bytes objects, to test
an object for bytes-ness, and to get the
byte string value. The latter function returns a null pointer
if the object is not of the proper type.
There is a variant that takes an explicit size as well as a
variant that assumes a zero-terminated string. Note that none of the
functions should be applied to nil objects.
functions should be applied to NULL pointer.
*/
/* Caching the hash (ob_shash) saves recalculation of a string's hash value.
This significantly speeds up dict lookups. */
PyAPI_DATA(PyTypeObject) PyBytes_Type;
PyAPI_DATA(PyTypeObject) PyBytesIter_Type;
@ -50,26 +47,16 @@ PyAPI_FUNC(PyObject *) PyBytes_DecodeEscape(const char *, Py_ssize_t,
const char *, Py_ssize_t,
const char *);
/* Provides access to the internal data buffer and size of a string
object or the default encoded version of a Unicode object. Passing
NULL as *len parameter will force the string buffer to be
0-terminated (passing a string with embedded NULL characters will
/* Provides access to the internal data buffer and size of a bytes object.
Passing NULL as len parameter will force the string buffer to be
0-terminated (passing a string with embedded NUL characters will
cause an exception). */
PyAPI_FUNC(int) PyBytes_AsStringAndSize(
PyObject *obj, /* string or Unicode object */
PyObject *obj, /* bytes object */
char **s, /* pointer to buffer variable */
Py_ssize_t *len /* pointer to length variable or NULL
(only possible for 0-terminated
strings) */
Py_ssize_t *len /* pointer to length variable or NULL */
);
/* Flags used by string formatting */
#define F_LJUST (1<<0)
#define F_SIGN (1<<1)
#define F_BLANK (1<<2)
#define F_ALT (1<<3)
#define F_ZERO (1<<4)
#ifndef Py_LIMITED_API
# define Py_CPYTHON_BYTESOBJECT_H
# include "cpython/bytesobject.h"

View File

@ -20,7 +20,7 @@ PyAPI_FUNC(PyObject *) PyCell_Get(PyObject *);
PyAPI_FUNC(int) PyCell_Set(PyObject *, PyObject *);
#define PyCell_GET(op) (((PyCellObject *)(op))->ob_ref)
#define PyCell_SET(op, v) (((PyCellObject *)(op))->ob_ref = v)
#define PyCell_SET(op, v) ((void)(((PyCellObject *)(op))->ob_ref = v))
#ifdef __cplusplus
}

View File

@ -63,7 +63,7 @@ PyVectorcall_Function(PyObject *callable)
{
PyTypeObject *tp;
Py_ssize_t offset;
vectorcallfunc *ptr;
vectorcallfunc ptr;
assert(callable != NULL);
tp = Py_TYPE(callable);
@ -73,8 +73,8 @@ PyVectorcall_Function(PyObject *callable)
assert(PyCallable_Check(callable));
offset = tp->tp_vectorcall_offset;
assert(offset > 0);
ptr = (vectorcallfunc *)(((char *)callable) + offset);
return *ptr;
memcpy(&ptr, (char *) callable + offset, sizeof(ptr));
return ptr;
}
/* Call the callable object 'callable' with the "vectorcall" calling

View File

@ -10,7 +10,7 @@ typedef struct {
/* Invariants:
* ob_sval contains space for 'ob_size+1' elements.
* ob_sval[ob_size] == 0.
* ob_shash is the hash of the string or -1 if not computed yet.
* ob_shash is the hash of the byte string or -1 if not computed yet.
*/
} PyBytesObject;

Some files were not shown because too many files have changed in this diff Show More