Quick and painless wrapping C code into Python.
MIT License
∘
MIT license <https://github.com/bwoodsend/cslug/blob/master/LICENSE>
_
∘
PyPI <https://pypi.org/project/cslug>
_
∘
Documentation <https://cslug.readthedocs.io/>
_
∘
Source Code <https://github.com/bwoodsend/cslug>
_
∘
Raise Bugs <https://github.com/bwoodsend/cslug/issues>
_
∘
Support <https://github.com/bwoodsend/cslug/discussions>
_
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.
.. code-block:: c
// hello-cslug.c
int add_1(int x) {
return x + 1;
}
double times_2(double x) {
return x * 2.0;
}
.. code-block:: python
>>> from cslug import CSlug
>>> slug = CSlug("hello-cslug.c")
>>> slug.dll.add_1(12)
13
>>> slug.dll.times_2(-5)
-10.0
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 <https://intermediate-and-advanced-software-carpentry.readthedocs.io/en/latest/c++-wrapping.html>
_.
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 ..........
import numpy
extension is several MBs.Disadvantages .............
list
or dict
within C code.Shared Caveats ..............
Before you commit yourself to any non Pure-Python you should bear in mind that:
The following OS/compiler combinations are fully supported and tested routinely.
============ ==== ====== ==== ======= ========== Platform gcc_ clang_ MSVC TinyCC_ PGCC_ ** ============ ==== ====== ==== ======= ========== Linux ✓ ✓ ✗ ✓ ✓ Windows ✓ ✓ ✗ ✓ ✗ macOS ✓ ✓ ✗ ✗ ✗ FreeBSD ✓ ✓ ✗ ✗ ✗ OpenBSD ✓ ✓ ✗ ✗ ✗ NetBSD ✓ ✓ ✗ ✗ ✗ DragonFlyBSD ✓ ✓ ✗ ✗ ✗ Cygwin/msys2 ✓ ✓ ✗ ✗ ✗ Android* ✗ ✓ ✗ ✗ ✗ Omnios ✓ ✓ ✗ ✗ ✗ Solaris ✓ ✓ ✗ ✗ ✗ ============ ==== ====== ==== ======= ==========
* Using Termux_.
** Installable as part of the NVIDIA HPC SDK
_.
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.
Check out our quickstart page on readthedocs <https://cslug.readthedocs.io/en/latest/quickstart.html>
_ to get started.
.. _changelog: https://cslug.readthedocs.io/en/latest/history.html
.. _ctypes: https://docs.python.org/3/library/ctypes.html
.. _mingw-w64: https://www.mingw-w64.org/downloads/
.. _gcc: https://gcc.gnu.org/
.. _TinyCC: https://bellard.org/tcc/
.. _clang: https://clang.llvm.org/
.. _pcc
: http://pcc.ludd.ltu.se/
.. _Cython
: https://cython.readthedocs.io/en/latest/index.html
.. _Vagrant: https://github.com/hashicorp/vagrant
.. _manylinux: https://github.com/pypa/manylinux/tree/manylinux1
.. _Termux: https://termux.com/
.. _WinLibs: https://www.winlibs.com/
.. _PGCC: https://docs.nvidia.com/hpc-sdk/pgi-compilers/20.4/x86/pgi-ref-guide/index.htm
.. _NVIDIA HPC SDK
: https://developer.nvidia.com/hpc-sdk