Skip to main content

An extended set of Python bindings for libclang

Project description

https://travis-ci.org/pybee/seasnake.svg?branch=master

Sealang is an improved set of Python bindings for libclang.

The upstream maintainers of libclang have not been especially responsive to patches that address issues like Python 3 compatibility, and the significant omissions in the API (such as extracting literals and operators).

This package is a fork of the official Python bindings for libclang, patched to correct these problems.

Installation

Sealang works by providing a C module (sealang.so) that adds C interfaces for useful operations on the LLVM AST. This C module is then accessed using ctypes to provide Python bindings.

To compile Sealang, you’ll need to:

  1. Install LLVM (with clang)

  2. Set some environment variables

  3. Install Sealang

The exact commands needed will vary between platforms.

OS X

Although OS X provides Clang, it doesn’t provide all the development headers, so you’ll need to . Homebrew is the easiest way to do this. Follow the installation instructions on the Homebrew homepage; once you’ve got Homebrew installed, you can run:

$ brew install llvm --with-clang --with-asan

to get a working install of llvm with clang.

Then, you’ll need to set the following environment variables:

$ export LLVM_HOME=/usr/local/opt/llvm
$ export DYLD_LIBRARY_PATH=$LLVM_HOME/lib

Lastly, you can install Sealang:

$ pip install sealang

Ubuntu 14.04 (Trusty)

To compile under Ubuntu 14.04 (Trusty), you’ll need to get an updated version of LLVM:

$ sudo apt-get install libclang-3.6 clang-3.6 -y

Then, you’ll need to set the following environment variables.

$ export LLVM_HOME=/usr/lib/llvm-3.6 $ export LD_LIBRARY_PATH=$LLVM_HOME/lib

Lastly, you can install Sealang:

$ pip install sealang

Other platforms

The instructions for installing on other platforms should be analogous. If you develop build instructions for a platform, please submit a pull request.

Usage

Sealang provides a superset of the functionality provided by libclang. Those features are:

  • Cursor objects have 4 additional attributes:

    • literal - the value of a literal expression. Available on IntegerLiteral, FloatingLiteral, StringLiteral, CharacterLiteral, and CXXBooleanLiteral nodes.

    • operator - the printable version of an operator. Only available on BinaryOperator, UnaryOperator, and CompoundAssignOperator cursor nodes.

    • binary_operator - an enumeration value describing a BinaryOperator or CompoundAssignOperator node.

    • unary_operator - an enumeration value describing a UnaryOperator node.

  • BinaryOperator - An enumeration for the types of binary operators:

    • BinaryOperator.INVALID

    • BinaryOperator.PTRMEMD

    • BinaryOperator.PTRMEMI

    • BinaryOperator.MUL

    • BinaryOperator.DIV

    • BinaryOperator.REM

    • BinaryOperator.ADD

    • BinaryOperator.SUB

    • BinaryOperator.SHL

    • BinaryOperator.SHR

    • BinaryOperator.LT

    • BinaryOperator.GT

    • BinaryOperator.LE

    • BinaryOperator.GE

    • BinaryOperator.EQ

    • BinaryOperator.NE

    • BinaryOperator.AND

    • BinaryOperator.XOR

    • BinaryOperator.OR

    • BinaryOperator.LAND

    • BinaryOperator.LOR

    • BinaryOperator.ASSIGN

    • BinaryOperator.MULASSIGN

    • BinaryOperator.DIVASSIGN

    • BinaryOperator.REMASSIGN

    • BinaryOperator.ADDASSIGN

    • BinaryOperator.SUBASSIGN

    • BinaryOperator.SHLASSIGN

    • BinaryOperator.SHRASSIGN

    • BinaryOperator.ANDASSIGN

    • BinaryOperator.XORASSIGN

    • BinaryOperator.ORASSIGN

    • BinaryOperator.COMMA

    • BinaryOperator.UNKNOWN

  • UnaryOperator - An enumeration for the types of binary operators:

    • UnaryOperator.INVALID

    • UnaryOperator.POSTINC

    • UnaryOperator.POSTDEC

    • UnaryOperator.PREINC

    • UnaryOperator.PREDEC

    • UnaryOperator.ADDROF

    • UnaryOperator.DEREF

    • UnaryOperator.PLUS

    • UnaryOperator.MINUS

    • UnaryOperator.NOT

    • UnaryOperator.LNOT

    • UnaryOperator.REAL

    • UnaryOperator.IMAG

    • UnaryOperator.EXTENSION

    • UnaryOperator.UNKNOWN

How it works

Sealang is a bit of a nasty hack. libclang is a set of C bindings to a C++ API; Python ctypes are then used to wrap the C API. However, while the C++ API is quite rich, libclang is less so.

Sealang bridges this gap by providing C wrappers around the C++ calls that provide the useful functionality. This library of C functions is wrapped up as a Python C module for delivery purposes - this C module contains no exposed Python objects or methods, but because it’s a module, the underlying compiled sealang.so file is easy to find. ctypes are then used to expose the sealang wrapper functions;

Internally, Sealang reproduces some minor pieces of the libclang API; these are methods (such as the string creation and manipulation methods) that aren’t exposed as symbols for third-party use.

All this functionality is potentially a candidate to be passed upstream to libclang.

Community

Sealang is part of the BeeWare suite. You can talk to the community through:

Contributing

If you experience problems with Sealang, log them on GitHub. If you want to contribute code, please fork the code and submit a pull request.

Project details


Download files

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

Source Distribution

sealang-3.9.dev258341.tar.gz (48.9 kB view details)

Uploaded Source

Built Distributions

sealang-3.9.dev258341-cp34-cp34m-macosx_10_9_x86_64.whl (1.3 MB view details)

Uploaded CPython 3.4m macOS 10.9+ x86-64

sealang-3.9.dev258341-cp27-none-macosx_10_9_x86_64.whl (1.3 MB view details)

Uploaded CPython 2.7 macOS 10.9+ x86-64

File details

Details for the file sealang-3.9.dev258341.tar.gz.

File metadata

File hashes

Hashes for sealang-3.9.dev258341.tar.gz
Algorithm Hash digest
SHA256 2619a2c34ccb6d34173af2557dae689c632cdc4817244293706900b219fb96cc
MD5 6408d84a93e0b0ebf9730cd6cd09b68c
BLAKE2b-256 b09db3dc032fec53ccec06454a34d1f1c720ec43e2f45f05327141466eefee21

See more details on using hashes here.

File details

Details for the file sealang-3.9.dev258341-cp34-cp34m-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for sealang-3.9.dev258341-cp34-cp34m-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 6444829dbe5dc57ca4301b6958d6d8e97fe76e9d56fb0e55f105964a93564ac4
MD5 efbd8f2af85b59b5cc2ef9e5651e10c4
BLAKE2b-256 808be857ea24cb87c6b21148952a4b307c6376852635d0eaa051f7064f8c4afa

See more details on using hashes here.

File details

Details for the file sealang-3.9.dev258341-cp27-none-macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for sealang-3.9.dev258341-cp27-none-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 3d356d0d30d091a16d3c95377f5edc52328d048503c5a28ef1839ba918929be9
MD5 0ee358edf328aeca8efa94a4628d0f55
BLAKE2b-256 930622bac9620d0fa6d7b1eeec384510268e603cbef5a1461e76a03a017d695c

See more details on using hashes here.

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