Add _c_extension.pyi to template. Expand on Cython documentation.

Author: BrianPugh

README.rst

@@ -87,7 +87,7 @@ Cython
 ======
 This template has an option to add boilerplate for Cython_.
 Cython is a programming language that simplifies the creation of C extensions for Python.
-The Cython documentation is quite good; the aim of this section is to explain what this
+The `Cython documentation is quite good <https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html>`_; the aim of this section is to explain what this
 template sets up, and what actions will still need to be performed by you.
 This explanation assumes you are familiar with C.
 Replace any reference here to ``pythontemplate`` with your project name.
@@ -97,31 +97,46 @@ Replace any reference here to ``pythontemplate`` with your project name.
 
 2. Update ``pythontemplate/cpythontemplate.pxd`` with header information from the files in (1).
    Example of common definitions (functions, structs, and enums) are provided.
-   Think of ``*.pxd`` as a header file that allows Cython ``.pyx`` code to access pure C files.
-   This file will be compiled into a package that can be imported in a ``.pyx`` file via ``cimport``.
-   If you don't plan on using any explicit C files, you may delete this file.
+   Think of ``*.pxd`` as a header file that allows Cython ``.pyx`` code to access pure C ``.c`` files.
+   This file will be compiled into a package of the same name that can be imported in a ``.pyx`` file via ``cimport``.
+   If you don't plan on using any explicit C files, you may delete this file and the ``_c_src`` directory.
 
 3. Add Cython code to ``pythontemplate/_c_extension.pyx``. Some class starter code is provided.
    This is where a good pythonic interface (functions and classes) should be written.
 
-4. Optionally tweak ``build.py`` (runs at setup/installation) with compiler options.
+4. If adding type hints, update ``pythontemplate/_c_extension.pyi`` to reflect your ``.pyx`` implementation.
+
+5. Optionally tweak ``build.py`` (runs at setup/installation) with compiler options.
    The default ``build.py`` offers a good, working starting point for most projects and performs the following:
 
    a. Recursively searches for all C files in ``pythontemplate/_c_src/``.
       To change this action, modify the variable ``c_files``.
 
    b. Compiles the code defined in ``_c_extension.pyx`` into a shared object file.
 
-   c. Adds ``pythontemplate`` and ``pythontemplate/_c_src`` to the Include Path (variable ``include_dirs``).
+   c. Adds ``pythontemplate`` and ``pythontemplate/_c_src`` to the Include Path (python variable ``include_dirs``).
 
    d. If your codebase contains a slower, python implementation of your Cython code,
       we can allow building to fail by uncommenting the ``allowed_to_fail`` logic at the top.
+      The logic checks for the environment variable ``CIBUILDWHEEL`` because we don't want to allow
+      build failures in our CI when creating pre-built wheels that we upload to PyPI.
 
-5. The Github Action workflow defined in ``.github/workflows/build_wheels.yaml`` will create pre-built
+6. The Github Action workflow defined in ``.github/workflows/build_wheels.yaml`` will create pre-built
    binaries for all major Python versions, operating systems, and computer architectures.
    It will also create a Source Distribution (sdist).
-   Finally, on git semver tags (``vX.X.X``), it will upload all the resulting wheels to PyPI.
+   All of these distributions will be uploaded to the github action job page.
+   On git semver tags (``vX.X.X``), they will be uploaded to PyPI.
+
+When developing, you must re-run ``poetry-install`` to re-compile changes made in C/Cython code.
+The resulting, built Cython code will be importable from ``pythontemplate._c_extension``, so it may be
+good to add something like the following to your ``pythontemplate/__init__.py``:
+
+.. code-block:: python
 
+   __all__ = [
+      "Foo",
+   ]
+   from pythontemplate._c_extension import Foo
 
 Reference
 =========

bootstrap

@@ -83,6 +83,7 @@ def validate_input(prompt, validate=None, default=""):
             break
         except BadResponseError as e:
             print(f'"{response}" {e}')
+            print('To disable these validation checks, run "./bootstrap --no-verify"')
     return response
 
 
@@ -224,6 +225,7 @@ def main():
     if not is_typed:
         # Remove the py.typed file
         Path("pythontemplate/py.typed").unlink()
+        Path("pythontemplate/_c_extension.pyi").unlink()
 
     if not include_cli:
         # Delete CLI-replated files & config
@@ -256,9 +258,11 @@ def main():
             ".github/workflows/build_wheels.yaml",
             "build.py",
             "pythontemplate/_c_src",
+            "pythontemplate/_c_extension.pyx",
+            "pythontemplate/cpythontemplate.pxd",
+            # Do not include "pythontemplate/_c_extension.pyi" here,
+            # it is removed in the ``is_typed`` section above.
         ]
-        paths_to_delete.extend(Path("pythontemplate").rglob("*.pyx"))
-        paths_to_delete.extend(Path("pythontemplate").rglob("*.pxd"))
 
         for path_to_delete in paths_to_delete:
             path_to_delete = Path(path_to_delete)

build.py

@@ -2,9 +2,10 @@
 import shutil
 from pathlib import Path
 
-# Uncommend if your library can still function if extensions fail to compile.
-allowed_to_fail = False
+# Uncomment if library can still function if extensions fail to compile (e.g. slower, python fallback).
+# Don't allow failure if cibuildwheel is running.
 # allowed_to_fail = os.environ.get("CIBUILDWHEEL", "0") != "1"
+allowed_to_fail = False
 
 
 def build_cython_extensions():

pythontemplate/_c_extension.pyi

@@ -0,0 +1,5 @@
+class Foo:
+    def __init__(self): ...
+    def __call__(self): ...
+
+def divide(x: float, y: float) -> float: ...

pythontemplate/_c_extension.pyx

@@ -1,21 +1,27 @@
-cimport cpythontemplate
-# Invoke PyErr_CheckSignals occasionally if your C code runs long.
+cimport cpythontemplate  # See cpythontemplate.pxd
+# Invoke PyErr_CheckSignals() occasionally if your C code runs long.
 # This allows your code to be interrupted via ctrl+c.
 from cpython.exc cimport PyErr_CheckSignals
 from cpython.mem cimport PyMem_Malloc, PyMem_Free
 from libc.stddef cimport size_t
 
 
 cdef class Foo:
+    """Pythonic interface to the C "foo" struct."""
     cdef cpythontemplate.foo_t * _object
 
     def __cinit__(self):
-        # Allocate objects here
+        # Automatically called before __init__.
+        # All arguments passed to __init__ are also passed to __cinit__.
+        #    * As a convenience, if __cinit__() takes no arguments (other than self), it will
+        #      ignore arguments passed to the constructor without complaining about signature mismatch.
+        # Allocate memory for C objects here.
         self._object = <cpythontemplate.foo_t *>PyMem_Malloc(sizeof(cpythontemplate.foo_t))
         if self._object is NULL:
             raise MemoryError
 
     def __dealloc__(self):
+        # Should "undo" __cinit__
         PyMem_Free(self._object)
 
     def __init__(self):
@@ -24,3 +30,11 @@ cdef class Foo:
     def __call__(self):
         # invoke increment
         cpythontemplate.foo_increment(self._object)
+
+# Functions declared with cpdef are visible to both cython and python.
+# https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html#python-functions-vs-c-functions
+# https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html#error-return-values
+cpdef float divide(float x, float y) except? 1.23:
+    if y == 0.0:
+        raise ZeroDivisionError
+    return x / y