Merge branch 'main' into sqlite-expose-error-code

Author: Erlend E. Aasland

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*.{py,c,cpp,h,rst,md,yml}]
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+
+[*.{py,c,cpp,h}]
+indent_size = 4
+
+[*.yml]
+indent_size = 2

.gitignore

@@ -35,6 +35,7 @@ gmon.out
 .coverage
 .mypy_cache/
 .pytest_cache/
+.DS_Store
 
 *.exe
 !Lib/distutils/command/*.exe

Doc/bugs.rst

@@ -80,6 +80,10 @@ taken on the bug.
       Article which goes into some detail about how to create a useful bug report.
       This describes what kind of information is useful and why it is useful.
 
+   `Bug Writing Guidelines <https://bugzilla.mozilla.org/page.cgi?id=bug-writing.html>`_
+      Information about writing a good bug report.  Some of this is specific to the
+      Mozilla project, but describes general good practices.
+
 .. _contributing-to-python:
 
 Getting started contributing to Python yourself

Doc/c-api/exceptions.rst

@@ -100,7 +100,7 @@ For convenience, some of these functions will always return a
    This is the most common way to set the error indicator.  The first argument
    specifies the exception type; it is normally one of the standard exceptions,
    e.g. :c:data:`PyExc_RuntimeError`.  You need not increment its reference count.
-   The second argument is an error message; it is decoded from ``'utf-8``'.
+   The second argument is an error message; it is decoded from ``'utf-8'``.
 
 
 .. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)

Doc/c-api/type.rst

@@ -112,6 +112,13 @@ Type Objects
 
    .. versionadded:: 3.11
 
+.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
+
+   Return the type's qualified name. Equivalent to getting the
+   type's ``__qualname__`` attribute.
+
+   .. versionadded:: 3.11
+
 .. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
 
    Return the function pointer stored in the given slot. If the

Doc/data/refcounts.dat

@@ -2310,6 +2310,9 @@ PyType_GetFlags:PyTypeObject*:type:0:
 PyType_GetName:PyObject*::+1:
 PyType_GetName:PyTypeObject*:type:0:
 
+PyType_GetQualName:PyObject*::+1:
+PyType_GetQualName:PyTypeObject*:type:0:
+
 PyType_GetSlot:void*:::
 PyType_GetSlot:PyTypeObject*:type:0:
 PyType_GetSlot:int:slot::

Doc/data/stable_abi.dat

@@ -644,6 +644,7 @@ function,PyType_GetFlags,3.2,
 function,PyType_GetModule,3.10,
 function,PyType_GetModuleState,3.10,
 function,PyType_GetName,3.11,
+function,PyType_GetQualName,3.11,
 function,PyType_GetSlot,3.4,
 function,PyType_IsSubtype,3.2,
 function,PyType_Modified,3.2,

Doc/faq/gui.rst

@@ -14,17 +14,8 @@ Graphic User Interface FAQ
 General GUI Questions
 =====================
 
-What platform-independent GUI toolkits exist for Python?
-========================================================
-
-Depending on what platform(s) you are aiming at, there are several.  Some
-of them haven't been ported to Python 3 yet.  At least `Tkinter`_ and `Qt`_
-are known to be Python 3-compatible.
-
-.. XXX check links
-
-Tkinter
--------
+What GUI toolkits exist for Python?
+===================================
 
 Standard builds of Python include an object-oriented interface to the Tcl/Tk
 widget set, called :ref:`tkinter <Tkinter>`.  This is probably the easiest to
@@ -34,83 +25,12 @@ For more info about Tk, including pointers to the source, see the
 `Tcl/Tk home page <https://www.tcl.tk>`_.  Tcl/Tk is fully portable to the
 Mac OS X, Windows, and Unix platforms.
 
-wxWidgets
----------
-
-wxWidgets (https://www.wxwidgets.org) is a free, portable GUI class
-library written in C++ that provides a native look and feel on a
-number of platforms, with Windows, Mac OS X, GTK, X11, all listed as
-current stable targets.  Language bindings are available for a number
-of languages including Python, Perl, Ruby, etc.
-
-`wxPython <https://www.wxpython.org>`_ is the Python binding for
-wxwidgets.  While it often lags slightly behind the official wxWidgets
-releases, it also offers a number of features via pure Python
-extensions that are not available in other language bindings.  There
-is an active wxPython user and developer community.
-
-Both wxWidgets and wxPython are free, open source, software with
-permissive licences that allow their use in commercial products as
-well as in freeware or shareware.
-
-
-Qt
----
-
-There are bindings available for the Qt toolkit (using either `PyQt
-<https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide
-<https://wiki.qt.io/PySide>`_) and for KDE (`PyKDE4 <https://techbase.kde.org/Languages/Python/Using_PyKDE_4>`__).
-PyQt is currently more mature than PySide, but you must buy a PyQt license from
-`Riverbank Computing <https://www.riverbankcomputing.com/commercial/license-faq>`_
-if you want to write proprietary applications.  PySide is free for all applications.
-
-Qt 4.5 upwards is licensed under the LGPL license; also, commercial licenses
-are available from `The Qt Company <https://www.qt.io/licensing/>`_.
-
-Gtk+
-----
-
-The `GObject introspection bindings <https://wiki.gnome.org/Projects/PyGObject>`_
-for Python allow you to write GTK+ 3 applications.  There is also a
-`Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.io>`_.
-
-The older PyGtk bindings for the `Gtk+ 2 toolkit <https://www.gtk.org>`_ have
-been implemented by James Henstridge; see <http://www.pygtk.org>.
-
-Kivy
-----
-
-`Kivy <https://kivy.org/>`_ is a cross-platform GUI library supporting both
-desktop operating systems (Windows, macOS, Linux) and mobile devices (Android,
-iOS).  It is written in Python and Cython, and can use a range of windowing
-backends.
-
-Kivy is free and open source software distributed under the MIT license.
-
-FLTK
-----
-
-Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
-powerful and mature cross-platform windowing system, are available from `the
-PyFLTK project <https://pyfltk.sourceforge.io/>`_.
-
-OpenGL
-------
-
-For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
-
-
-What platform-specific GUI toolkits exist for Python?
-========================================================
-
-By installing the `PyObjc Objective-C bridge
-<https://pypi.org/project/pyobjc/>`_, Python programs can use Mac OS X's
-Cocoa libraries.
-
-:ref:`Pythonwin <windows-faq>` by Mark Hammond includes an interface to the
-Microsoft Foundation Classes and a Python programming environment
-that's written mostly in Python using the MFC classes.
-
+Depending on what platform(s) you are aiming at, there are also several
+alternatives. A `list of cross-platform
+<https://wiki.python.org/moin/GuiProgramming#Cross-Platform_Frameworks>`_ and
+`platform-specific
+<https://wiki.python.org/moin/GuiProgramming#Platform-specific_Frameworks>`_ GUI
+frameworks can be found on the python wiki.
 
 Tkinter questions
 =================

Doc/faq/programming.rst

@@ -1826,6 +1826,55 @@ For example, here is the implementation of
                 return True
         return False
 
+
+How can a subclass control what data is stored in an immutable instance?
+------------------------------------------------------------------------
+
+When subclassing an immutable type, override the :meth:`__new__` method
+instead of the :meth:`__init__` method.  The latter only runs *after* an
+instance is created, which is too late to alter data in an immutable
+instance.
+
+All of these immutable classes have a different signature than their
+parent class:
+
+.. testcode::
+
+    from datetime import date
+
+    class FirstOfMonthDate(date):
+        "Always choose the first day of the month"
+        def __new__(cls, year, month, day):
+            return super().__new__(cls, year, month, 1)
+
+    class NamedInt(int):
+        "Allow text names for some numbers"
+        xlat = {'zero': 0, 'one': 1, 'ten': 10}
+        def __new__(cls, value):
+            value = cls.xlat.get(value, value)
+            return super().__new__(cls, value)
+
+    class TitleStr(str):
+        "Convert str to name suitable for a URL path"
+        def __new__(cls, s):
+            s = s.lower().replace(' ', '-')
+            s = ''.join([c for c in s if c.isalnum() or c == '-'])
+            return super().__new__(cls, s)
+
+The classes can be used like this:
+
+.. doctest::
+
+    >>> FirstOfMonthDate(2012, 2, 14)
+    FirstOfMonthDate(2012, 2, 1)
+    >>> NamedInt('ten')
+    10
+    >>> NamedInt(20)
+    20
+    >>> TitleStr('Blog: Why Python Rocks')
+    'blog-why-python-rocks'
+
+
 How do I cache method calls?
 ----------------------------