{"id":15297000,"url":"https://github.com/bwoodsend/cslug","last_synced_at":"2025-04-13T22:11:56.952Z","repository":{"id":39895326,"uuid":"302994906","full_name":"bwoodsend/cslug","owner":"bwoodsend","description":"Quick and painless wrapping C code into Python.","archived":false,"fork":false,"pushed_at":"2024-10-12T17:01:42.000Z","size":1556,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T12:38:30.186Z","etag":null,"topics":["c","python","wrapper"],"latest_commit_sha":null,"homepage":"https://cslug.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bwoodsend.png","metadata":{"files":{"readme":"README.rst","changelog":"history/0.1.0.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-10T21:44:34.000Z","updated_at":"2025-02-22T19:08:44.000Z","dependencies_parsed_at":"2024-09-12T05:33:14.700Z","dependency_job_id":null,"html_url":"https://github.com/bwoodsend/cslug","commit_stats":{"total_commits":417,"total_committers":1,"mean_commits":417.0,"dds":0.0,"last_synced_commit":"eae5b246df747fe359f317807e72035e59febc34"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwoodsend%2Fcslug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwoodsend%2Fcslug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwoodsend%2Fcslug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwoodsend%2Fcslug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bwoodsend","download_url":"https://codeload.github.com/bwoodsend/cslug/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248788917,"owners_count":21161728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","python","wrapper"],"created_at":"2024-09-30T19:13:56.915Z","updated_at":"2025-04-13T22:11:56.924Z","avatar_url":"https://github.com/bwoodsend.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"=================\nWelcome to cslug!\n=================\n\n∘\n`MIT license \u003chttps://github.com/bwoodsend/cslug/blob/master/LICENSE\u003e`_\n∘\n`PyPI \u003chttps://pypi.org/project/cslug\u003e`_\n∘\n`Documentation \u003chttps://cslug.readthedocs.io/\u003e`_\n∘\n`Source Code \u003chttps://github.com/bwoodsend/cslug\u003e`_\n∘\n`Raise Bugs \u003chttps://github.com/bwoodsend/cslug/issues\u003e`_\n∘\n`Support \u003chttps://github.com/bwoodsend/cslug/discussions\u003e`_\n\nQuick and painless wrapping C code into Python.\nThe **cslug** package provides a thin layer on top of the built-in ctypes_\nlibrary, making it easier to load functions and structures from C into Python.\n\n.. code-block:: c\n\n    // hello-cslug.c\n\n    int add_1(int x) {\n      return x + 1;\n    }\n\n    double times_2(double x) {\n      return x * 2.0;\n    }\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from cslug import CSlug\n    \u003e\u003e\u003e slug = CSlug(\"hello-cslug.c\")\n    \u003e\u003e\u003e slug.dll.add_1(12)\n    13\n    \u003e\u003e\u003e slug.dll.times_2(-5)\n    -10.0\n\n\nAlternatives\n------------\n\nMixing C with Python is nothing new - there are plenty of other ways.\nThe most common way is to write Python extension modules.\nA nice comparison of the various methods can be found `here\n\u003chttps://intermediate-and-advanced-software-carpentry.readthedocs.io/en/latest/c++-wrapping.html\u003e`_.\n**cslug** aims to be the simplest although it certainly isn't the most flexible.\n\nUsing ctypes driven wrapping has both advantages and disadvantages over Python\nextension modules and tools that write them (such as Cython_).\n\n\nAdvantages\n..........\n\n* C code can be just plain high school level C.\n  Even a hello world Python extension module is some 40 lines of hairy looking\n  macros.\n* Binaries are not linked against Python and are therefore not tied to a\n  specific Python version.\n  A Python extension module needs to be recompiled for every minor version of\n  Python (3.8, 3.9, 3.10, 3.11) and for every platform (Windows, macOS, Linux)\n  whereas a **cslug** binary need only be compiled for every platform.\n* You can use virtually any C compiler.\n  Python extension modules must be built with clang_ on macOS and MSVC on\n  Windows.\n  The real advantage of this is that you can use the same compiler on all\n  platforms making them considerably more homogonuos and thus greatly reducing\n  your chances of having to debug an issue present only on your least favourite\n  platform.\n* File sizes of binaries are very small.\n  1000 lines of C code equates to about 20KB of binary on Linux.\n  Python extension modules are typically several times larger and\n  a bare-bones Cython-ised ``import numpy`` extension is several MBs.\n\n\nDisadvantages\n.............\n\n* The surrounding Python code is less automated. A Python extension module looks\n  and feels like a native Python module out the box complete with function\n  metadata and docstrings whereas a small wrapper function is generally required\n  for ctypes.\n* You can't use native Python types such as ``list`` or ``dict`` within C code.\n  Using such types will generally reduce performance down to near pure\n  Python levels anyway so this is a small loss in practice.\n* You can't use C++.\n\n\nShared Caveats\n..............\n\nBefore you commit yourself to any non Pure-Python you should bear in mind that:\n\n* You'll need to ship wheels for every platform you wish to support\n  otherwise users of your code will have to install a C compiler to run it.\n  This means that you either need access to all platforms, or you will have to\n  setup Continuous Integration to build you package on the cloud.\n  Linux users can get around this by using Vagrant_.\n* Linux wheels must be built on a manylinux_ Docker image in order to be\n  widely compatible with most distributions of Linux.\n* Recent macOS versions will typically block or delete any binary file you\n  produce unless you either purchase a codesign license\n  or your software becomes famous enough to be whitelisted for you by Apple\n  (binaries uploaded to PyPI seem to be exempt automatically).\n  Windows users face a similar, albeit lesser, problem with Microsoft Defender.\n\n\nSupported Compilers\n-------------------\n\nThe following OS/compiler combinations are fully supported and tested routinely.\n\n============ ==== ====== ==== ======= ==========\nPlatform     gcc_ clang_ MSVC TinyCC_ PGCC_ \\*\\*\n============ ==== ====== ==== ======= ==========\nLinux        ✓    ✓      ✗    ✓       ✓\nWindows      ✓    ✓      ✗    ✓       ✗\nmacOS        ✓    ✓      ✗    ✗       ✗\nFreeBSD      ✓    ✓      ✗    ✗       ✗\nOpenBSD      ✓    ✓      ✗    ✗       ✗\nNetBSD       ✓    ✓      ✗    ✗       ✗\nDragonFlyBSD ✓    ✓      ✗    ✗       ✗\nCygwin/msys2 ✓    ✓      ✗    ✗       ✗\nAndroid*     ✗    ✓      ✗    ✗       ✗\nOmnios       ✓    ✓      ✗    ✗       ✗\nSolaris      ✓    ✓      ✗    ✗       ✗\n============ ==== ====== ==== ======= ==========\n\n\\* Using Termux_.\n\\*\\* Installable as part of the `NVIDIA HPC SDK`_.\n\nInstallation\n------------\n\n**cslug** requires a C compiler to compile C code.\nIts favourite compiler is gcc_.\nLinux distributions typically come with it preinstalled.\nIf you are on another OS or just don't have it then you should get it with\nmingw-w64_.\nWindows users are recommended to download WinLibs_ without\n``LLVM/Clang/LLD/LLDB`` (although **cslug** works with ``clang`` too)\nand add its ``mingw64/bin`` directory to ``PATH``.\n\nCheck that you have it set up by running the following in a terminal::\n\n    gcc -v\n\n.. note::\n\n    gcc_ is a build time dependency only. If you provide wheels for a package\n    that contain binaries built with **cslug**, then your users will not need a\n    compiler; only if they try to build your package from source.\n\nBy default, **cslug** will use gcc_ if it can find it. On macOS or FreeBSD it\nwill switch to clang_ if **gcc** is unavailable.\nTo use any other supported compiler, **cslug** respects the ``CC`` environment\nvariable.\nSet it to the name or full path of your alternative compiler.\n\nInstall **cslug** itself with the usual::\n\n    pip install cslug\n\nWhilst **cslug** is still in its 0.x versions, breaking changes may occur on\nminor version increments.\nPlease don't assume forward compatibility - pick a version you like and\npin it in a ``requirements.txt``.\nInspect the `changelog`_ for anything that may break your code.\n\n\nQuickstart\n----------\n\nCheck out our `quickstart page on readthedocs\n\u003chttps://cslug.readthedocs.io/en/latest/quickstart.html\u003e`_ to get started.\n\n.. _changelog: https://cslug.readthedocs.io/en/latest/history.html\n.. _ctypes: https://docs.python.org/3/library/ctypes.html\n.. _mingw-w64: https://www.mingw-w64.org/downloads/\n.. _gcc: https://gcc.gnu.org/\n.. _TinyCC: https://bellard.org/tcc/\n.. _clang: https://clang.llvm.org/\n.. _`pcc`: http://pcc.ludd.ltu.se/\n.. _`Cython`: https://cython.readthedocs.io/en/latest/index.html\n.. _Vagrant: https://github.com/hashicorp/vagrant\n.. _manylinux: https://github.com/pypa/manylinux/tree/manylinux1\n.. _Termux: https://termux.com/\n.. _WinLibs: https://www.winlibs.com/\n.. _PGCC: https://docs.nvidia.com/hpc-sdk/pgi-compilers/20.4/x86/pgi-ref-guide/index.htm\n.. _`NVIDIA HPC SDK`: https://developer.nvidia.com/hpc-sdk\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwoodsend%2Fcslug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbwoodsend%2Fcslug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwoodsend%2Fcslug/lists"}