Skip to main content

Quick and painless wrapping C code into Python

Project description

https://img.shields.io/badge/Python-%203.6%20%7C%203.7%20%7C%203.8%20%7C%203.9%20-%2326543A.svg

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.

Alternatives

Mixing C with Python is nothing new - there are plenty of other ways. 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 extension module is some 40 lines of incomprehensible macros. This does not apply to Cython.

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

Disadvantages

  • The wrapping Python code is less automated. A Python extension module looks and feels like a native Python module out the box 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. However, using such types will generally reduce performance down to near pure Python levels anyway.

Shared Caveats

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

  • You should 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 a cloud server.

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

  • Unless your users have the relevant security thrice disabled, uninstalled, blocked and scraped off the hard drive, recent macOS will block or delete any binary file you produce unless you throw them some money and get it code-signed.

Supported Compilers

Compiler

Linux

Windows

macOS

FreeBSD

Cygwin/msys2

gcc

clang

MSVC

TinyCC

Installation

cslug requires a C compiler to compile C code. Its favourite compiler is gcc. If you’re on Linux you probably already have it. If you are on another OS then you should get it with mingw. To check you have it run the following in terminal:

gcc -v

To use any other supported compiler, cslug respects the CC environment variable. Set it to the name or full path of your alternative compiler.

To install cslug itself use the usual:

pip install cslug

This package is very much in its beta-stages and its API will likely move around. Please don’t assume forward compatibility - pick a version you like and pin it in a requirements.txt.

Quickstart

Check out our quickstart page on readthedocs to get started.

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

cslug-0.1.0-py3-none-any.whl (33.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page