gh-106149: fix comment on stackdepth of generators (#107321)

Docs: Argument Clinic: Restructure "Basic concepts and usage" (#106981)

Split "Basic concepts and usage" into:

- Reference
  - Terminology
  - CLI reference

- Background
  - Basic concepts

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

Docs: Remove the numbered steps from the Argument Clinic tutorial (#107203)

Instead, order the tutorial as one body of prose, making it easier to
align the tutorial according to Diátaxis principles.

gh-104050: Argument clinic: Annotate `str_converter_key()` (#107294)

gh-104050: Argument clinic: Complete `get_destination_buffer` annotations (#107293)

gh-105002: [pathlib] Fix relative_to with walk_up=True using ".." (#107014)

It makes sense to raise an Error because ".." can not
be resolved and the current working directory is unknown.

gh-107091: Fix some uses of :c:type: role (GH-107138)

gh-107091: Fix some uses of :c:member: role (GH-107129)

Document that `os.link()` is not available on Emscripten (GH-104822)

gh-107298: Fix doc references to undocumented modules (#107300)

Update also Doc/tools/.nitignore.

gh-106948: Update documentation nitpick_ignore for c:identifer domain (#107295)

Update the nitpick_ignore of the documentation configuration to fix
Sphinx warnings about standard C types when declaring functions with
the "c:function" markups.

Copy standard C types declared in the "c:type" domain to the
"c:identifier" domain, since "c:function" markup looks for types in
the "c:identifier" domain.

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

gh-107015: Remove async_hacks from the tokenizer (#107018)

gh-106149: Simplify stack depth calculation. Replace asserts by exceptions. (#107255)

gh-104683: Argument Clinic: Make most arguments to `Class` and `Function` required (#107289)

gh-104050: Argument clinic: improve typing around `parse_arg()` methods (#107288)

gh-103735: Tkinter: remove handling for uninteresting "procbody" Tcl value type (GH-103736)

gh-106368: Increase Argument Clinic CLI test coverage (#107277)

gh-104050: Argument clinic: annotate `post_parsing()` and `cleanup()` (#107225)

gh-106939: document ShareableList nul-strip quirk. (#107266)

* gh-106939: document ShareableList nul-strip quirk.
* Mention the `int` size constraint.

gh-104050: Argument clinic: more misc typing improvements (#107264)

gh-106185: Deduplicate `CPythonTracebackErrorCaretTests` in `test_traceback` (GH-106187)

gh-107082: Fix instruction size computation for ENTER_EXECUTOR (#107256)

Co-authored-by: Victor Stinner <vstinner@python.org>

gh-107226: PyModule_AddObjectRef() should only be in the limited API 3.10 (GH-107227)

gh-106350: Tkinter: do not ignore return value of `mp_init()` (GH-106351)

gh-106004: PyDict_GetItemRef() should only be in the limited API 3.13 (GH-107229)

gh-107249: Implement Py_UNUSED() for MSVC (#107250)

Fix warnings C4100 in Py_UNUSED() when Python is built with "cl /W4".

Example with this function included by Python.h:

    static inline unsigned int
    PyUnicode_IS_READY(PyObject* Py_UNUSED(op))
    { return 1; }

Without this change, building a C program with "cl /W4" which just
includes Python.h emits the warning:

    Include\cpython/unicodeobject.h(199):
    warning C4100: '_unused_op': unreferenced formal parameter

This change fix this warning.

gh-106739: Add `rtype_cache` to `warnings.warn` message when leaked objects found (#106740)

Adding the `rtype_cache` to the `warnings.warn` message improves the
previous, somewhat vague message from

```
/Users/username/cpython/Lib/multiprocessing/resource_tracker.py:224: UserWarning: resource_tracker: There appear to be 6 leaked semaphore objects to clean up at shutdown
```

to

```
/Users/username/cpython/Lib/multiprocessing/resource_tracker.py:224: UserWarning: resource_tracker: There appear to be 6 leaked semaphore objects to clean up at shutdown: {'/mp-yor5cvj8', '/mp-10jx8eqr', '/mp-eobsx9tt', '/mp-0lml23vl', '/mp-9dgtsa_m', '/mp-frntyv4s'}
```

---------

Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>

Remove unused internal _PyImport_GetModuleId() function (#107235)

gh-105059: Fix MSCV compiler warning on PyObject union (#107239)

Use pragma to ignore the MSCV compiler warning on the PyObject
nameless union.

gh-106869: Use new PyMemberDef constant names (#106871)

* Remove '#include "structmember.h"'.
* If needed, add <stddef.h> to get offsetof() function.
* Update Parser/asdl_c.py to regenerate Python/Python-ast.c.
* Replace:

  * T_SHORT => Py_T_SHORT
  * T_INT => Py_T_INT
  * T_LONG => Py_T_LONG
  * T_FLOAT => Py_T_FLOAT
  * T_DOUBLE => Py_T_DOUBLE
  * T_STRING => Py_T_STRING
  * T_OBJECT => _Py_T_OBJECT
  * T_CHAR => Py_T_CHAR
  * T_BYTE => Py_T_BYTE
  * T_UBYTE => Py_T_UBYTE
  * T_USHORT => Py_T_USHORT
  * T_UINT => Py_T_UINT
  * T_ULONG => Py_T_ULONG
  * T_STRING_INPLACE => Py_T_STRING_INPLACE
  * T_BOOL => Py_T_BOOL
  * T_OBJECT_EX => Py_T_OBJECT_EX
  * T_LONGLONG => Py_T_LONGLONG
  * T_ULONGLONG => Py_T_ULONGLONG
  * T_PYSSIZET => Py_T_PYSSIZET
  * T_NONE => _Py_T_NONE
  * READONLY => Py_READONLY
  * PY_AUDIT_READ => Py_AUDIT_READ
  * READ_RESTRICTED => Py_AUDIT_READ
  * PY_WRITE_RESTRICTED => _Py_WRITE_RESTRICTED
  * RESTRICTED => (READ_RESTRICTED | _Py_WRITE_RESTRICTED)

gh-107237: Fix test_udp_reconnection() of test_logging (#107238)

test_logging: Fix test_udp_reconnection() by increasing the timeout
from 100 ms to 5 minutes (LONG_TIMEOUT).

Replace also blocking wait() with wait(LONG_TIMEOUT) in
test_output() to prevent the test to hang.

gh-105059: Use GCC/clang extension for PyObject union (#107232)

Anonymous union is new in C11. To prevent compiler warning
when using -pedantic compiler option, use Clang and GCC
extension on C99 and older.

gh-106996: Add a how-to section to the turtle documentation (#107153)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

gh-86493: Modernize modules initialization code (GH-106858)

Use PyModule_Add() or PyModule_AddObjectRef() instead of soft deprecated
PyModule_AddObject().

gh-106774: Update bundled pip version to 23.2.1 (#106775)

* Update bundled pip version to 23.2.1

gh-104050: Argument clinic: more misc typing coverage improvements (#107210)

gh-104050: Argument clinic: improve typing around adding C converters (#107209)

gh-107211: No longer export internal variables (#107218)

No longer export these 5 internal C API variables:

* _PyBufferWrapper_Type
* _PyImport_FrozenBootstrap
* _PyImport_FrozenStdlib
* _PyImport_FrozenTest
* _Py_SwappedOp

Fix the definition of these internal functions, replace PyAPI_DATA()
with PyAPI_FUNC():

* _PyImport_ClearExtension()
* _PyObject_IsFreed()
* _PyThreadState_GetCurrent()

gh-107211: No longer export internal functions (4) (#107217)

No longer export these 2 internal C API functions:

* _PyEval_SignalAsyncExc()
* _PyEval_SignalReceived()

Add also comments explaining why some internal functions have to be
exported, and update existing comments.

gh-107211: No longer export internal functions (3) (#107215)

No longer export these 14 internal C API functions:

* _PySys_Audit()
* _PySys_SetAttr()
* _PyTraceBack_FromFrame()
* _PyTraceBack_Print_Indented()
* _PyUnicode_FormatAdvancedWriter()
* _PyUnicode_ScanIdentifier()
* _PyWarnings_Init()
* _Py_DumpASCII()
* _Py_DumpDecimal()
* _Py_DumpHexadecimal()
* _Py_DumpTraceback()
* _Py_DumpTracebackThreads()
* _Py_WriteIndent()
* _Py_WriteIndentedMargin()

gh-107211: No longer export internal functions (2) (#107214)

No longer export these 43 internal C API functions:

* _PyDict_CheckConsistency()
* _PyErr_ChainStackItem()
* _PyErr_CheckSignals()
* _PyErr_CheckSignalsTstate()
* _PyErr_Clear()
* _PyErr_ExceptionMatches()
* _PyErr_Fetch()
* _PyErr_Format()
* _PyErr_FormatFromCauseTstate()
* _PyErr_GetExcInfo()
* _PyErr_GetHandledException()
* _PyErr_GetTopmostException()
* _PyErr_NoMemory()
* _PyErr_NormalizeException()
* _PyErr_Restore()
* _PyErr_SetHandledException()
* _PyErr_SetNone()
* _PyErr_SetObject()
* _PyErr_SetString()
* _PyErr_StackItemToExcInfoTuple()
* _PyExc_CreateExceptionGroup()
* _PyExc_PrepReraiseStar()
* _PyException_AddNote()
* _PyInterpreterState_Enable()
* _PyLong_FormatAdvancedWriter()
* _PyLong_FormatBytesWriter()
* _PyLong_FormatWriter()
* _PyMem_GetAllocatorName()
* _PyMem_SetDefaultAllocator()
* _PyMem_SetupAllocators()
* _PyOS_InterruptOccurred()
* _PyRuntimeState_Fini()
* _PyRuntimeState_Init()
* _PyRuntime_Finalize()
* _PyRuntime_Initialize()
* _PyThreadState_Bind()
* _PyThreadState_DeleteExcept()
* _PyThreadState_New()
* _PyThreadState_Swap()
* _PyType_CheckConsistency()
* _PyUnicodeTranslateError_Create()
* _Py_DumpExtensionModules()
* _Py_FatalErrorFormat()

gh-107211: No longer export internal functions (1) (#107213)

No longer export these 49 internal C API functions:

* _PyArgv_AsWstrList()
* _PyCode_New()
* _PyCode_Validate()
* _PyFloat_DebugMallocStats()
* _PyFloat_FormatAdvancedWriter()
* _PyImport_CheckSubinterpIncompatibleExtensionAllowed()
* _PyImport_ClearExtension()
* _PyImport_GetModuleId()
* _PyImport_SetModuleString()
* _PyInterpreterState_IDDecref()
* _PyInterpreterState_IDIncref()
* _PyInterpreterState_IDInitref()
* _PyInterpreterState_LookUpID()
* _PyWideStringList_AsList()
* _PyWideStringList_CheckConsistency()
* _PyWideStringList_Clear()
* _PyWideStringList_Copy()
* _PyWideStringList_Extend()
* _Py_ClearArgcArgv()
* _Py_DecodeUTF8Ex()
* _Py_DecodeUTF8_surrogateescape()
* _Py_EncodeLocaleRaw()
* _Py_EncodeUTF8Ex()
* _Py_GetEnv()
* _Py_GetForceASCII()
* _Py_GetLocaleEncoding()
* _Py_GetLocaleEncodingObject()
* _Py_GetLocaleconvNumeric()
* _Py_ResetForceASCII()
* _Py_device_encoding()
* _Py_dg_dtoa()
* _Py_dg_freedtoa()
* _Py_dg_strtod()
* _Py_get_blocking()
* _Py_get_env_flag()
* _Py_get_inheritable()
* _Py_get_osfhandle_noraise()
* _Py_get_xoption()
* _Py_open()
* _Py_open_osfhandle()
* _Py_open_osfhandle_noraise()
* _Py_read()
* _Py_set_blocking()
* _Py_str_to_int()
* _Py_wfopen()
* _Py_wgetcwd()
* _Py_wreadlink()
* _Py_wrealpath()
* _Py_write()

gh-107211: Rename PySymtable_Lookup() to _PySymtable_Lookup() (#107212)

Rename the internal PySymtable_Lookup() function to
_PySymtable_Lookup() and no longer export it.

gh-104050: Argument Clinic: Annotate `CRenderData.__init__` (#107207)

Argument Clinic: Annotate `CRenderData.__init__`

gh-104050: Argument clinic: misc improvements to type annotation coverage (#107206)

gh-106149: move _PyCfg_BasicblockLastInstr and make it local to flowgraph.c (#107180)

gh-104050: Argument clinic: annotate `format_docstring()` (#107200)

gh-106917: fix super classmethod calls to non-classmethods (#106977)

gh-106727: Add `__module__` check for `inspect.getsource(cls)` (#106968)

gh-102304: Rename _Py_IncRefTotal_DO_NOT_USE_THIS() (#107193)

* Rename _Py_IncRefTotal_DO_NOT_USE_THIS() to _Py_INCREF_IncRefTotal()
* Rename _Py_DecRefTotal_DO_NOT_USE_THIS() to _Py_DECREF_DecRefTotal()
* Remove temporary _Py_INC_REFTOTAL() and _Py_DEC_REFTOTAL() macros

gh-98608: Move PyInterpreterConfig to pylifecycle.h (#107191)

Move PyInterpreterConfig structure and associated macros from
initconfig.h to pylifecycle.h: it's not related to the Python
Initialization Configuration.

gh-104050: Argument Clinic: annotate `main()` (#107192)

GH-96803: Move PyUnstable_InterpreterFrame_GetCode() to Python.h (#107188)

Declare the following 3 PyUnstable functions in
Include/cpython/pyframe.h rather than Include/cpython/frameobject.h,
so they are now provided by the standard "#include <Python.h>".

gh-106368: Increase Argument Clinic CLI test coverage (#107156)

Instead of hacking into the Clinic class, use the Argument Clinic tool
to run the ClinicExternalTest test suite.

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

gh-106320: Remove private _PyMem API (#107187)

Move private _PyMem functions to the internal C API (pycore_pymem.h):

* _PyMem_GetCurrentAllocatorName()
* _PyMem_RawStrdup()
* _PyMem_RawWcsdup()
* _PyMem_Strdup()

No longer export these functions.

Move pymem_getallocatorsname() function from _testcapi to _testinternalcapi,
since the API moved to the internal C API.

gh-106320: Remove private _PyUnicode C API (#107185)

Move private _PyUnicode functions to the internal C API
(pycore_unicodeobject.h):

* _PyUnicode_IsCaseIgnorable()
* _PyUnicode_IsCased()
* _PyUnicode_IsXidContinue()
* _PyUnicode_IsXidStart()
* _PyUnicode_ToFoldedFull()
* _PyUnicode_ToLowerFull()
* _PyUnicode_ToTitleFull()
* _PyUnicode_ToUpperFull()

No longer export these functions.

Thoroughly refactor the cases generator (#107151)

This mostly extracts a whole bunch of stuff out of generate_cases.py into separate files, but there are a few other things going on here.

- analysis.py: `Analyzer` etc.
- instructions.py: `Instruction` etc.
- flags.py: `InstructionFlags`, `variable_used`, `variable_used_unspecialized`
- formatting.py: `Formatter` etc.
- Rename parser.py to parsing.py, to avoid conflict with stdlib parser.py
- Blackify most things
- Fix most mypy errors
- Remove output filenames from Generator state, add them to `write_instructions()` etc.
- Fix unit tests

Docs: Add missing markup to Argument Clinic docs (#106876)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

gh-107162: Document errcode.h usage in its comment (#107177)

Public and documented PyRun_InteractiveOneFlags() C API uses it.

gh-106320: Remove private _PyDict C API (#107145)

Move private _PyDict functions to the internal C API (pycore_dict.h):

* _PyDict_Contains_KnownHash()
* _PyDict_DebugMallocStats()
* _PyDict_DelItemIf()
* _PyDict_GetItemWithError()
* _PyDict_HasOnlyStringKeys()
* _PyDict_MaybeUntrack()
* _PyDict_MergeEx()

No longer export these functions.

Fix PyVectorcall_Function doc versionadded (#107140)

The documentation implies that PyVectorcall_Function() was available in Python 3.8.
This is half-true - it was available under a different name. I think it's clearer to set
the "version added" to 3.9.

Docs: Remove duplicate word in Argument Clinic howto heading (#107169)

gh-107017: Change Chapter Strings to Texts in the Introduction chapter. (#107104)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

gh-106320: Remove private _PyObject C API (#107159)

Move private _PyObject and private _PyType functions to the internal
C API (pycore_object.h):

* _PyObject_GetMethod()
* _PyObject_IsAbstract()
* _PyObject_NextNotImplemented()
* _PyType_CalculateMetaclass()
* _PyType_GetDocFromInternalDoc()
* _PyType_GetTextSignatureFromInternalDoc()

No longer export these functions.

Docs: fix typo in os.pwrite docstring (#107087)

gh-105291: Add link to migration guide for distutils (#107130)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

gh-106948: Docs: Disable links for C standard library functions, OS utility functions and system calls (#107062)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

gh-106320: Remove _PyBytes_Join() C API (#107144)

Move private _PyBytes functions to the internal C API
(pycore_bytesobject.h):

* _PyBytes_DecodeEscape()
* _PyBytes_FormatEx()
* _PyBytes_FromHex()
* _PyBytes_Join()

No longer export these functions.

gh-106320: Remove private _PyObject C API (#107147)

Move private debug _PyObject functions to the internal C API
(pycore_object.h):

* _PyDebugAllocatorStats()
* _PyObject_CheckConsistency()
* _PyObject_DebugTypeStats()
* _PyObject_IsFreed()

No longer export most of these functions, except of
_PyObject_IsFreed().

Move test functions using _PyObject_IsFreed() from _testcapi to
_testinternalcapi. check_pyobject_is_freed() test no longer catch
_testcapi.error: the tested function cannot raise _testcapi.error.

gh-106320: Remove _PyTuple_MaybeUntrack() C API (#107143)

Move _PyTuple_MaybeUntrack() and _PyTuple_DebugMallocStats() functions
to the internal C API (pycore_tuple.h). No longer export these functions.

gh-106320: Remove _PyIsSelectable_fd() C API (#107142)

Move _PyIsSelectable_fd() macro to the internal C API
(pycore_fileutils.h).

Remove superflous whitespaces in `layout.html`. (GH-107067)

gh-107122: Update what's news for dbm.*dbm.clear() method (gh-107135)

gh-107122: Add clear method to dbm.ndbm module (gh-107126)

gh-62519: Make pgettext search plurals when translation is not found (#107118)

Co-authored-by: Łukasz Langa <lukasz@langa.pl>

gh-107122: Add clear method to dbm.gdbm.module (gh-107127)

gh-107017: Analolgy to Pascal and C replaced. (#107025)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

gh-107091: Fix the use of some C domain roles (#107092)

gh-106186: Don't report MultipartInvariantViolationDefect for valid multipart emails when parsing header only (#107016)

bpo-18319: gettext() can retrieve a message even if a plural form exists (#19869)

gh-106996: Add the basics of a turtle graphics tutorial (#107072)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

gh-106976: alphabetise bullets by module name task2-3 (#107005)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

gh-101100: Fix some broken sphinx references (#107095)

gh-54738: Add argparse i18n howto (#104562)

gh-71261: Add paragraph on shadowing submodules with star imports (#107004)

gh-107017: removed mention that C does it the same way (#107020)

gh-102111: Add link to string escape sequences in re module (#106995)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

gh-82500: Fix asyncio sendfile overflow on 32bit (#107056)

gh-107082: Remove debug hack from get_first_executor in test_capi.test_misc (#107085)

(Even though it doesn't look like it fixes gh-107082 -- see discussion there -- it still removes debug code that should never have been committed.)

gh-106962: Detect mpicc in configure.ac (#106961)

Don't let autoconf mistake MPI compilers for Intel compilers;
filter out the MPI case to prevent Intel specific options from being applied.

gh-104050: Argument Clinic: Increase typing coverage (#107074)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

gh-106320: Remove _PyFunction_Vectorcall() API (#107071)

Move _PyFunction_Vectorcall() API to the internal C API.
No longer export the function.

gh-106320: Remove private _PyModule API (#107070)

Move private _PyModule API to the internal C API
(pycore_moduleobject.h):

* _PyModule_Clear()
* _PyModule_ClearDict()
* _PyModuleSpec_IsInitializing()
* _PyModule_IsExtension()

No longer export these functions.

GH-103082: Rename PY_MONITORING_EVENTS to _PY_MONITORING_EVENTS (#107069)

Rename private C API constants:

* Rename PY_MONITORING_UNGROUPED_EVENTS to _PY_MONITORING_UNGROUPED_EVENTS
* Rename PY_MONITORING_EVENTS to _PY_MONITORING_EVENTS

gh-106527: asyncio: optimize to add/remove readers and writers (#106528)

gh-106320: Move _PyMethodWrapper_Type to internal C API (#107064)

gh-107028: tiny textual changes in logging docs and docstrings (GH-107029)

gh-106320: Remove private _PyInterpreterID C API (#107053)

Move the private _PyInterpreterID C API to the internal C API: add a
new pycore_interp_id.h header file.

Remove Include/interpreteridobject.h and
Include/cpython/interpreteridobject.h header files.

gh-106948: Add standard external names to nitpick_ignore (GH-106949)

It includes standard C types, macros and variables like "size_t",
"LONG_MAX" and "errno", and standard environment variables like "PATH".

gh-107008: Document the curses module variables LINES and COLS (GH-107011)

LINES and COLS referred in curses.update_lines_cols() documentations are
the module variables, not the environment variables.