Package: cslug
∘MIT license∘PyPI∘Documentation∘Source Code∘Raise Bugs∘Get SupportQuick and painless wrapping C code into Python.
Thecslugpackage provides a thin layer on top of the built-inctypeslibrary, making it easier to load functions and structures from C into Python.// hello-cslug.cintadd_1(intx){returnx+1;}doubletimes_2(doublex){returnx*2.0;}>>>fromcslugimportCSlug>>>slug=CSlug("hello-cslug.c")>>>slug.dll.add_1(12)13>>>slug.dll.times_2(-5)-10.0AlternativesMixing 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 foundhere.cslugaims 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 asCython).AdvantagesC 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 acslugbinary need only be compiled for every platform.You can use virtually any C compiler.
Python extension modules must be built withclangon 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-isedimport numpyextension is several MBs.DisadvantagesThe 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 aslistordictwithin 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 CaveatsBefore 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 usingVagrant.Linux wheels must be built on amanylinuxDocker 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 CompilersThe following OS/compiler combinations are fully supported and tested routinely.CompilerLinuxWindowsmacOSFreeBSDOpenBSDNetBSDCygwin/msys2Android*gcc✓✓✓✓✓✓✓✗clang✓✓✓✓✓✗✓✓MSVC✗✗✗✗✗✗✗✗TinyCC✓✓✗✗✗✗✗✗PGCC**✓✗✗✗✗✗✗✗* UsingTermux.
** Installable as part of theNVIDIA HPC SDK.Installationcslugrequires a C compiler to compile C code.
Its favourite compiler isgcc.
Linux distributions typically come with it preinstalled.
If you are on another OS or just don’t have it then you should get it withmingw-w64.
Windows users are recommended to downloadWinLibswithoutLLVM/Clang/LLD/LLDB(althoughcslugworks withclangtoo)
and add itsmingw64/bindirectory toPATH.Check that you have it set up by running the following in a terminal:gcc -vNotegccis a build time dependency only. If you provide wheels for a package
that contain binaries built withcslug, then your users will not need a
compiler; only if they try to build your package from source.By default,cslugwill usegccif it can find it. On macOS or FreeBSD it
will switch toclangifgccis unavailable.
To use any other supported compiler,cslugrespects theCCenvironment
variable.
Set it to the name or full path of your alternative compiler.Installcslugitself with the usual:pip install cslugWhilstcslugis 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 arequirements.txt.
Inspect thechangelogfor anything that may break your code.QuickstartCheck out ourquickstart page on readthedocsto get started.CreditsHall of fame for contributions to cslug.Huge shout out toJetBrainsforPyCharmand for providing their full range
of productsfree 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 byCookiecutterand a fork of theaudreyr/cookiecutter-pypackageproject
template.