pythongh-121657: merge upstream

Author: gege-hoho

Doc/faq/programming.rst

@@ -1741,11 +1741,31 @@ but effective way to define class private variables.  Any identifier of the form
 is textually replaced with ``_classname__spam``, where ``classname`` is the
 current class name with any leading underscores stripped.
 
-This doesn't guarantee privacy: an outside user can still deliberately access
-the "_classname__spam" attribute, and private values are visible in the object's
-``__dict__``.  Many Python programmers never bother to use private variable
-names at all.
+The identifier can be used unchanged within the class, but to access it outside
+the class, the mangled name must be used:
 
+.. code-block:: python
+
+   class A:
+       def __one(self):
+           return 1
+       def two(self):
+           return 2 * self.__one()
+
+   class B(A):
+       def three(self):
+           return 3 * self._A__one()
+
+   four = 4 * A()._A__one()
+
+In particular, this does not guarantee privacy since an outside user can still
+deliberately access the private attribute; many Python programmers never bother
+to use private variable names at all.
+
+.. seealso::
+
+   The :ref:`private name mangling specifications <private-name-mangling>`
+   for details and special cases.
 
 My class defines __del__ but it is not called when I delete the object.
 -----------------------------------------------------------------------

Doc/library/configparser.rst

@@ -147,23 +147,28 @@ case-insensitive and stored in lowercase [1]_.
 It is possible to read several configurations into a single
 :class:`ConfigParser`, where the most recently added configuration has the
 highest priority. Any conflicting keys are taken from the more recent
-configuration while the previously existing keys are retained.
+configuration while the previously existing keys are retained. The example
+below reads in an ``override.ini`` file, which will override any conflicting
+keys from the ``example.ini`` file.
+
+.. code-block:: ini
+
+   [DEFAULT]
+   ServerAliveInterval = -1
 
 .. doctest::
 
-   >>> another_config = configparser.ConfigParser()
-   >>> another_config.read('example.ini')
-   ['example.ini']
-   >>> another_config['topsecret.server.example']['Port']
-   '50022'
-   >>> another_config.read_string("[topsecret.server.example]\nPort=48484")
-   >>> another_config['topsecret.server.example']['Port']
-   '48484'
-   >>> another_config.read_dict({"topsecret.server.example": {"Port": 21212}})
-   >>> another_config['topsecret.server.example']['Port']
-   '21212'
-   >>> another_config['topsecret.server.example']['ForwardX11']
-   'no'
+   >>> config_override = configparser.ConfigParser()
+   >>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
+   >>> with open('override.ini', 'w') as configfile:
+   ...     config_override.write(configfile)
+   ...
+   >>> config_override = configparser.ConfigParser()
+   >>> config_override.read(['example.ini', 'override.ini'])
+   ['example.ini', 'override.ini']
+   >>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
+   -1
+
 
 This behaviour is equivalent to a :meth:`ConfigParser.read` call with several
 files passed to the *filenames* parameter.
@@ -984,6 +989,31 @@ ConfigParser Objects
    converter gets its own corresponding :meth:`!get*()` method on the parser
    object and section proxies.
 
+   It is possible to read several configurations into a single
+   :class:`ConfigParser`, where the most recently added configuration has the
+   highest priority. Any conflicting keys are taken from the more recent
+   configuration while the previously existing keys are retained. The example
+   below reads in an ``override.ini`` file, which will override any conflicting
+   keys from the ``example.ini`` file.
+
+   .. code-block:: ini
+
+      [DEFAULT]
+      ServerAliveInterval = -1
+
+   .. doctest::
+
+      >>> config_override = configparser.ConfigParser()
+      >>> config_override['DEFAULT'] = {'ServerAliveInterval': '-1'}
+      >>> with open('override.ini', 'w') as configfile:
+      ...     config_override.write(configfile)
+      ...
+      >>> config_override = configparser.ConfigParser()
+      >>> config_override.read(['example.ini', 'override.ini'])
+      ['example.ini', 'override.ini']
+      >>> print(config_override.get('DEFAULT', 'ServerAliveInterval'))
+      -1
+
    .. versionchanged:: 3.1
       The default *dict_type* is :class:`collections.OrderedDict`.
 

Doc/library/ftplib.rst

@@ -243,7 +243,7 @@ FTP objects
       Retrieve a file in binary transfer mode.
 
       :param str cmd:
-        An appropriate ``STOR`` command: :samp:`"STOR {filename}"`.
+        An appropriate ``RETR`` command: :samp:`"RETR {filename}"`.
 
       :param callback:
          A single parameter callable that is called

Doc/reference/expressions.rst

@@ -83,18 +83,47 @@ exception.
    pair: name; mangling
    pair: private; names
 
-**Private name mangling:** When an identifier that textually occurs in a class
-definition begins with two or more underscore characters and does not end in two
-or more underscores, it is considered a :dfn:`private name` of that class.
-Private names are transformed to a longer form before code is generated for
-them.  The transformation inserts the class name, with leading underscores
-removed and a single underscore inserted, in front of the name.  For example,
-the identifier ``__spam`` occurring in a class named ``Ham`` will be transformed
-to ``_Ham__spam``.  This transformation is independent of the syntactical
-context in which the identifier is used.  If the transformed name is extremely
-long (longer than 255 characters), implementation defined truncation may happen.
-If the class name consists only of underscores, no transformation is done.
+Private name mangling
+^^^^^^^^^^^^^^^^^^^^^
 
+When an identifier that textually occurs in a class definition begins with two
+or more underscore characters and does not end in two or more underscores, it
+is considered a :dfn:`private name` of that class.
+
+.. seealso::
+
+   The :ref:`class specifications <class>`.
+
+More precisely, private names are transformed to a longer form before code is
+generated for them.  If the transformed name is longer than 255 characters,
+implementation-defined truncation may happen.
+
+The transformation is independent of the syntactical context in which the
+identifier is used but only the following private identifiers are mangled:
+
+- Any name used as the name of a variable that is assigned or read or any
+  name of an attribute being accessed.
+
+  The ``__name__`` attribute of nested functions, classes, and type aliases
+  is however not mangled.
+
+- The name of imported modules, e.g., ``__spam`` in ``import __spam``.
+  If the module is part of a package (i.e., its name contains a dot),
+  the name is *not* mangled, e.g., the ``__foo`` in ``import __foo.bar``
+  is not mangled.
+
+- The name of an imported member, e.g., ``__f`` in ``from spam import __f``.
+
+The transformation rule is defined as follows:
+
+- The class name, with leading underscores removed and a single leading
+  underscore inserted, is inserted in front of the identifier, e.g., the
+  identifier ``__spam`` occurring in a class named ``Foo``, ``_Foo`` or
+  ``__Foo`` is transformed to ``_Foo__spam``.
+
+- If the class name consists only of underscores, the transformation is the
+  identity, e.g., the identifier ``__spam`` occurring in a class named ``_``
+  or ``__`` is left as is.
 
 .. _atom-literals:
 

Doc/tutorial/classes.rst

@@ -688,6 +688,11 @@ current class name with leading underscore(s) stripped.  This mangling is done
 without regard to the syntactic position of the identifier, as long as it
 occurs within the definition of a class.
 
+.. seealso::
+
+   The :ref:`private name mangling specifications <private-name-mangling>`
+   for details and special cases.
+
 Name mangling is helpful for letting subclasses override methods without
 breaking intraclass method calls.  For example::
 

Lib/_pyrepl/historical_reader.py

@@ -264,6 +264,7 @@ def select_item(self, i: int) -> None:
         self.historyi = i
         self.pos = len(self.buffer)
         self.dirty = True
+        self.last_refresh_cache.invalidated = True
 
     def get_item(self, i: int) -> str:
         if i != len(self.history):

Lib/_pyrepl/reader.py

@@ -58,7 +58,6 @@ def disp_str(buffer: str) -> tuple[str, list[int]]:
         elif unicodedata.category(c).startswith("C"):
             c = r"\u%04x" % ord(c)
             s.append(c)
-            b.append(str_width(c))
             b.extend([0] * (len(c) - 1))
         else:
             s.append(c)
@@ -254,6 +253,7 @@ class RefreshCache:
         pos: int = field(init=False)
         cxy: tuple[int, int] = field(init=False)
         dimensions: tuple[int, int] = field(init=False)
+        invalidated: bool = False
 
         def update_cache(self,
                          reader: Reader,
@@ -266,14 +266,19 @@ def update_cache(self,
             self.pos = reader.pos
             self.cxy = reader.cxy
             self.dimensions = reader.console.width, reader.console.height
+            self.invalidated = False
 
         def valid(self, reader: Reader) -> bool:
+            if self.invalidated:
+                return False
             dimensions = reader.console.width, reader.console.height
             dimensions_changed = dimensions != self.dimensions
             paste_changed = reader.in_bracketed_paste != self.in_bracketed_paste
             return not (dimensions_changed or paste_changed)
 
         def get_cached_location(self, reader: Reader) -> tuple[int, int]:
+            if self.invalidated:
+                raise ValueError("Cache is invalidated")
             offset = 0
             earliest_common_pos = min(reader.pos, self.pos)
             num_common_lines = len(self.line_end_offsets)

Lib/_pyrepl/unix_console.py

@@ -383,6 +383,8 @@ def get_event(self, block: bool = True) -> Event | None:
         Returns:
         - Event: Event object from the event queue.
         """
+        if not block and not self.wait(timeout=0):
+            return None
         while self.event_queue.empty():
             while True:
                 try:
@@ -397,8 +399,6 @@ def get_event(self, block: bool = True) -> Event | None:
                         raise
                 else:
                     break
-            if not block:
-                break
         return self.event_queue.get()
 
     def wait(self, timeout: float | None = None) -> bool:

Lib/asyncio/__main__.py

@@ -106,7 +106,8 @@ def run(self):
                 if os.getenv("PYTHON_BASIC_REPL"):
                     raise RuntimeError("user environment requested basic REPL")
                 if not os.isatty(sys.stdin.fileno()):
-                    raise OSError(errno.ENOTTY, "tty required", "stdin")
+                    return_code = errno.ENOTTY
+                    raise OSError(return_code, "tty required", "stdin")
 
                 # This import will fail on operating systems with no termios.
                 from _pyrepl.simple_interact import (

Lib/test/libregrtest/logger.py

@@ -43,7 +43,10 @@ def log(self, line: str = '') -> None:
 
     def get_load_avg(self) -> float | None:
         if hasattr(os, 'getloadavg'):
-            return os.getloadavg()[0]
+            try:
+                return os.getloadavg()[0]
+            except OSError:
+                pass
         if self.win_load_tracker is not None:
             return self.win_load_tracker.getloadavg()
         return None

Lib/test/test_ast.py

@@ -1821,6 +1821,12 @@ def test_get_docstring(self):
         node = ast.parse('async def foo():\n  """spam\n  ham"""')
         self.assertEqual(ast.get_docstring(node.body[0]), 'spam\nham')
 
+        node = ast.parse('async def foo():\n  """spam\n  ham"""')
+        self.assertEqual(ast.get_docstring(node.body[0], clean=False), 'spam\n  ham')
+
+        node = ast.parse('x')
+        self.assertRaises(TypeError, ast.get_docstring, node.body[0])
+
     def test_get_docstring_none(self):
         self.assertIsNone(ast.get_docstring(ast.parse('')))
         node = ast.parse('x = "not docstring"')
@@ -1845,6 +1851,9 @@ def test_get_docstring_none(self):
         node = ast.parse('async def foo():\n  x = "not docstring"')
         self.assertIsNone(ast.get_docstring(node.body[0]))
 
+        node = ast.parse('async def foo():\n  42')
+        self.assertIsNone(ast.get_docstring(node.body[0]))
+
     def test_multi_line_docstring_col_offset_and_lineno_issue16806(self):
         node = ast.parse(
             '"""line one\nline two"""\n\n'

Lib/test/test_pyrepl/support.py

@@ -38,6 +38,20 @@ def code_to_events(code: str):
         yield Event(evt="key", data=c, raw=bytearray(c.encode("utf-8")))
 
 
+def clean_screen(screen: Iterable[str]):
+    """Cleans color and console characters out of a screen output.
+
+    This is useful for screen testing, it increases the test readability since
+    it strips out all the unreadable side of the screen.
+    """
+    output = []
+    for line in screen:
+        if line.startswith(">>>") or line.startswith("..."):
+            line = line[3:]
+        output.append(line)
+    return "\n".join(output).strip()
+
+
 def prepare_reader(console: Console, **kwargs):
     config = ReadlineConfig(readline_completer=kwargs.pop("readline_completer", None))
     reader = ReadlineAlikeReader(console=console, config=config)