small fixes

Author: Technologicat

CHANGELOG.md

@@ -1,3 +1,7 @@
+## [v0.1.3]
+ - fix terminology (subpackage, not submodule)
+ - provide pruned-down version [setup-purepython.py](setup-purepython.py) for pure Python projects. This is mainly for comparison, as many templates already exist for this.
+
 ## [v0.1.2]
  - fix license also in [README.md](README.md)
 

README.md

@@ -8,9 +8,11 @@ Setuptools[[1]][setuptools] has become the tool of choice[[2]][packaging] for pa
 
 For packages to be distributed (especially through [PyPI](https://pypi.python.org/pypi)), setuptools is preferable, since the documentation on distributing packages[[3]][distributing] assumes that is what the developer uses. Also, [setuptools adds dependency resolution](http://stackoverflow.com/questions/25337706/setuptools-vs-distutils-why-is-distutils-still-a-thing) (over distutils), which is an essential feature of `pip`.
 
-This very minimal project documents the author's best guess at current best practices for the packaging and distribution of Cython projects, by piecing together information from various sources (mainly documentation and StackOverflow). Possible corrections, if any, are welcome.
+This very minimal project documents the author's best guess at current best practices for the packaging and distribution of Cython projects, by piecing together information from various sources (mainly documentation and StackOverflow). A pruned-down version for pure Python projects is also provided for comparison. Possible corrections, if any, are welcome.
 
-This is intended as a template for new Cython projects. For completeness, a minimal Cython module is included. This project is placed in the public domain so as to allow its use anywhere.
+This is intended as a template [`setup.py`](setup.py) for new Cython projects. For completeness, a minimal Cython-based example library is included, containing examples of things such as absolute cimports, subpackages, [NumPyDoc](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) style docstrings, and using [memoryviews](http://cython.readthedocs.io/en/latest/src/userguide/memoryviews.html) for passing arrays (for the last two, see [compute.pyx](mylibrary/compute.pyx)). The example in the [test/](test/) subdirectory demonstrates its usage.
+
+This project is placed under The Unlicense so as to allow its use anywhere. Code snippets based on StackOverflow answers are credited by providing the original links.
 
 This is similar to [simple-cython-example](https://github.com/thearn/simple-cython-example), but different. Here the focus is on numerical scientific projects, where a custom Cython extension (containing all-new code) can bring a large speedup.
 
@@ -57,7 +59,7 @@ For `install`, the switch `--user` may be useful. As can, alternatively, running
 
 #### Binary distributions
 
-As noted in the [Python packaging guide](https://packaging.python.org/distributing/#platform-wheels), PyPI accepts platform wheels (platform-specific binary distributions) for Linux only if they conform to [the `manylinux1` ABI](https://www.python.org/dev/peps/pep-0513/), so running `python setup.py bdist_egg` on an arbitrary development machine is generally not very useful for the purposes of distribution.
+As noted in the [Python packaging guide](https://packaging.python.org/distributing/#platform-wheels), PyPI accepts platform wheels (platform-specific binary distributions) for Linux only if they conform to [the `manylinux1` ABI](https://www.python.org/dev/peps/pep-0513/), so running `python setup.py bdist_wheel` on an arbitrary development machine is generally not very useful for the purposes of distribution.
 
 For the adventurous, PyPA provides [instructions](https://github.com/pypa/manylinux) along with a Docker image.
 

mylibrary/__init__.py

@@ -5,7 +5,7 @@
 from __future__ import absolute_import
 
 # This is extracted automatically by the top-level setup.py.
-__version__ = '0.1.2'
+__version__ = '0.1.3'
 
-# add any imports here, if you wish to bring things into the library's top-level namespace.
+# add any imports here, if you wish to bring things into the library's top-level namespace when the library is imported.
 

mylibrary/compute.pyx

@@ -3,7 +3,7 @@
 # cython: wraparound  = False
 # cython: boundscheck = False
 # cython: cdivision   = True
-"""Example Cython module."""
+"""Example Cython module for numerical computation mixing libc.math and NumPy."""
 
 from __future__ import division, print_function, absolute_import
 
@@ -42,7 +42,7 @@ Return value:
     cdef int n = x.shape[0]
 
     # np.empty() is a pretty good mechanism for dynamic allocation of arrays,
-    # as long as memory allocation can be done on the Python side,
+    # as long as memory allocation can be done in Python parts of the code (no "nogil").
     #
     # If you absolutely need to dynamically allocate memory in nogil code,
     # then "from libc.stdlib cimport malloc, free", and be ready for pain.
@@ -57,7 +57,7 @@ Return value:
     # can proceed while this one is computing.
     #
     # We could also "cimport cython.parallel" and "for j in cython.parallel.prange(n):"
-    # if we wanted to link this with OpenMP.
+    # if we wanted (and then link this module with OpenMP in setup.py).
     #
     cdef int j
     with nogil:

mylibrary/dostuff.pyx

@@ -3,18 +3,18 @@
 # cython: wraparound  = False
 # cython: boundscheck = False
 # cython: cdivision   = True
-"""Example Cython module."""
+"""Example Cython module that calls a function from a subpackage of mylibrary."""
 
 from __future__ import division, print_function, absolute_import
 
 
 # Use absolute module names, even from this library itself.
 #
-cimport mylibrary.submodule.helloworld as helloworld
+cimport mylibrary.subpackage.helloworld as helloworld
 
 
 def hello(s):
-    """Python interface to mylibrary.submodule.helloworld.
+    """Python interface to mylibrary.subpackage.helloworld.
 
 This is mainly an example of absolute imports in Cython modules.
 

mylibrary/submodule/helloworld.pxd

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+#
+# Cython-level declarations for mylibrary.subpackage.helloworld, available for cimport from other Cython modules.
+
+from __future__ import absolute_import
+
+cdef void hello(str s)
+

mylibrary/submodule/helloworld.pyx

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+#
+# cython: wraparound  = False
+# cython: boundscheck = False
+# cython: cdivision   = True
+"""Example Cython module."""  # this is the Python-level docstring
+
+# Note that this is a pure Cython-level module; it has no "def" functions or Python-accessible objects.
+#
+# If this is imported to Python, the user will just see the module docstring.
+
+from __future__ import division, print_function, absolute_import
+
+# Echo the string s.
+#
+cdef void hello(str s):
+    print(s)  # this is really, really silly (providing a Cython-level cdef function that just calls Python print())
+