Added Sphinx build HTML

Contents now links to Sphinx build HTML as .md was a bit flakey.

Author: paulross

.gitignore

@@ -1,4 +1,3 @@
-doc/sphinx/build/*
 src/build/*
 *.so
 PythonExtensionPatterns/*

README.md

@@ -4,8 +4,4 @@ Examples of reliable coding of Python 'C' extensions by Paul Ross.
 
 ## Contents:
 
-* Introduction to [reference counts](doc/sphinx/source/refcount.rst) in Python C extensions.
-* Managing [exceptions](doc/sphinx/source/exceptions.rst).
-* A [canonical function pattern](doc/sphinx/source/canonical_function.rst) for C extensions.
-* Handling [function arguments](doc/sphinx/source/parsing_arguments.rst).
-* Creating, setting and getting [module globals](doc/sphinx/source/module_globals.rst).
+The [Sphinx Documentation](doc/sphinx/build/html/index.html) for this project.

doc/sphinx/build/doctrees/canonical_function.doctree

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 16bf173fae07a841c4cb05b21572d779
+tags: 645f666f9bcd5a90fca523b33c5a78b7

doc/sphinx/build/doctrees/classes.doctree

@@ -0,0 +1,185 @@
+.. toctree::
+    :maxdepth: 3
+
+
+===========================================
+A Pythonic Coding Pattern for C Functions
+===========================================
+
+To avoid all the errors we have seen it is useful to have a C coding pattern for handling ``PyObjects`` that does the following:
+
+* No early returns and a single place for clean up code.
+* Borrowed references incref'd and decref'd correctly.
+* No stale Exception from previous execution path.
+* Exceptions set and tested.
+* NULL is returned when an exception is set.
+* Non-NULL is returned when no exception is set.
+
+The basic pattern in C is similar to Python's try/except/finally pattern:
+
+.. code-block:: c
+
+    try:
+        /* Do fabulous stuff here. */
+    except:
+        /* Handle every abnormal condition and clean up. */
+    finally:
+        /* Clean up under normal conditions and return an appropriate value. */
+
+
+Firstly we set any local ``PyObject`` (s) and the return value to ``NULL``:
+
+.. code-block:: c
+
+    static PyObject *function(PyObject *arg_1) {
+        PyObject *obj_a    = NULL;
+        PyObject *ret      = NULL;
+    
+Then we have a little bit of Pythonic C - this can be omitted:
+
+.. code-block:: c
+
+        goto try; /* Pythonic 'C' ;-) */
+    try:
+
+Check that there are no lingering Exceptions:
+
+.. code-block:: c
+
+        assert(! PyErr_Occurred());
+
+An alternative check for no lingering Exceptions:
+
+.. code-block:: c
+
+        if(PyErr_Occurred()) {
+            goto except;
+        }
+
+Now we assume that any argument is a "Borrowed" reference so we increment it (we need a matching ``Py_DECREF`` before function exit, see below). The first pattern assumes a non-NULL argument.
+
+.. code-block:: c
+
+        assert(arg_1);
+        Py_INCREF(arg_1);
+
+If you are willing to accept NULL arguments then this pattern would be more suitable:
+
+.. code-block:: c
+    
+    if (arg_1) {
+        Py_INCREF(arg_1);
+    }
+    
+Of course the same test must be used when calling ``Py_DECFREF``, or just use ``Py_XDECREF``.
+
+Now we create any local objects, if they are "Borrowed" references we need to incref them. With any abnormal behaviour we do a local jump straight to the cleanup code.
+
+.. code-block:: c
+
+        /* Local object creation. */
+        /* obj_a = ...; */
+        if (! obj_a) {
+            PyErr_SetString(PyExc_ValueError, "Ooops.");
+            goto except;
+        }
+        /* If obj_a is a borrowed reference rather than a new reference. */
+        Py_INCREF(obj_a);
+
+Create the return value and deal with abnormal behaviour in the same way:
+ 
+.. code-block:: c
+
+        /* More of your code to do stuff with arg_1 and obj_a. */    
+        /* Return object creation, ret should be a new reference otherwise you are in trouble. */
+        /* ret = ...; */
+        if (! ret) {
+            PyErr_SetString(PyExc_ValueError, "Ooops again.");
+            goto except;
+        }
+
+You might want to check the contents of the return value here. On error jump to ``except:`` otherwise jump to ``finally:``.
+
+.. code-block:: c
+
+        /* Any return value checking here. */
+    
+        /* If success then check exception is clear,
+         * then goto finally; with non-NULL return value. */
+        assert(! PyErr_Occurred());
+        assert(ret);
+        goto finally;
+
+This is the except block where we cleanup any local objects and set the return value to NULL.
+
+.. code-block:: c
+
+    except:
+        /* Failure so Py_XDECREF the return value here. */
+        Py_XDECREF(ret);
+        /* Check a Python error is set somewhere above. */
+        assert(PyErr_Occurred());
+        /* Signal failure. */
+        ret = NULL;
+
+Notice the ``except:`` block falls through to the ``finally:`` block.
+
+.. code-block:: c
+
+    finally:
+        /* All _local_ PyObjects declared at the entry point are Py_XDECREF'd here.
+         * For new references this will free them. For borrowed references this
+         * will return them to their previous refcount.
+         */
+        Py_XDECREF(obj_a);
+        /* Decrement the ref count of externally supplied the arguments here.
+         * If you allow arg_1 == NULL then Py_XDECREF(arg_1). */
+        Py_DECREF(arg_1);
+        /* And return...*/
+        return ret;
+    }
+
+
+Here is the complete code with minimal comments:
+
+.. code-block:: c
+
+    static PyObject *function(PyObject *arg_1) {
+        PyObject *obj_a    = NULL;
+        PyObject *ret      = NULL;
+    
+        goto try;
+    try:
+        assert(! PyErr_Occurred());
+        assert(arg_1);
+        Py_INCREF(arg_1);
+    
+        /* obj_a = ...; */
+        if (! obj_a) {
+            PyErr_SetString(PyExc_ValueError, "Ooops.");
+            goto except;
+        }
+        /* Only do this if obj_a is a borrowed reference. */
+        Py_INCREF(obj_a);
+    
+        /* More of your code to do stuff with obj_a. */
+    
+        /* Return object creation, ret must be a new reference. */
+        /* ret = ...; */
+        if (! ret) {
+            PyErr_SetString(PyExc_ValueError, "Ooops again.");
+            goto except;
+        }
+        assert(! PyErr_Occurred());
+        assert(ret);
+        goto finally;
+    except:
+        Py_XDECREF(ret);
+        assert(PyErr_Occurred());
+        ret = NULL;
+    finally:
+        /* Only do this if obj_a is a borrowed reference. */
+        Py_XDECREF(obj_a);
+        Py_DECREF(arg_1);
+        return ret;
+    }

doc/sphinx/build/doctrees/environment.pickle

@@ -0,0 +1,89 @@
+.. highlight:: python
+    :linenothreshold: 10
+
+.. toctree::
+    :maxdepth: 3
+
+=================================
+Exception Raising 
+=================================
+
+A brief interlude on how to communicate error conditions from C code to Python.
+
+These CPython calls are the most useful:
+
+* ``PyErr_SetString(...)`` - To set an exception type with a fixed string.
+* ``PyErr_Format(...)`` - To set an exception type with a formatted string.
+* ``PyErr_Occurred()`` - To check if an exception has already been set in the flow of control.
+* ``PyErr_Clear()`` - Clearing any set exceptions, have good reason to do this!
+
+Indicating an error condition is a two stage process; your code must register an exception and then indicate failure by returning ``NULL``. Here is a C function doing just that:
+
+.. code-block:: c
+
+    static PyObject *_raise_error(PyObject *module) {
+    
+        PyErr_SetString(PyExc_ValueError, "Ooops.");
+        return NULL;
+    }
+
+You might want some dynamic information in the exception object, in that case ``PyErr_Format`` will do:
+
+.. code-block:: c
+
+    static PyObject *_raise_error_formatted(PyObject *module) {
+    
+        PyErr_Format(PyExc_ValueError,
+                     "Can not read %d bytes when offset %d in byte length %d.", \
+                     12, 25, 32
+                     );
+        return NULL;
+    }
+
+If one of the two actions is missing then the exception will not be raised correctly. For example returning ``NULL`` without setting an exception type:
+
+.. code-block:: c
+
+    /* Illustrate returning NULL but not setting an exception. */
+    static PyObject *_raise_error_bad(PyObject *module) {
+        return NULL;
+    }
+
+Executing this from Python will produce a clear error message (the C function ``_raise_error_bad()`` is mapped to the Python function ``cExcep.raiseErrBad()`` ::
+
+    >>> cExcep.raiseErrBad()
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    SystemError: error return without exception set
+
+If the opposite error is made, that is setting an exception but not signalling then the function will succeed but leave a later runtime error:
+
+.. code-block:: c
+
+    static PyObject *_raise_error_mixup(PyObject *module) {
+        PyErr_SetString(PyExc_ValueError, "ERROR: _raise_error_mixup()");
+        Py_RETURN_NONE;
+    }
+
+The confusion can arise is that if a subsequent function then tests to see if an exception is set, if so signal it. It will appear that the error is coming from the second function when actually it is from the first:
+
+.. code-block:: c
+
+    static PyObject *_raise_error_mixup_test(PyObject *module) {
+        if (PyErr_Occurred()) {
+            return NULL;
+        }
+        Py_RETURN_NONE;
+    }
+
+The other thing to note is that if there are multiple calls to ``PyErr_SetString`` only the last one counts:
+
+.. code-block:: c
+
+    static PyObject *_raise_error_overwrite(PyObject *module) {
+        PyErr_SetString(PyExc_RuntimeError, "FORGOTTEN.");
+        PyErr_SetString(PyExc_ValueError, "ERROR: _raise_error_overwrite()");
+        assert(PyErr_Occurred());
+        return NULL;
+    }
+

doc/sphinx/build/doctrees/exceptions.doctree

@@ -0,0 +1,25 @@
+.. Python Extension Patterns documentation master file, created by
+   sphinx-quickstart on Sun May 11 19:42:01 2014.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Coding Patterns for Python Extensions
+=====================================================
+
+This describes reliable patterns of coding Python Extensions in C. It covers the essentials of reference counts, exceptions and creating functions that are safe and efficient.
+
+.. toctree::
+   :maxdepth: 3
+
+   refcount
+   exceptions
+   canonical_function
+   parsing_arguments
+   module_globals
+
+
+Indices and tables
+==================
+
+* :ref:`search`
+