Welcome to cslug!

∘ MIT license ∘ PyPI ∘ Documentation ∘ Source Code ∘ Raise Bugs ∘ Get Support

Quick and painless wrapping C code into Python. The cslug package provides a thin layer on top of the built-in ctypes library, making it easier to load functions and structures from C into Python.

// hello-cslug.c

int add_1(int x) {
  return x + 1;
}

double times_2(double x) {
  return x * 2.0;
}

>>> from cslug import CSlug
>>> slug = CSlug("hello-cslug.c")
>>> slug.dll.add_1(12)
13
>>> slug.dll.times_2(-5)
-10.0

Alternatives

Mixing C with Python is nothing new - there are plenty of other ways. The most common way is to write Python extension modules. A nice comparison of the various methods can be found here. cslug aims to be the simplest although it certainly isn't the most flexible.

Using ctypes driven wrapping has both advantages and disadvantages over Python extension modules and tools that write them (such as Cython).

Advantages

• C code can be just plain high school level C. Even a hello world Python extension module is some 40 lines of hairy looking macros.

• Binaries are not linked against Python and are therefore not tied to a specific Python version. A Python extension module needs to be recompiled for every minor version of Python (3.6, 3.7, 3.8, 3.9) and for every platform (Windows, macOS, Linux) whereas a cslug binary need only be compiled for every platform.

• You can use virtually any C compiler. Python extension modules must be built with clang on macOS and MSVC on Windows. The real advantage of this is that you can use the same compiler on all platforms making them considerably more homogonuos and thus greatly reducing your chances of having to debug an issue present only on your least favourite platform.

• File sizes of binaries are very small. 1000 lines of C code equates to about 20KB of binary on Linux. Python extension modules are typically several times larger and a bare-bones Cython-ised import numpy extension is several MBs.

Disadvantages

• The surrounding Python code is less automated. A Python extension module looks and feels like a native Python module out the box complete with function metadata and docstrings whereas a small wrapper function is generally required for ctypes.

• You can't use native Python types such as list or dict within C code. Using such types will generally reduce performance down to near pure Python levels anyway so this is a small loss in practice.

• You can't use C++.

Shared Caveats

Before you commit yourself to any non Pure-Python you should bear in mind that:

• You'll need to ship wheels for every platform you wish to support otherwise users of your code will have to install a C compiler to run it. This means that you either need access to all platforms, or you will have to setup Continuous Integration to build you package on the cloud. Linux users can get around this by using Vagrant.

• Linux wheels must be built on a manylinux Docker image in order to be widely compatible with most distributions of Linux.

• Recent macOS versions will typically block or delete any binary file you produce unless you either purchase a codesign license or your software becomes famous enough to be whitelisted for you by Apple (binaries uploaded to PyPI seem to be exempt automatically). Windows users face a similar, albeit lesser, problem with Microsoft Defender.

Supported Compilers

The following OS/compiler combinations are fully supported and tested routinely.

Compiler	Linux	Windows	macOS	FreeBSD	OpenBSD	NetBSD	Cygwin/msys2	Android*
gcc	✓	✓	✓	✓	✓	✓	✓	✗
clang	✓	✓	✓	✓	✓	✗	✓	✓
MSVC	✗	✗	✗	✗	✗	✗	✗	✗
TinyCC	✓	✓	✗	✗	✗	✗	✗	✗
PGCC **	✓	✗	✗	✗	✗	✗	✗	✗

* Using Termux. ** Installable as part of the NVIDIA HPC SDK.

Installation

cslug requires a C compiler to compile C code. Its favourite compiler is gcc. Linux distributions typically come with it preinstalled. If you are on another OS or just don't have it then you should get it with mingw-w64. Windows users are recommended to download WinLibs without LLVM/Clang/LLD/LLDB (although cslug works with clang too) and add its mingw64/bin directory to PATH.

Check that you have it set up by running the following in a terminal:

gcc -v

Note

gcc is a build time dependency only. If you provide wheels for a package that contain binaries built with cslug, then your users will not need a compiler; only if they try to build your package from source.

By default, cslug will use gcc if it can find it. On macOS or FreeBSD it will switch to clang if gcc is unavailable. To use any other supported compiler, cslug respects the CC environment variable. Set it to the name or full path of your alternative compiler.

Install cslug itself with the usual:

pip install cslug

Whilst cslug is still in its 0.x versions, breaking changes may occur on minor version increments. Please don't assume forward compatibility - pick a version you like and pin it in a requirements.txt. Inspect the changelog for anything that may break your code.

Quickstart

Check out our quickstart page on readthedocs to get started.

Credits

Hall of fame for contributions to cslug.

• 

  Huge shout out to JetBrains for PyCharm and for providing their full range of products free to open source developers. (The ability to run Python from inside a docker image with completion, debugging, and all the other bells and whistles has been a big help to this project.)

• 

  This initial creation of this package was sped up considerably by Cookiecutter and a fork of the audreyr/cookiecutter-pypackage project template.

Contents:

• Basics
  • Hello cslug
  • Making slugs
  • Compiling and Recompiling
  • Accessing Functions
  • Current Working Dir Independence
• Types and Type Safety
  • Type Checking
  • Pointer Types
• Strings and Bytes
  • Reading strings
  • Writing to strings
  • Null terminated or not null terminated?
• Structs – Almost Object-Oriented Programming
  • Source code for cards example
  • Defining a Struct
  • Using a Struct in Python
  • Passing a Struct from Python to C
  • Passing a Struct from C to Python
  • Warning for Structs Containing Pointers
• Buffers and Arrays
  • Buffers
  • Arrays
• NumPy Arrays
  • Basic 1D Examples
  • Contiguity
  • Data types
  • Multidimensional arrays
  • Vectorization
• Accessing Global Variables and Constants
  • An integer
  • Other basic types
  • String, bytes and arrays
• Exceptions in C
• Headers – Working with Multiple Files
  • Pre-waffle: What headers are for
  • Auto-generating header files
  • Sharing constants between Python and C
  • Add #includes to generated headers
  • Add arbitrary code to generated headers
• Access the C Standard Library
  • assert.h
  • ctype.h
  • locale.h
  • math.h
  • regex.h
  • signal.h
  • stdarg.h
  • stdio.h
  • stdlib.h
  • string.h
  • strings.h
  • time.h
  • wchar.h
  • wctype.h
• Customising C Compilation
  • Select a C compiler
  • Add compiler flags
  • Minimum OSX version
  • Architectures for macOS
• Packaging with setuptools
  • Quick setup
  • contains-slugs
  • Compile on setup.py build.
  • Specify build-time dependencies
  • Data files for source distributions (sdists)
  • Data files for binary distributions (wheels)
  • Platform specific wheel tag
• C++
• Tips and Tricks
  • Return multiple values from a function
• Glossary
• CSlug API Reference
  • Module contents
  • Submodules
• Changelog
  • v0.7.0
  • v0.6.0
  • v0.5.2
  • v0.5.1
  • v0.5.0
  • v0.4.1
  • v0.4.0
  • v0.3.0
  • v0.2.0
  • v0.1.2
  • v0.1.1
  • v0.1.0

Indices and tables

• Index

• Module Index

• Search Page