docs: improve style in an example

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

docs: words instead of <=

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

gh-55454: Clarify imaplib idle() docs

- Add example idle response tuples, to make the minor difference from other
  imaplib response tuples more obvious.
- Merge the idle context manager's burst() method docs with the IMAP
  object's idle() method docs, for easier understanding.
- Upgrade the Windows note regarding lack of pipe timeouts to a warning.
- Rephrase various things for clarity.

gh-55454: Add IMAP4 IDLE support to imaplib

This extends imaplib with support for the rfc2177 IMAP IDLE command,
as requested in #55454.  It allows events to be pushed to a client as
they occur, rather than having to continually poll for mailbox changes.

The interface is a new idle() method, which returns an iterable context
manager.  Entering the context starts IDLE mode, during which events
(untagged responses) can be retrieved using the iteration protocol.
Exiting the context sends DONE to the server, ending IDLE mode.

An optional time limit for the IDLE session is supported, for use with
servers that impose an inactivity timeout.

The context manager also offers a burst() method, designed for programs
wishing to process events in batch rather than one at a time.

Notable differences from other implementations:

- It's an extension to imaplib, rather than a replacement.
- It doesn't introduce additional threads.
- It doesn't impose new requirements on the use of imaplib's existing methods.
- It passes the unit tests in CPython's test/test_imaplib.py module
  (and adds new ones).
- It works on Windows, Linux, and other unix-like systems.
- It makes IDLE available on all of imaplib's client variants
  (including IMAP4_stream).
- The interface is pythonic and easy to use.

Caveats:

- Due to a Windows limitation, the special case of IMAP4_stream running
  on Windows lacks a duration/timeout feature. (This is the stdin/stdout
  pipe connection variant; timeouts work fine for socket-based
  connections, even on Windows.) I have documented it where appropriate.

- The file-like imaplib instance attributes are changed from buffered to
  unbuffered mode. This could potentially break any client code that
  uses those objects directly without expecting partial reads/writes.
  However, these attributes are undocumented. As such, I think (and
  PEP 8 confirms) that they are fair game for changes.
  https://peps.python.org/pep-0008/#public-and-internal-interfaces

Usage examples:

https://github.com/python/cpython/issues/55454#issuecomment-2227543041

Original discussion:

https://discuss.python.org/t/gauging-interest-in-my-imap4-idle-implementation-for-imaplib/59272

Earlier requests and suggestions:

https://github.com/python/cpython/issues/55454

https://mail.python.org/archives/list/python-ideas@python.org/thread/C4TVEYL5IBESQQPPS5GBR7WFBXCLQMZ2/

gh-123553: Fix compile warning in `compile.c` (#123578)

gh-118761: Speedup pathlib import by deferring shutil (#123520)

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

gh-123341: Support `tkinter.Event` type subcript (#123353)

Co-authored-by: Kirill Podoprigora <kirill.bast9@mail.ru>

Bump types-setuptools from 71.1.0.20240726 to 74.0.0.20240831 in /Tools (#123565)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

gh-91126: Docs and tests for slotted dataclasses with `__init_subclass__` (#123342)

Bump mypy from 1.11.1 to 1.11.2 in /Tools (#123566)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

Bump types-psutil from 6.0.0.20240621 to 6.0.0.20240901 in /Tools (#123564)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

gh-123553: Fix compiler warning in `Python/compile.c` (#123554)

gh-123550: Fix code snippet of `BUILD_TUPLE` in `dis` docs (#123551)

GH-109975: Copyedit 3.13 What's New: Removals (#123529)

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

gh-123494: Improve documentation for ``webbrowser`` return types (#123495)

Document the return value for ``webbrowser.open*()``.

gh-115238: Remove a redundant f-string in graphlib (#115239)

gh-123517: Remove unnecessary ``:meth:`` parentheses (#123518)

gh-121285: Remove backtracking when parsing tarfile headers (GH-121286)

* Remove backtracking when parsing tarfile headers
* Rewrite PAX header parsing to be stricter
* Optimize parsing of GNU extended sparse headers v0.0

Co-authored-by: Kirill Podoprigora <kirill.bast9@mail.ru>
Co-authored-by: Gregory P. Smith <greg@krypto.org>

Enable colour for doctest on GitHub Actions (#123536)

gh-123309: Remove check for redefined memo entry in pickletools.dis() (GH-123374)

Such pickles are supported by the Unpickler even if the Pickler does not
produce them.

gh-76960: Fix urljoin() and urldefrag() for URIs with empty components (GH-123273)

* urljoin() with relative reference "?" sets empty query and removes fragment.
* Preserve empty components (authority, params, query, fragment) in urljoin().
* Preserve empty components (authority, params, query) in urldefrag().

Also refactor the code and get rid of double _coerce_args() and
_coerce_result() calls in urljoin(), urldefrag(), urlparse() and
urlunparse().

gh-123309: Add more tests for the pickletools module (GH-123355)

Add tests for genops() and dis().

gh-123407: Enable translating literal and code blocks (#123408)

gh-108172: do not override OS preferred browser if it is a super-string of a known browser (GH-113011)

When checking if the registering browser is the "OS preferred browser", do not use a substring search - that makes no sense: one can have a preferred browser that looks like a super-string of a known browser, e.g. "firefox-nightly" vs "firefox".

https://github.com/python/cpython/issues/108172 explains in more detail, and lays out a potential better future enhancement for this case of just using xdg-open.  We'll go with this for now.

---------

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

gh-121313: Limit the reading size from pipes to their default buffer size on POSIX systems (GH-121315)

See https://github.com/python/cpython/issues/121313 for analysis, but this greatly reduces memory overallocation and overhead when multiprocessing is sending non-small data over its pipes between processes.

Make self turtledemo codeowner (#123524)

gh-121404: rearrange code in compile.c so that codegen functions come first and compiler functions second (#123510)

gh-123440: Improve error message for `except as` used with not a name (#123442)

gh-122854: Add Py_HashBuffer() function (#122855)

gh-121645: Add PyBytes_Join() function (#121646)

* Replace _PyBytes_Join() with PyBytes_Join().
* Keep _PyBytes_Join() as an alias to PyBytes_Join().

gh-123484: Fix the debug offsets for PyLongObject (#123485)

gh-123492: Remove unnecessary `:func:` parentheses (#123493)

gh-123189: [`Modules/blake2module.c`]: Move function definitions and their usage under the macros (#123190)

gh-123446: Fix empty function names in `TypeError`s in `typeobject` (#123470)

gh-121485: Always use 64-bit integers for integers bits count (GH-121486)

Use 64-bit integers instead of platform specific size_t or Py_ssize_t
to represent the number of bits in Python integer.

gh-123446: Fix empty function names in `TypeError`s in `_csv` module (#123462)

gh-123446: Fix empty function names in `TypeError`s in `_csv` module (#123461)

gh-123431: Harmonize extension code checks in pickle (GH-123434)

This checks are redundant in normal circumstances and can only work if
the extension registry was intentionally broken.

* The Python implementation now raises exception for the extension code
  with false boolean value.
* Simplify the C code. RuntimeError is now raised in explicit checks.
* Add many tests.

gh-123448: Move `_PyNoDefault_Type` to the static types array (#123449)

gh-122136: test_asyncio: Don't fail if the kernel buffers more data than advertised (GH-123423)

gh-123142: fix too wide source location of GET_ITER/GET_AITER (#123420)

gh-101860: document `property.__name__` (GH-123399)

gh-123344: Add missing ast optimizations for PEP 696 (#123377)

Co-authored-by: Kirill Podoprigora <kirill.bast9@mail.ru>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Fix typos in docs, error messages and comments (#123336)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

gh-120389: Add PyLong_FromInt64() and PyLong_AsInt64() (#120390)

Add new functions to convert C <stdint.h> numbers from/to Python int:

* PyLong_FromInt32()
* PyLong_FromUInt32()
* PyLong_FromInt64()
* PyLong_FromUInt64()
* PyLong_AsInt32()
* PyLong_AsUInt32()
* PyLong_AsInt64()
* PyLong_AsUInt64()

gh-122561: Clean up and microoptimize str.translate and charmap codec (GH-122932)

* Replace PyLong_AS_LONG() with PyLong_AsLong().
* Call PyLong_AsLong() only once per the replacement code.
* Use PyMapping_GetOptionalItem() instead of PyObject_GetItem().

gh-123254: Improve `tuple` C API docs with more info about errors (#123255)

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

gh-123363: Show string value of CONTAINS_OP oparg in dis (#123387)

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

gh-123270: Replaced SanitizedNames with a more surgical fix. (#123354)

Applies changes from zipp 3.20.1 and jaraco/zipp#124

gh-123271: Make builtin zip method safe under free-threading (#123272)

The `zip_next` function uses a common optimization technique for methods
that generate tuples. The iterator maintains an internal reference to
the returned tuple. When the method is called again, it checks if the
internal tuple's reference count is 1. If so, the tuple can be reused.
However, this approach is not safe under the free-threading build:
after checking the reference count, another thread may perform the same
check and also reuse the tuple. This can result in a double decref on
the items of the replaced tuple and a double incref (memory leak) on
the items of the tuple being set.

This adds a function, `_PyObject_IsUniquelyReferenced` that
encapsulates the stricter logic necessary for the free-threaded build:
the internal tuple must be owned by the current thread, have a local
refcount of one, and a shared refcount of zero.

gh-121404: split compiler_nameop into a codegen part and a compiler part (#123398)

gh-109975: Fix a typo in What's New in Python 3.13 (#123393)

GH-117759: Document incremental GC (GH-123266)

* Update what's new

* Update gc module docs and fix inconsistency in gc.get_objects

gH-80788: remove old weakset workaround for thread safety (#123388)

gh-123089: Make weakref.WeakSet safe against concurrent mutations while it is being iterated  (#123279)

* Make `weakref.WeakSet` safe against concurrent mutations while it is being iterated.

`_IterationGuard` is no longer used for `WeakSet`, it now relies on copying the underlying set which is an atomic operation while iterating so that it can be modified by other threads.

gh-120426: Reword the glossary term "immortal" (GH-123191)

Reword the glossary term "immortal", mark it as an implementation detail

gh-121404: compiler_visit_* --> codegen_visit_* (#123382)

GH-123232: Factor BINARY_SLICE and STORE_SLICE to handle stats properly for tier 2. (GH-123381)

GH-115775: Use `__static_attributes__` to initialize shared keys (GH-118468)

Further revise idlelib/Icons/README.text (#123364)

In particular, add trademark derivative approval information.

gh-122666: Tests for ast optimizations (#122667)

Co-authored-by: Sergey B Kirpichev <skirpichev@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

gh-123340: Show string value of `IS_OP` oparg in `dis` (#123348)

GH-73991: Prune `pathlib.Path.copy()` and `copy_into()` arguments (#123337)

Remove *ignore* and *on_error* arguments from `pathlib.Path.copy[_into]()`,
because these arguments are under-designed. Specifically:

- *ignore* is appropriated from `shutil.copytree()`, but it's not clear
  how it should apply when the user copies a non-directory. We've changed
  the callback signature from the `shutil` version, but I'm not confident
  the new signature is as good as it can be.
- *on_error* is a generalisation of `shutil.copytree()`'s error handling,
  which is to accumulate exceptions and raise a single `shutil.Error` at
  the end. It's not obvious which solution is better.

Additionally, this arguments may be challenging to implement in future user
subclasses of `PathBase`, which might utilise a native recursive copying
method.

GH-73991: Make `pathlib.Path.delete()` private. (#123315)

Per feedback from Paul Moore on GH-123158, it's better to defer making
`Path.delete()` public than ship it with under-designed error handling
capabilities.

We leave a remnant `_delete()` method, which is used by `move()`. Any
functionality not needed by `move()` is deleted.

gh-111495: Remove test_capi test_rshift_print() (#123338)

The suggestion for "print >> value" was removed recently:
commit 9375b9ca3a4998678ba74ff5c77ed540a4dcf887.

 gh-111495: Add tests for PyNumber C API (#111996)

GH-73991: Add `pathlib.Path.copy_into()` and `move_into()` (#123314)

These two methods accept an *existing* directory path, onto which we join
the source path's base name to form the final target path.

A possible alternative implementation is to check for directories in
`copy()` and `move()` and adjust the target path, which is done in several
`shutil` functions. This behaviour is helpful in a shell context, but
less so in a stored program that explicitly specifies destinations. For
example, a user that calls `Path('foo.py').copy('bar.py')` might not
imagine that `bar.py/foo.py` would be created, but under the alternative
implementation this will happen if `bar.py` is an existing directory.

gh-111495: Add tests for PyTuple C API (#118757)

Co-authored-by: kalyanr <kalyan.ben10@live.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>

Rewrite idlelib/Icons/README.txt (#123329)

gh-123177: Fix prompt for wrapped lines in pyrepl (#123324)

When display lines above the cursor come from the cache, the first line
to not come from the cache may be a wrapped line, starting half way
through a logical line in the buffer. Detect and handle this case to
avoid accidentally drawing a stray prompt in the middle of a logical
line.

gh-82378: Document the difference between sys.tracebacklimit and the limit arguments (#123286)

gh-123177: Deactivate line wrap for Apple Terminal via scape codes in the new REPL (#123267)

gh-123297: Propagate LD_FLAGS to LDCXXSHARED in sysconfig (#123298)

gh-122982: Extend the deprecation period for bool inversion by two years (#123306)

GH-73991: Add `pathlib.Path.move()` (#122073)

Add a `Path.move()` method that moves a file or directory tree, and returns a new `Path` instance pointing to the target.

This method is similar to `shutil.move()`, except that it doesn't accept a *copy_function* argument, and it doesn't check whether the destination is an existing directory.

gh-123228: don't leak file descriptors in pyrepl test (#123302)

GH-109975: Copyedit 3.13 What's New: Optimizations (#123301)

GH-123299: Move ctypes What's New entry to 3.14 (#123300)

Revert "GH-120754: Add a strace helper and test set of syscalls for o… (#123303)

Revert "GH-120754: Add a strace helper and test set of syscalls for open().read() (#121143)"

This reverts commit e38d0afe3548b856ccf0b05c01ed3eefc69cb3e7.

GH-120754: Add a strace helper and test set of syscalls for open().read() (#121143)

Remove comment from pystate created in 2003 (#123259)

gh-123228: fix return type for _ReadlineWrapper.get_line_buffer() (#123281)

Co-authored-by: Carl Friedrich Bolz-Tereick <cfbolz@gmx.de>

GH-122890: Fix low-level error handling in `pathlib.Path.copy()` (#122897)

Give unique names to our low-level FD copying functions, and try each one
in turn. Handle errors appropriately for each implementation:

- `fcntl.FICLONE`: suppress `EBADF`, `EOPNOTSUPP`, `ETXTBSY`, `EXDEV`
- `posix._fcopyfile`: suppress `EBADF`, `ENOTSUP`
- `os.copy_file_range`: suppress `ETXTBSY`, `EXDEV`
- `os.sendfile`: suppress `ENOTSOCK`

GH-109975: Copyedit 3.13 What's New: Improved Modules (#123132)

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

Docs: Fix Makefile syntax (#123287)

gh-123243: Fix reference leak in `_decimal` (#123244)

gh-117376: Make `Py_DECREF` a macro in ceval.c in free-threaded build (#122975)

`Py_DECREF` and `PyStackRef_CLOSE` are now implemented as macros in the
free-threaded build in ceval.c. There are two motivations;

 * MSVC has problems inlining functions in ceval.c in the PGO build.

 * We will want to mark escaping calls in order to spill the stack
   pointer in ceval.c and we will want to do this around `_Py_Dealloc`
   (or `_Py_MergeZeroLocalRefcount` or `_Py_DecRefShared`), not around
   the entire `Py_DECREF` or `PyStackRef_CLOSE` call.

gh-123205: `Python/bytecodes.c`: Fix compiler warning (#123206)

Fix MSVC warning "conversion from '__int64' to 'int'"

GH-73991: Disallow copying directory into itself via `pathlib.Path.copy()` (#122924)

gh-121404: more compiler_* -> codegen_*, class_body and comprehensions (#123262)

Fix typo mentioning threads instead of tasks (#123203)

gh-122272: Guarantee specifiers %F and %C for datetime.strftime to be 0-padded (GH-122436)

GH-122298: Restore printing of GC stats (GH-123261)

gh-123229: Fix valgrind warning by initializing the f-string buffers to 0 in the tokenizer (#123263)

Signed-off-by: Pablo Galindo <pablogsal@gmail.com>

GH-123232: Fix "not specialized" stats (GH-123236)

gh-121404: compiler_annassign --> codegen_annassign (#123245)

GH-123040: Specialize shadowed `LOAD_ATTR`. (GH-123219)

gh-123213: Fixed xml.etree.ElementTree.Element.extend and assignment to no longer hide exceptions (GH-123214)

GH-99108: Amend Modules/Setup (#123146)

gh-122546: Relax SyntaxError check when raising errors on the new REPL (#123233)