Cython sample module

This project is an example of a module that can be built using Cython. It is an upgrade from a similar model developed by Arin Khare.

Structure

The structure of this project is as follows:

.
├── cython_example
│   ├── dataset
│   ├── hello.pyx
│   └── matrix
|       ├── matrix.pyx
|       ├── norm1.pyx
|       └── trace.pyx
├── MANIFEST.in
├── pyproject.toml
├── README.md
├── test
│   └── test.py
└── setup.py

Let me describe the individual components:

*.pyx are files that will be compiled to native code from Cython/Python sources.
dataset is an example of a file that will be installed raw.
hello.pxd is a Cython file that will be compiled to a module with the path cython_example.hello
matrix.pyx is a Cython file that joins two other files, norm1.pyx and trace.pyx, which will be joined under the same submodule, cython_example.matrix
MANIFEST.in enumerates additional files that need to be installed in the package.
pyproject.toml lists packages required to build this module (Cython, to start with), but which are not required for execution.
README.md is this long description.
setup.py is the Python program that builds the module and assists pip with the installation.

Building and installing from sources

Using a virtual environment

The canonical way to build and install the package is to use setuptools with a build system. In Anaconda, this means you have to install

conda install setuptools build

Then you can issue the command

python -m build

from within the directory of this project. This command will create a new environment only with the libraries indicated in pyproject.toml and build your extension there.

The binary of this build process will be stored as dist/cython_example-*.whl, with some intermediate characters in ‘*’ that represent the version of python and operating system or platform it was built for. You can install this binary on your system using

pip install dist/cython_example*.whl

Note that if you already installed a previous version, you can use the argument --force after install to force reinstalling the package.

Using setuptools

Alternatively, you can use

python setup.py sdist bdist_wheel

This requires that you have already installed the build dependencies enumerated in pyproject.toml.

Trying out the package

The file test/test.py contains an example of a program that invokes all functions from all modules installed in cython_example. Note how the functions norm1 and test are directly available form within the matrix submodule, because of the inline structure.