Editing docs from handwritten notes. Up to page 98.

Author: paulross

doc/sphinx/source/canonical_function.rst

@@ -150,6 +150,12 @@ Notice the ``except:`` block falls through to the ``finally:`` block.
 .. index::
     single: C Functions; Full Coding Pattern
 
+.. raw:: latex
+
+    [Continued on the next page]
+
+    \pagebreak
+
 The Function Code as One
 ========================
 

doc/sphinx/source/capsules.rst

@@ -366,15 +366,15 @@ In this case we want to create a subclass of the ``datetime.datetime`` object th
 `naive` datetimes.
 
 Here is the C Extension code to create a ``datetimetz`` module and a ``datetimetz.datetimetz`` object.
-This code is lightly edited for clarity and works with Python 3.10+.
-The actual code is in ``src/cpy/Capsules/datetimetz.c`` (which works with Python 3.9 as well)
+This code is lightly edited for clarity and works with Python 3.10+ (using the modern API).
+The actual code is in ``src/cpy/Capsules/datetimetz.c`` (which works with the Python 3.9 API as well)
 and the tests are in ``tests/unit/test_c_capsules.py``.
 
 --------------------------------
 Writing the Code for the Object
 --------------------------------
 
-Firstly the declaration of the timezone aware datetime, it just inherits from ``datetime.datetime``:
+Firstly the declaration of the timezone aware datetime, it just inherits from ``datetime.datetime`` :
 
 .. code-block:: c
 
@@ -421,8 +421,8 @@ Now the code for creating a new instance:
     }
 
 So far a new ``datetimetz`` object must be created with a ``tzinfo`` but the ``datetime.datetime`` has an API
-``replace`` that creates a new datetime with different properties, including ``tzinfo``.
-We need to guard against the user trying to change the timezone.
+``replace()`` that creates a new datetime with different properties, including ``tzinfo``.
+We need to guard against the user trying to change the timezone to None.
 To do this we call the super class function and then check, and raise, if a ``tzinfo`` is absent.
 This uses the utility function that call Python's ``super()`` function.
 That code is in ``src/cpy/Util/py_call_super.h`` and ``src/cpy/Util/py_call_super.c``:
@@ -473,6 +473,10 @@ Finally the module code:
             .m_size = -1,
     };
 
+Initialise the module, this is when we use the existing capsule:
+
+.. code-block:: c
+
     PyMODINIT_FUNC
     PyInit_datetimetz(void) {
         PyObject *m = PyModule_Create(&datetimetzmodule);
@@ -635,6 +639,19 @@ The error is handled correctly by the superclass.
             d.tzinfo = None
         assert err.value.args[0] == "attribute 'tzinfo' of 'datetime.datetime' objects is not writable"
 
+Check that ``.replace()`` works as expected with ``tzinfo``:
+
+.. code-block:: python
+
+    def test_datetimetz_datetimetz_replace_raises_tzinfo():
+        d = datetimetz.datetimetz(
+            2024, 7, 15, 10, 21, 14,
+            tzinfo=zoneinfo.ZoneInfo('Europe/London')
+        )
+        with pytest.raises(TypeError) as err:
+            d.replace(tzinfo=None)
+        assert err.value.args[0] == 'No time zone provided.'
+
 Some equality tests.
 We want to fail when comparing our ``datetimetz`` with a naive ``datatime`` object.
 
@@ -659,7 +676,7 @@ We want to fail when comparing our ``datetimetz`` with a naive ``datatime`` obje
         d_no_tz = datetime.datetime(2024, 7, 15, 10, 21, 14)
         assert d_no_tz != d
 
-Some datetime comparison tests that show our ``datetimetz`` inter-operates correctly with itself and a ``datetime``
+Some datetime subtraction tests that show our ``datetimetz`` inter-operates correctly with itself and a ``datetime``
 object.
 
 .. code-block:: python
@@ -724,16 +741,3 @@ object.
             d_tz - d
         assert err.value.args[0] == "can't subtract offset-naive and offset-aware datetimes"
 
-Check that ``.replace()`` works as expected with ``tzinfo``:
-
-.. code-block:: python
-
-    def test_datetimetz_datetimetz_replace_raises_tzinfo():
-        d = datetimetz.datetimetz(
-            2024, 7, 15, 10, 21, 14,
-            tzinfo=zoneinfo.ZoneInfo('Europe/London')
-        )
-        with pytest.raises(TypeError) as err:
-            d.replace(tzinfo=None)
-        assert err.value.args[0] == 'No time zone provided.'
-

doc/sphinx/source/exceptions.rst

@@ -159,19 +159,33 @@ Creating Specialised Exceptions
 ---------------------------------
 
 Often you need to create an Exception class that is specialised to a particular module.
+The following C code is equivalent to the Python code:
+
+.. code-block:: python
+
+    class ExceptionBase(Exception):
+        pass
+
+    class SpecialisedError(ExceptionBase):
+        pass
+
 This can be done quite easily using either the ``PyErr_NewException`` or the ``PyErr_NewExceptionWithDoc`` functions.
 These create new exception classes that can be added to a module.
 For example:
 
 .. code-block:: c
 
     /** Specialise exceptions base exception. */
-    static PyObject *ExceptionBase = 0;
+    static PyObject *ExceptionBase = NULL;
     /** Specialise exceptions derived from base exception. */
-    static PyObject *SpecialisedError = 0;
+    static PyObject *SpecialisedError = NULL;
 
     /* NOTE: Functions that might raise one of these exceptions will go here. See below. */
 
+Now define the module, ``cExceptions_methods`` is explained later:
+
+.. code-block:: c
+
     static PyModuleDef cExceptions_module = {
             PyModuleDef_HEAD_INIT,
             "cExceptions",
@@ -181,6 +195,10 @@ For example:
             NULL, NULL, NULL, NULL,
     };
 
+Initialise the module, this registers the exception types and the class hierarchy:
+
+.. code-block:: c
+
     PyMODINIT_FUNC
     PyInit_cExceptions(void) {
         PyObject *m = PyModule_Create(&cExceptions_module);
@@ -294,3 +312,20 @@ Or fish it out of the module (this will be slower):
         }
         return NULL;
     }
+
+Here is some test code from ``tests/unit/test_c_exceptions.py``:
+
+.. code-block:: python
+
+    from cPyExtPatt import cExceptions
+
+    def test_raise_exception_base():
+        with pytest.raises(cExceptions.ExceptionBase) as err:
+            cExceptions.raise_exception_base()
+        assert err.value.args[0] == 'One 1 two 2 three 3.'
+
+
+    def test_raise_specialised_error():
+        with pytest.raises(cExceptions.SpecialisedError) as err:
+            cExceptions.raise_specialised_error()
+        assert err.value.args[0] == 'One 1 two 2 three 3.'

doc/sphinx/source/module_globals.rst

@@ -131,7 +131,7 @@ The dict is added in a separate C function merely for readability:
         Py_XDECREF(val);
         key = PyBytes_FromString("123");
         val = PyLong_FromLong(123);
-        if (PyDict_SetItem(pMap, PyBytes_FromString("123"), PyLong_FromLong(123))) {
+        if (PyDict_SetItem(pMap, key, value)) {
             goto except;
         }
         Py_XDECREF(key);

doc/sphinx/source/parsing_arguments.rst

@@ -532,6 +532,8 @@ The complete C code is:
         return Py_BuildValue("y#", arg.buf, arg.len);
     }
 
+See ``tests/unit/test_c_parse_args.py`` for some Python uses of this code.
+
 .. index::
     single: Parsing Arguments Example; Positional Only Arguments
     single: Parsing Arguments Example; Keyword Only Arguments
@@ -690,6 +692,11 @@ Being Pythonic with Default Mutable Arguments
 
 If the arguments default to some C fundamental type the code above is fine.
 However if the arguments default to Python objects then a little more work is needed.
+
+.. note::
+
+    See :ref:`cpp_and_cpython.handling_default_arguments` for a way of simplifying this with C++.
+
 Here is a function that has a tuple and a dict as default arguments, in other words the Python signature:
 
 .. code-block:: python

src/cpy/cExceptions.c

@@ -56,9 +56,9 @@ static PyObject *raise_error_overwrite(PyObject *Py_UNUSED(module)) {
 }
 
 /** Specialise exceptions base exception. */
-static PyObject *ExceptionBase = 0;
+static PyObject *ExceptionBase = NULL;
 /** Specialise exceptions derived from base exception. */
-static PyObject *SpecialisedError = 0;
+static PyObject *SpecialisedError = NULL;
 
 
 /** Raises a ExceptionBase. */