{"id":16987745,"url":"https://github.com/trolldbois/ctypeslib","last_synced_at":"2025-04-04T08:09:35.837Z","repository":{"id":1897566,"uuid":"2824114","full_name":"trolldbois/ctypeslib","owner":"trolldbois","description":"Generate python ctypes classes from C headers. Requires LLVM clang","archived":false,"fork":false,"pushed_at":"2024-03-17T12:21:46.000Z","size":1181,"stargazers_count":209,"open_issues_count":37,"forks_count":55,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-05-01T19:19:28.028Z","etag":null,"topics":["ctypes","libclang","python"],"latest_commit_sha":null,"homepage":"http://trolldbois.blogspot.com/search?q=ctypeslib","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/trolldbois.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","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},"funding":{"github":"trolldbois"}},"created_at":"2011-11-21T23:55:14.000Z","updated_at":"2024-06-19T00:19:13.568Z","dependencies_parsed_at":"2024-06-19T00:19:08.779Z","dependency_job_id":null,"html_url":"https://github.com/trolldbois/ctypeslib","commit_stats":{"total_commits":734,"total_committers":16,"mean_commits":45.875,"dds":"0.25204359673024523","last_synced_commit":"58b0729e2130cd5c2e89bee5c0af01af1813b1ac"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trolldbois%2Fctypeslib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trolldbois%2Fctypeslib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trolldbois%2Fctypeslib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trolldbois%2Fctypeslib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trolldbois","download_url":"https://codeload.github.com/trolldbois/ctypeslib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142074,"owners_count":20890653,"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":["ctypes","libclang","python"],"created_at":"2024-10-14T02:50:40.227Z","updated_at":"2025-04-04T08:09:35.808Z","avatar_url":"https://github.com/trolldbois.png","language":"Python","funding_links":["https://github.com/sponsors/trolldbois"],"categories":[],"sub_categories":[],"readme":"# ctypeslib with libclang\n\n\n![Build Status](https://github.com/trolldbois/ctypeslib/workflows/ctypeslib-linux/badge.svg)\n\n[![Coverage Status](https://coveralls.io/repos/github/trolldbois/ctypeslib/badge.svg?branch=master)](https://coveralls.io/github/trolldbois/ctypeslib?branch=master)\n\n[![Latest release](https://img.shields.io/github/tag/trolldbois/ctypeslib.svg)]()\n[![Supported versions](https://img.shields.io/pypi/pyversions/ctypeslib2.svg)]()\n\n![PyPI](https://img.shields.io/pypi/v/ctypeslib)\n![Python](https://img.shields.io/pypi/pyversions/ctypeslib)\n\n[Quick usage guide](docs/ctypeslib_2.0_Introduction.ipynb) in the docs/ folder.\n\n## Status update\n\n - 2025-02:\n   - Updating for clang 19 and py13. \n   - Dropping testing/support for versions older than 3 from latest.\n - 2023-04:\n   - Please read the installation instructions\n - 2021-02:\n   - Thanks for the pull requests\n   - Note: libclang-xx-dev must be installed for stddef and other reasons.\n   - bump to libclang-11\n - 2018-01-03: master branch works with libclang-5.0 HEAD, python clang from pypi, python3\n - 2017-05-01: master branch works with libclang-4.0 HEAD\n\n## Installation\n\n### LLVM Clang library\nFirst, you should install LLVM clang.\nSee the LLVM Clang instructions at http://apt.llvm.org/ or use your distribution's packages. As clang is the default compiler on macOS, Mac users should see [the section below.](#macos-install)\n\nEither use an installer relevant for your OS (APT, downloads, etc..) to install libclang \n```sh\n$ sudo apt install libclang1-19\n```\n\nor you can use the LLVM install script that installs the whole llvm toolkit \n```sh\n wget https://apt.llvm.org/llvm.sh \u0026\u0026 chmod +x llvm.sh\n # then install llvm version 19 \n ./llvm.sh 19\n # or version 17 or any other version\n ./llvm.sh 17\n```\nor you can use anaconda, or any local installation of your favorite choice\n\n### ctypeslib and python packages\nThen, install ctypeslib2 and the clang python package with the **same version as your llvm clang library**.\n\nStable Distribution is available through PyPi at https://pypi.python.org/pypi/ctypeslib2/\nif you are not using the latest LLVM clang version, you will need to specify the correct clang python package version\n\n  - If you have installed the latest llvm version: `pip install ctypeslib2` should work fine\n  - If you are using llvm clang 16: `pip install ctypeslib2 clang==16`\n  - If you are using llvm clang 14: `pip install ctypeslib2 clang==14` \n  - If you are using llvm clang 11: `pip install ctypeslib2 clang==11`\n  - etc...\n\n### Alternative install for Ubuntu and Debian\n\nOn Ubuntu, libclang libraries are installed with version in the filename.\nThis library tries to load a few different versions to help you out. (`__init__.py`)\nBut if you encounter a version compatibility issue, you might have to fix the problem\nusing one of the following solutions:\n\n* Set the CLANG_LIBRARY_PATH environmental variable to the clang library file or path\n    ```\n    $ export CLANG_LIBRARY_PATH=/lib/x86_64-linux-gnu/libclang-11.so.1\n    $ clang2py --version\n    versions - clang2py:2.3.3 clang:11.1.0 python-clang:11.0\n    ```\n\n* **OR** Install the development package libclang-\u003cversion\\\u003e-dev to get a file called libclang.so (e.g. `sudo apt get install libclang-11-dev`)\n\n* **OR** create a link to libclang-\u003cversion\\\u003e.so.1 named libclang.so\n* **OR** hardcode a call to clang.cindex.Config.load_library_file('libclang-\u003cversion\\\u003e.so.1') in your code before importing ctypeslib\n\n### macOS install\n\nInstall the XCode Command Line Tools with `xcode-select --install` so that clang and essential headers are available.\n\nIdentify the version of `clang` with\n\n```\n% xcrun clang --version\nApple clang version 15.0.0 (clang-1500.3.9.4)\nTarget: arm64-apple-darwin23.3.0\nThread model: posix\nInstalledDir: /Library/Developer/CommandLineTools/usr/bin\n```\n\nensure the Apple-provided clang is the active one in your environment\n\n```\n% which clang\n/usr/bin/clang\n% clang --version\nApple clang version 15.0.0 (clang-1500.3.9.4)\nTarget: arm64-apple-darwin23.3.0\nThread model: posix\nInstalledDir: /Library/Developer/CommandLineTools/usr/bin\n```\n\nand install ctypeslib2 and the corresponding Python bindings to clang with pip\n\n```\n% pip install ctypeslib2 'clang\u003e=15,\u003c16'\n```\n\n(In theory it is possible to install different versions of clang with e.g. conda. To avoid invoking installing the XCode Command Line Tools or invoking xcrun at all from ctypeslib2, `export CTYPESLIB2_SKIP_MACOS_SDK=1` in the environment. You will need to then supply the necessary options yourself with `--clang-args` or the `cfg=` argument to `translate()` and `translate_files()`.)\n\n## Usage\n### Use ctypeslib2 as a Library in your own python code\n\n```py\nimport ctypeslib\npy_module = ctypeslib.translate('''int i = 12;''')\nprint(py_module.i)  # Prints 12\n\npy_module2 = ctypeslib.translate('''struct coordinates { int i ; int y; };''')\nprint(py_module2.struct_coordinates)  # \u003cclass 'struct_coordinates'\u003e\nprint(py_module2.struct_coordinates(1,2))  # \u003cstruct_coordinates object at 0xabcde12345\u003e\n\n# input files, output file\npy_module3 = ctypeslib.translate_files(['mytest.c'], outfile=open('mytest.py', 'w'))\nprint(open('mytest.py').read())\n\n# input files, output code\npy_module4 = ctypeslib.translate_files(['mytest.c'])\nprint(open('mytest.py').read())\n\n# input files, output code, with clang options, like cross-platform\nfrom ctypeslib.codegen import config\ncfg = config.CodegenConfig()\ncfg.clang_opts.extend(['-target', 'arm-gnu-linux'])\npy_module5 = ctypeslib.translate_files(['mytest.c'], cfg=cfg)\nprint(open('mytest.py').read())\n```\n\nLook at `test/test_api.py` for more advanced Library usage\n\n\n### Use ctypeslib2 on the command line\n\nSource file:\n```c\n// t.c \nstruct my_bitfield {\n    long a:3;\n    long b:4;\n    unsigned long long c:3;\n    unsigned long long d:3;\n    long f:2;\n};\n```\n\nRun c-to-python script:\n\n    clang2py t.c\n\nOutput:\n```py\n# -*- coding: utf-8 -*-\n#\n# TARGET arch is: []\n# WORD_SIZE is: 8\n# POINTER_SIZE is: 8\n# LONGDOUBLE_SIZE is: 16\n#\nimport ctypes\n\nclass struct_my_bitfield(ctypes.Structure):\n    _pack_ = True # source:False\n    _fields_ = [\n    ('a', ctypes.c_int64, 3),\n    ('b', ctypes.c_int64, 4),\n    ('c', ctypes.c_int64, 3),\n    ('d', ctypes.c_int64, 3),\n    ('f', ctypes.c_int64, 2),\n    ('PADDING_0', ctypes.c_int64, 49)]\n\n__all__ = \\\n    ['struct_my_bitfield']\n```\n\n### use ctypeslib with additional clang arguments:\n\nSource file:\n```c\n// test-stdbool.c \n#include \u003cstdbool.h\u003e\n\ntypedef struct s_foo {\n    bool bar1;\n    bool bar2;\n    bool bar3;\n} foo;\n```\n\nRun c-to-python script (with any relevant include folder):\n\n    clang2py --clang-args=\"-I/usr/include/clang/4.0/include\" test-stdbool.c\n\nOutput:\n```py\n# -*- coding: utf-8 -*-\n#\n# TARGET arch is: ['-I/usr/include/clang/4.0/include']\n# WORD_SIZE is: 8\n# POINTER_SIZE is: 8\n# LONGDOUBLE_SIZE is: 16\n#\nimport ctypes\n\nclass struct_s_foo(ctypes.Structure):\n    _pack_ = True # source:False\n    _fields_ = [\n    ('bar1', ctypes.c_bool),\n    ('bar2', ctypes.c_bool),\n    ('bar3', ctypes.c_bool),]\n\nfoo = struct_s_foo\n__all__ = ['struct_s_foo', 'foo']\n```\n\n## _pack_ and PADDING explanation\n\n    clang2py test/data/test-record.c\n\nThis outputs:\n```py\n# ...\n\nclass struct_Node2(Structure):\n    _pack_ = True # source:False\n    _fields_ = [ \n    ('m1', ctypes.c_ubyte),\n    ('PADDING_0', ctypes.c_ubyte * 7),\n    ('m2', POINTER_T(struct_Node)),]\n\n# ...\n```\nThe PADDING_0 field is added to force the ctypes memory Structure to align fields offset with the definition given\nby the clang compiler.\n\nThe [_pack_](https://docs.python.org/3/library/ctypes.html#ctypes.Structure._pack_) attribute forces the alignment \non 0 bytes, to ensure all fields are as defined by this library, and not per the compiler used by the host python binary\n\nThe objective of this, is to be able to produce cross-architecture python code, that can read memory structures from a \ndifferent architecture (like reading a memory dump from a different architecture)\n\nSee `clang-11 -print-targets` for options\n\n\n## Usage details\n\n    usage: clang2py [-h] [-c] [-d] [--debug] [-e] [-k TYPEKIND] [-i] [-l DLL] [-m module] [--nm NM] [-o OUTPUT] [-p DLL] [-q] [-r EXPRESSION] [-s SYMBOL] [-t TARGET] [-v] [-V] [-w W] [-x] [--show-ids SHOWIDS] [--max-depth N]\n                    [--validate VALIDATE] [--clang-args CLANG_ARGS]\n                    files [files ...]\n    \n    Version 2.3.3. Generate python code from C headers\n    \n    positional arguments:\n      files                 source filenames. stdin is not supported\n    \n    options:\n      -h, --help            show this help message and exit\n      -c, --comments        include source doxygen-style comments\n      -d, --doc             include docstrings containing C prototype and source file location\n      --debug               setLevel to DEBUG\n      -e, --show-definition-location\n                            include source file location in comments\n      -k TYPEKIND, --kind TYPEKIND\n                            kind of type descriptions to include: a = Alias, c = Class, d = Variable, e = Enumeration, f = Function, m = Macro, #define s = Structure, t = Typedef, u = Union default = 'cdefstu'\n      -i, --includes        include declaration defined outside of the sourcefiles\n      -l DLL, --include-library DLL\n                            library to search for exported functions. Add multiple times if required\n      -m module, --module module\n                            Python module(s) containing symbols which will be imported instead of generated\n      --nm NM               nm program to use to extract symbols from libraries\n      -o OUTPUT, --output OUTPUT\n                            output filename (if not specified, standard output will be used)\n      -p DLL, --preload DLL\n                            dll to be loaded before all others (to resolve symbols)\n      -q, --quiet           Shut down warnings and below\n      -r EXPRESSION, --regex EXPRESSION\n                            regular expression for symbols to include (if neither symbols nor expressions are specified,everything will be included)\n      -s SYMBOL, --symbol SYMBOL\n                            symbol to include (if neither symbols nor expressions are specified,everything will be included)\n      -t TARGET, --target TARGET\n                            target architecture (default: x86_64-Linux)\n      -v, --verbose         verbose output\n      -V, --version         show program's version number and exit\n      -w W                  add all standard windows dlls to the searched dlls list\n      -x, --exclude-includes\n                            Parse object in sources files only. Ignore includes\n      --show-ids SHOWIDS    Don't compute cursor IDs (very slow)\n      --max-depth N         Limit cursor expansion to depth N\n      --validate VALIDATE   validate the python code is correct\n      --clang-args CLANG_ARGS\n                            clang options, in quotes: --clang-args=\"-std=c99 -Wall\"\n    \n    Cross-architecture: You can pass target modifiers to clang. For example, try --clang-args=\"-target x86_64\" or \"-target i386-linux\" to change the target CPU arch.\n\n\n## Inner workings for memo\n\n- clang2py is a script that calls ctypeslib/ctypeslib/clang2py.py\n- clang2py.py is mostly the old xml2py.py module forked to use libclang.\n- clang2py.py calls ctypeslib/ctypeslib/codegen/codegenerator.py\n- codegenerator.py calls ctypeslib/ctypeslib/codegen/clangparser.py\n- clangparser.py uses libclang's python binding to access the clang internal representation of the C source code. \n    - It then translate each child of the AST tree to python objects as listed in typedesc.\n- codegenerator.py then uses these python object to generate ctypes-based python source code.\n \nBecause clang is capable to handle different target architecture, this fork \n {is/should be} able to produce cross-platform memory representation if needed.\n\n\n## Credits\n\nThis fork of ctypeslib is mainly about using the libclang1\u003e=3.7 python bindings\nto generate python code from C source code, instead of gccxml.\n\nthe original ctypeslib contains these packages:\n - ``ctypeslib.codegen``       - a code generator\n - ``ctypeslib.contrib``       - various contributed modules\n - ``ctypeslib.util``          - assorted small helper functions\n - ``ctypeslib.test``          - unittests\n\nThis fork of ctypeslib is heavily patched for clang.\n- https://github.com/trolldbois/ctypeslib is based on rev77594 of the original ctypeslib.\n- git-svn-id: http://svn.python.org/projects/ctypes/trunk/ctypeslib@775946015fed2-1504-0410-9fe1-9d1591cc4771\n\nThe original ctypeslib is written by\n- author=\"Thomas Heller\",\n- author_email=\"theller@ctypes.org\",\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrolldbois%2Fctypeslib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrolldbois%2Fctypeslib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrolldbois%2Fctypeslib/lists"}