aeroevan / cython-template-impl

A template to quickly get you creating an open-source python library or project with linting, static analysis, CI, and CD to PyPi.

Usage

To use this template, click the green "Use this template" button in the github web interface. Then run:

git clone YOUR_REPO
# then cd into your local repo, and run:
./bootstrap

And follow the on-screen prompts. bootstrap uses some git data (like detecting your username and repository name), so cloning the repo generated from the template is necessary.

Compatibility

This template only works on MacOS/Linux/WSL, it will not work natively on windows. The resulting project, however, may be windows-compatible.

Features

• Features dependent if project is a library or a standalone project.
• Poetry support.
  • If not installed, Poetry will automatically be installed when running bootstrap.
  • Poetry Dynamic Versioning_ - Dynamically handles your project version based on git tags.
• Optional command line interface boilerplate using typer.
• Optional C binding support via Cython.
• Sphinx + ReadTheDocs.
  • To setup, goto ReadTheDocs Dashboard and click on "Import a Project".
• Pre-commit linting and static analysis. The following are pre-configured:
  • Black - Code formatter and linter.
  • Ruff - An extremely fast Python linter.
  • Creosote - Identifies unused dependencies.
  • Codespell - Checks code for common misspellings.
  • Pyright - Static type checker.
• Docker support for standalone projects.
• GitHub actions for:
  • Run pre-commit on pull requests and commits to main.
  • Run unit tests, coverage, and verify docs build on pull requests and commits to main.
    • Goto your Codecov Dashboard and add your repo.
  • Build and upload wheels to PyPi on semver tags vX.Y.Z.
    • Add your PyPi API token to your GitHub secrets for key PYPI_TOKEN.
  • Build and upload docker images to Dockerhub.
    • Add your Dockerhub username and token to your GitHub secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN.

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 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.

1. Place all C and header files in the pythontemplate/_c_src directory. If you don't plan on using any explicit C files, you may delete this directory.
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.
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. The default build.py offers a good, working starting point for most projects and performs the following:
   1. Recursively searches for all C files in pythontemplate/_c_src/. To change this action, modify the variable c_files.
   2. Compiles the code defined in _c_extension.pyx into a shared object file.
   3. Adds pythontemplate and pythontemplate/_c_src to the Include Path (variable include_dirs).
   4. 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.
5. 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.

Reference

If you find this in the git history of a project and you like the structure, visit this template at https://github.com/BrianPugh/python-template .