Merge branch 'pdb-cli-fix-error-handling' of github.com:chgnrdv/cpyth…

…on into pdb-cli-fix-error-handling

Doc/c-api/dict.rst

@@ -79,12 +79,9 @@ Dictionary Objects
 
 .. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
 
-   .. index:: single: PyUnicode_FromString()
-
-   Insert *val* into the dictionary *p* using *key* as a key. *key* should
-   be a :c:expr:`const char*` UTF-8 encoded bytes string.  The key object is created using
-   ``PyUnicode_FromString(key)``.  Return ``0`` on success or ``-1`` on
-   failure.  This function *does not* steal a reference to *val*.
+   This is the same as :c:func:`PyDict_SetItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
@@ -97,10 +94,9 @@ Dictionary Objects
 
 .. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
 
-   Remove the entry in dictionary *p* which has a key specified by the UTF-8
-   encoded bytes string *key*.
-   If *key* is not in the dictionary, :exc:`KeyError` is raised.
-   Return ``0`` on success or ``-1`` on failure.
+   This is the same as :c:func:`PyDict_DelItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)

Doc/c-api/mapping.rst

@@ -28,9 +28,9 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
 .. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
 
-   Return element of *o* corresponding to the string *key* or ``NULL`` on failure.
-   This is the equivalent of the Python expression ``o[key]``.
-   See also :c:func:`PyObject_GetItem`.
+   This is the same as :c:func:`PyObject_GetItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyMapping_GetOptionalItem(PyObject *obj, PyObject *key, PyObject **result)
@@ -50,38 +50,30 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
 
 .. c:function:: int PyMapping_GetOptionalItemString(PyObject *obj, const char *key, PyObject **result)
 
-   Variant of :c:func:`PyMapping_GetItemString` which doesn't raise
-   :exc:`KeyError` if the key is not found.
-
-   If the key is found, return ``1`` and set *\*result* to a new
-   :term:`strong reference` to the corresponding value.
-   If the key is not found, return ``0`` and set *\*result* to ``NULL``;
-   the :exc:`KeyError` is silenced.
-   If an error other than :exc:`KeyError` is raised, return ``-1`` and
-   set *\*result* to ``NULL``.
+   This is the same as :c:func:`PyMapping_GetOptionalItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    .. versionadded:: 3.13
 
 
 .. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
 
-   Map the string *key* to the value *v* in object *o*.  Returns ``-1`` on
-   failure.  This is the equivalent of the Python statement ``o[key] = v``.
-   See also :c:func:`PyObject_SetItem`.  This function *does not* steal a
-   reference to *v*.
+   This is the same as :c:func:`PyObject_SetItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
 
-   Remove the mapping for the object *key* from the object *o*.  Return ``-1``
-   on failure.  This is equivalent to the Python statement ``del o[key]``.
    This is an alias of :c:func:`PyObject_DelItem`.
 
 
 .. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
 
-   Remove the mapping for the string *key* from the object *o*.  Return ``-1``
-   on failure.  This is equivalent to the Python statement ``del o[key]``.
+   This is the same as :c:func:`PyObject_DelItem`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
@@ -90,20 +82,27 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
    This is equivalent to the Python expression ``key in o``.
    This function always succeeds.
 
-   Note that exceptions which occur while calling the :meth:`~object.__getitem__`
-   method will get suppressed.
-   To get error reporting use :c:func:`PyObject_GetItem()` instead.
+   .. note::
+
+      Exceptions which occur when this calls :meth:`~object.__getitem__`
+      method are silently ignored.
+      For proper error handling, use :c:func:`PyMapping_GetOptionalItem` or
+      :c:func:`PyObject_GetItem()` instead.
 
 
 .. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
 
-   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
-   This is equivalent to the Python expression ``key in o``.
-   This function always succeeds.
+   This is the same as :c:func:`PyMapping_HasKey`, but *key* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
+
+   .. note::
 
-   Note that exceptions which occur while calling the :meth:`~object.__getitem__`
-   method and creating a temporary string object will get suppressed.
-   To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
+      Exceptions that occur when this calls :meth:`~object.__getitem__`
+      method or while creating the temporary :class:`str`
+      object are silently ignored.
+      For proper error handling, use :c:func:`PyMapping_GetOptionalItemString` or
+      :c:func:`PyMapping_GetItemString` instead.
 
 
 .. c:function:: PyObject* PyMapping_Keys(PyObject *o)

Doc/c-api/object.rst

@@ -43,15 +43,15 @@ Object Protocol
 
 .. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
 
-   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
-   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
-   always succeeds.
+   This is the same as :c:func:`PyObject_HasAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    .. note::
 
       Exceptions that occur when this calls :meth:`~object.__getattr__` and
-      :meth:`~object.__getattribute__` methods or while creating the temporary :class:`str`
-      object are silently ignored.
+      :meth:`~object.__getattribute__` methods or while creating the temporary
+      :class:`str` object are silently ignored.
       For proper error handling, use :c:func:`PyObject_GetOptionalAttrString`
       or :c:func:`PyObject_GetAttrString` instead.
 
@@ -68,9 +68,9 @@ Object Protocol
 
 .. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
 
-   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
-   value on success, or ``NULL`` on failure. This is the equivalent of the Python
-   expression ``o.attr_name``.
+   This is the same as :c:func:`PyObject_GetAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    If the missing attribute should not be treated as a failure, you can use
    :c:func:`PyObject_GetOptionalAttrString` instead.
@@ -93,15 +93,9 @@ Object Protocol
 
 .. c:function:: int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);
 
-   Variant of :c:func:`PyObject_GetAttrString` which doesn't raise
-   :exc:`AttributeError` if the attribute is not found.
-
-   If the attribute is found, return ``1`` and set *\*result* to a new
-   :term:`strong reference` to the attribute.
-   If the attribute is not found, return ``0`` and set *\*result* to ``NULL``;
-   the :exc:`AttributeError` is silenced.
-   If an error other than :exc:`AttributeError` is raised, return ``-1`` and
-   set *\*result* to ``NULL``.
+   This is the same as :c:func:`PyObject_GetOptionalAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    .. versionadded:: 3.13
 
@@ -129,10 +123,9 @@ Object Protocol
 
 .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
 
-   Set the value of the attribute named *attr_name*, for object *o*, to the value
-   *v*. Raise an exception and return ``-1`` on failure;
-   return ``0`` on success.  This is the equivalent of the Python statement
-   ``o.attr_name = v``.
+   This is the same as :c:func:`PyObject_SetAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
    If *v* is ``NULL``, the attribute is deleted, but this feature is
    deprecated in favour of using :c:func:`PyObject_DelAttrString`.
@@ -158,8 +151,9 @@ Object Protocol
 
 .. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
 
-   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
-   This is the equivalent of the Python statement ``del o.attr_name``.
+   This is the same as :c:func:`PyObject_DelAttr`, but *attr_name* is
+   specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+   rather than a :c:expr:`PyObject*`.
 
 
 .. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)

Doc/library/datetime.rst

@@ -37,6 +37,10 @@ on efficient attribute extraction for output formatting and manipulation.
    Package `dateutil <https://dateutil.readthedocs.io/en/stable/>`_
       Third-party library with expanded time zone and parsing support.
 
+   Package `DateType <https://pypi.org/project/datetype/>`_
+      Third-party library that introduces distinct static types to e.g. allow static type checkers
+      to differentiate between naive and aware datetimes.
+
 .. _datetime-naive-aware:
 
 Aware and Naive Objects

Doc/library/doctest.rst

@@ -1409,6 +1409,27 @@ DocTestParser objects
       identifying this string, and is only used for error messages.
 
 
+TestResults objects
+^^^^^^^^^^^^^^^^^^^
+
+
+.. class:: TestResults(failed, attempted)
+
+   .. attribute:: failed
+
+      Number of failed tests.
+
+   .. attribute:: attempted
+
+      Number of attempted tests.
+
+   .. attribute:: skipped
+
+      Number of skipped tests.
+
+      .. versionadded:: 3.13
+
+
 .. _doctest-doctestrunner:
 
 DocTestRunner objects
@@ -1427,7 +1448,7 @@ DocTestRunner objects
    passing a subclass of :class:`OutputChecker` to the constructor.
 
    The test runner's display output can be controlled in two ways. First, an output
-   function can be passed to :meth:`TestRunner.run`; this function will be called
+   function can be passed to :meth:`run`; this function will be called
    with strings that should be displayed.  It defaults to ``sys.stdout.write``.  If
    capturing the output is not sufficient, then the display output can be also
    customized by subclassing DocTestRunner, and overriding the methods
@@ -1448,6 +1469,10 @@ DocTestRunner objects
    runner compares expected output to actual output, and how it displays failures.
    For more information, see section :ref:`doctest-options`.
 
+   The test runner accumulates statistics. The aggregated number of attempted,
+   failed and skipped examples is also available via the :attr:`tries`,
+   :attr:`failures` and :attr:`skips` attributes. The :meth:`run` and
+   :meth:`summarize` methods return a :class:`TestResults` instance.
 
    :class:`DocTestParser` defines the following methods:
 
@@ -1500,7 +1525,8 @@ DocTestRunner objects
    .. method:: run(test, compileflags=None, out=None, clear_globs=True)
 
       Run the examples in *test* (a :class:`DocTest` object), and display the
-      results using the writer function *out*.
+      results using the writer function *out*. Return a :class:`TestResults`
+      instance.
 
       The examples are run in the namespace ``test.globs``.  If *clear_globs* is
       true (the default), then this namespace will be cleared after the test runs,
@@ -1519,12 +1545,29 @@ DocTestRunner objects
    .. method:: summarize(verbose=None)
 
       Print a summary of all the test cases that have been run by this DocTestRunner,
-      and return a :term:`named tuple` ``TestResults(failed, attempted)``.
+      and return a :class:`TestResults` instance.
 
       The optional *verbose* argument controls how detailed the summary is.  If the
       verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
       used.
 
+   :class:`DocTestParser` has the following attributes:
+
+   .. attribute:: tries
+
+      Number of attempted examples.
+
+   .. attribute:: failures
+
+      Number of failed examples.
+
+   .. attribute:: skips
+
+      Number of skipped examples.
+
+      .. versionadded:: 3.13
+
+
 .. _doctest-outputchecker:
 
 OutputChecker objects

Doc/library/unittest.mock-examples.rst

@@ -579,14 +579,14 @@ Partial mocking
 In some tests I wanted to mock out a call to :meth:`datetime.date.today`
 to return a known date, but I didn't want to prevent the code under test from
 creating new date objects. Unfortunately :class:`datetime.date` is written in C, and
-so I couldn't just monkey-patch out the static :meth:`date.today` method.
+so I couldn't just monkey-patch out the static :meth:`datetime.date.today` method.
 
 I found a simple way of doing this that involved effectively wrapping the date
 class with a mock, but passing through calls to the constructor to the real
 class (and returning real instances).
 
 The :func:`patch decorator <patch>` is used here to
-mock out the ``date`` class in the module under test. The :attr:`side_effect`
+mock out the ``date`` class in the module under test. The :attr:`~Mock.side_effect`
 attribute on the mock date class is then set to a lambda function that returns
 a real date. When the mock date class is called a real date will be
 constructed and returned by ``side_effect``. ::
@@ -766,8 +766,8 @@ mock has a nice API for making assertions about how your mock objects are used.
     >>> mock.foo_bar.assert_called_with('baz', spam='eggs')
 
 If your mock is only being called once you can use the
-:meth:`assert_called_once_with` method that also asserts that the
-:attr:`call_count` is one.
+:meth:`~Mock.assert_called_once_with` method that also asserts that the
+:attr:`~Mock.call_count` is one.
 
     >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
     >>> mock.foo_bar()
@@ -835,7 +835,7 @@ One possibility would be for mock to copy the arguments you pass in. This
 could then cause problems if you do assertions that rely on object identity
 for equality.
 
-Here's one solution that uses the :attr:`side_effect`
+Here's one solution that uses the :attr:`~Mock.side_effect`
 functionality. If you provide a ``side_effect`` function for a mock then
 ``side_effect`` will be called with the same args as the mock. This gives us an
 opportunity to copy the arguments and store them for later assertions. In this
@@ -971,7 +971,8 @@ We can do this with :class:`MagicMock`, which will behave like a dictionary,
 and using :data:`~Mock.side_effect` to delegate dictionary access to a real
 underlying dictionary that is under our control.
 
-When the :meth:`__getitem__` and :meth:`__setitem__` methods of our ``MagicMock`` are called
+When the :meth:`~object.__getitem__` and :meth:`~object.__setitem__` methods
+of our ``MagicMock`` are called
 (normal dictionary access) then ``side_effect`` is called with the key (and in
 the case of ``__setitem__`` the value too). We can also control what is returned.