butter 0.8

Library to interface to low level linux features (inotify, fanotify, timerfd, signalfd, eventfd) with asyncio support

Butter is a library to integrate some of Linux’s low level features into python eg signalfd, eventfd and timerfd. most of these functions are handy if you are looking into creating non-blocking servers, anything using select/poll and derivatives or writing server code

Whats Available

• inotify (Complete support, includes asyncio support)

• seccomp (Limited support)

• fanotify (Limited support, includes asyncio support)

• splice

• tee

• vmsplice

• gethostname

• sethostname

• mount

• umount

• pivot_root

• getpid (bypasses glibc caching)

• getppid (bypasses glibc caching)

• eventfd (includes asyncio support)

• timerfd (includes asyncio support)

• pthread_sigmask (Avalible in python3.x but backported for python2.7)

• signalfd (includes asyncio support)

Whats Coming

Most of these exist in v0.2 as ctypes code. these are currently being rewritten to use cffi for speed and compatibility with pypy

• posix/linux aio (scatter/gather read writes with a completion based API instead of a ‘ready’ based interface, eg similar to IOCP on windows)

Supported Python

Butter currently supported the following python interpreters

• pypy (2.7 and 3.2 python implementations)

• cpython 3.4 (required for asyncio support)

• cpython 3.x

• cpython 2.7

Butter may work on older versions however it has not been tested on anything except the above interpreters and may break without warning

Design

The ‘fd’ apis have been designed first as thin wrappers around the underlying kernel syscalls. A File-like object that then uses these syscalls is then made available that obeys the ‘event like’ interface and is based on the interface provided by File and friends. They are intended to be drop in replacements and be used with the select module

Event-like objects

Event like objects are identical to filelike objects except they have the following extra methods to replace the disabled read/readline/write/writeline functionality

• read_event: Return a single event

• read_events: Return all cached events OR read all events from the kernel

AsyncIO

Some syscalls (ones that deal with fd’s) have been made to work with the asyncio framework that baecame avalible in python3.4. The asyncio enabled object is named after the normal Event-like object equivlent with ‘_async’ after it, eg Inotify => Inotify_async. These asyncio Eventlike objects are designed to act and behave like the asyncio.Queue object without the ability to write events to the queue (ie they can only be read from and events are injected from the fd as required)

Release History

0.9 (2014-05-24)

• Add eventfd support

• Add eventfd asyncio support

• asyncio objects now have a close() method

• eventfd now has a close() method

• eventfd now has a fileno() method

• Add timerfd support

• Add timerfd asyncio support

• Added pthread_sigmask

• Added Signalfd

• Added Signalfd asyncio support

Bug Fixes

• Fixed issue with circular imports preventing python3.4 from working

• Fixed issue with python2.7 returning floats where python3 returned ints

0.8 (2014-05-17)

• Now works with python3.4 and higher

• ‘from butter import *’ now imports the system module

• Added trove classification

• Added friendly properties to inotify event object

• Added friendly properties to fanotify event object

• FanotifyEvents now use less memory

• AsyncIO support for inotify on supported platforms

• AsyncIO support for fanotify on supported platforms

0.7 (2014-03-16)

• Added system.py module

• Added gethostname syscall

• Added sethostname syscall

• Added mount syscall

• Added umount syscall

• Added pivot_root syscall

• Added getpid syscall

• Added getppid syscall

• Documented all new syscalls

0.6 (2014-03-12)

• splice syscall documentation

• Added tee() syscall

• Added tee() example

• Added vmsplice() syscall

• Added vmsplice() example

• Updated setup.py to newer auto detecting version

• hide ‘main’ functions in splice module

0.5 (2014-03-11)

• Added splice() syscall

0.4 (2013-12-12)

• Refactor fanotify

• Refactor inotify

• Provide fanotify.str_to_events()

• Provide inotify.str_to_events()

• Add int to signal name mapping for inotify

0.3 (2013-11-20)

• Support for inotify

• Initial support for fanotify

• Initial support for seccomp

• Add function to peer inside kernel buffer and get amount of available bytes to read

API Changes

• removed unused old (non working) signalfd, eventfd, aio

0.2 (2013-11-20)

• Initial support for signalfd

• Initial support for eventfd

• Initial support for aio