Package: butter
“Making things that little bit butter under linux”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, dealing with event loops or writing
high performance servicesFeaturesFull testing of all error conditions in unit testsSmall set of exceptions to deal withasyncio compatible versions of callsEmulation and reuse of built in objects wherever possibleBoth low level 1:1 calls and a high level interface availableDefault values chosen follow ‘least surprise’ principle (eg CLOCK_MONOTONIC
instead of CLOCK_REALTIME to avoid issues with clock updates)Single codebase supporting python 2 and python 3 without modifcation for
easier forward migrationWhats Availableinotify (Complete support, includes asyncio support)fanotify (Limited support, includes asyncio support)spliceteevmsplice (Removed, cant be done safely with Python, use os.writev instead)gethostnamesethostnamemountumountpivot_rootgetpid (bypasses glibc caching)getppid (bypasses glibc caching)eventfd (includes asyncio support)timerfd (includes asyncio support)‘sloppy’ timers (inaccurate timers that may experince jitter for power saving)Wake timers (timers that may wake a system from suspend)pthread_sigmask (Avalible in python3.x but backported for python2.7)signalfd (includes asyncio support)memfdprctlWhats ComingMost of these exist in v0.2 as ctypes code. these are currently being rewritten
to use cffi for speed and compatibility with pypyposix/linux aio (scatter/gather read writes with a completion based API
instead of a ‘ready’ based interface, eg similar to IOCP on windows)Sphinx documentationExample codeMore unit testsSupported PythonButter currently supported the following python interpreterspypy (2.7 and 3.2 python implementations)cpython 3.4 (required for asyncio support)cpython 3.xcpython 2.7Butter may work on older versions however it has not been tested on anything
except the above interpreters and may break without warningInstallingbutter makes use of several C libraries to provide low level functionality. most
of the compilation is taken care of by setup.py and cffi at install time however
you will need to ensure that some header files are available on the machine doing
the compilation (which may be different to the machine butter is being packaged
for and Finally installed on)Dev packages required:kernel headers for a fairly recent kernel (3.x recommended)libffi-dev (required for cffi)to install butter use the following command:$ pip install setuptools
$ pip install butterthis will pull in all the required dependencies and compile the required C
extensionsfor asyncio support, python 3.4 or newer is required. importing the asyncio
modules on older versions of python will throw a syntax error. Hence why these
are namespaced under butter.asyncio rather than in the base modulesDesignThe ‘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 moduleEvent-like objectsEvent like objects are identical to filelike objects except they have the
following extra methods to replace the disabled read/readline/write/writeline
functionalityread_event:  Return a single eventread_events: Return all cached events OR read all events from the kernelAsyncIOSome syscalls (ones that deal with fd’s) have been made to work with the
asyncio framework that became 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)ExceptionsButter was designed to have a small set of easily catchable exceptions and to
reuse the builtin exceptions wherever possible. The list below is a rough
guide of what exceptions you can expect to receiveOSError/MemoryError: The Operating system was unable to fulfill your requestValueError: One of the arguments is invalidPermissionError: You do not have sufficient Privileges to use this callInternalError: The function hit an internal bug that was never expected to
be hit but is tested for just in case. Please consider filing a bug reportUnknownError: The Error is not specifically handled and unexpected, see
exception.errno for the Error code that generated this exceptionProjects using Butterhttps://pypi.python.org/pypi/icheck/(Written by the author, inotify)https://pypi.python.org/pypi/igor-inotify/(Written by the author, inotify)Contact DetailsFor pull requests, patches, feature requests and support
please email the author (code@pocketnix.org)xmpp:dablitz@pocketnix.orgorcode@conference.pocketnix.orgRelease History0.13.1 (2021-06-12)Bump versions correctly0.13.0 (2021-06-12)Arguments that take a file name or object now accept Path objectsFixups to setup.pyAdd new prctl module0.12.6 (2017-06-07)Eventlike objects are now usable as context managers like files‘pytest’ now works corectly (with no args)Fixed up missing symbols in fanotify modulereworked test suite to acomidate python2.70.12.5 (2017-04-07)Removal of seccomp supportAdd FAN_MODIFY_DIR from latest linux releaseAdd FAN_ALL_EVENTS0.12.4 (2017-01-27)Added environment variable to disable building of seccomp supportFixed up issue with imports on splice and timerfdAdded memfd supportFix up testsTest suite now leaks less fd’sAdded CLONE_NEWCGROUPsetns wrapper added (only low level stub was present)0.12.3 (2017-01-27)Added contributor file to keep a record of those who helped outfix up imports that where breaking on python3, preventing lib usageDocument a 3rd party lib dependency that comes in handy0.12.2 (2016-04-16)Include missing build files0.12.1 (2015-05-02)Added stub for removed vmsplice() that raises NotImplementedRemove note about installing cffi first as it is no longer required since v0.120.12 (2015-04-02)Add support for new timer types including ‘slack’ timers and timers that can wake a system from suspendHid the clone.C class as clone._C as it is not intended for general consumptionProvided C implementation for pivot_root as it was not provided by glibcMigrated to cffi >= 1.0.0 to fix build bugsAPI ChangesRemoved vmsplice() due to safety issues (does not copy bytes but maps live data, GC causes liveliness issues)0.11.2 (2015-09-27)Document cffi bootstrap issues in README0.11.1 (2015-06-14)Misc fixups to setup.pyAPI ChangesOlder Linux distros (debian < Jessie) to not provide libseccomp, disable this at setup.py timeBug FixesOlder Linux distros do not provide setns via libc, a ‘weak’ dummy implementation is now provided to allow compliation to work0.11 (2015-05-02)Make close on exec the default behavior for python 3 platformsLow level functions now accept a file-like or event-like object in addition to a fdNew ‘watch’ function as a simple wrapper around inotify for ultra simple uses caseswait() on eventlike objects now accept a timeout value in seconds to specify the maximum ammount of
time to wait for an event to occurAPI ChangesArgument order to fanotify_mark and high level API changed to have a more logical flowTimerfd code has been overhauled and is no longer compatibleBug Fixes‘blocking’ on Inotify objects was an internal flag and is now prefixed with ‘_’ to denote its statusTimerfd was created by default as CLOCK_MONOTONIC in contrast to other functions in butterFixed bug that prevented compilation on 64bit machines with signalfd0.10 (2015-03-20)errno to Exception mapping became a fixed part of the API (and unit tested)timerfd is now CLOCK_MONOTONIC by defaultAdded Simpler TimerVal to replace Timerspec for timerfdDeprecated TimerStruct (will print a DeprecationWarning if such warnings have been turned on)OSError now returned instead of IOError. on python3 IOError = OSError so identical behavior will be observedIdentical Error codes now return Identical Exceptions, except where there is a clear reason not o (eg InternalError)Errors due to incorrect arguments now all raise ValueError instead of ValueError or OSErrorBug FixesC code now gets compiled at installation rather than first useFixed up the name of an exception in error handling code leading to double exceptionpivot_root would return OSError rather than ValueError when incorect arguments were providedsystem.py was using its own definition of PermissionError, unify this with utils.pyfanotify now raises PermissionError on EPERM instead of OSError (of which it is a subclass)0.9.2 (2015-03-10)Deprecating seccomp support in favour of official libseccomp python bindingsBug FixesAdd __init__.py to asyncio dir so that async methods can be imported0.9.1 (2015-01-05)Bug Fixesread_events was passing an undefined variable to actual implementations0.9 (2014-05-24)Added eventfd supportAdded eventfd AsyncIO supportAdded timerfd supportAdded timerfd AsyncIO supportAdded SignalfdAdded Signalfd AsyncIO supportAdded pthread_sigmaskAsyncIO objects now have a close() methodConverted all high level event objects to Eventlike objectsInotify events now have an is_dir_event propertyAdded test suiteBug FixesFixed issue with circular imports preventing python3.4 from workingFixed issue with python2.7 returning floats where python3 returned ints0.8 (2014-05-17)Now works with python3.4 and higher‘from butter import *’ now imports the system moduleAdded trove classificationAdded friendly properties to inotify event objectAdded friendly properties to fanotify event objectFanotifyEvents now use less memoryAsyncIO support for inotify on supported platformsAsyncIO support for fanotify on supported platforms0.7 (2014-03-16)Added system.py moduleAdded gethostname syscallAdded sethostname syscallAdded mount syscallAdded umount syscallAdded pivot_root syscallAdded getpid syscallAdded getppid syscallDocumented all new syscalls0.6 (2014-03-12)splice syscall documentationAdded tee() syscallAdded tee() exampleAdded vmsplice() syscallAdded vmsplice() exampleUpdated setup.py to newer auto detecting versionhide ‘main’ functions in splice module0.5 (2014-03-11)Added splice() syscall0.4 (2013-12-12)Refactor fanotifyRefactor inotifyProvide fanotify.str_to_events()Provide inotify.str_to_events()Add int to signal name mapping for inotify0.3 (2013-11-20)Support for inotifyInitial support for fanotifyInitial support for seccompAdd function to peer inside kernel buffer and get amount of available bytes to readAPI Changesremoved unused old (non working) signalfd, eventfd, aio0.2 (2013-11-20)Initial support for signalfdInitial support for eventfdInitial support for aio