skip to navigation
skip to content

fslib 0.2.1

Wrapper around low-level FS-related calls, with support for advanced FS stacking

fslib is a wrapper around Python’s os.* low-level functions, aiming to:

  • Provide more pythonic APIs for low-level primitives
  • Merge various physical locations into a simple pseudo-filesystem for the application
  • Handle UnionFS-like features, including transparent write overlay on top of read-only paths

fslib supports Python 2.7 and 3.3+; it requires only the standard Python library.



$ pip install fslib


$ git clone git://
$ python install


Replacing import os

>>> import fslib
>>> fs = fslib.FileSystem(fslib.OSFS('/'))
>>> fs.dir_exists('/etc/')
>>> fs.listdir('/')
['/etc', '/dev', '/proc']

Forcing read-only

In order to ensure that user code doesn’t change any physical file, fslib provides a simple wrapper that prevents writing to the filesystem.

>>> import fslib
>>> import fslib.stacking
>>> fs = fslib.FileSystem(fslib.stacking.ReadOnlyFS(fslib.OSFS('/')))
>>> fs.read_one_line('/etc/hostname')
>>>'/tmp/x', 'w')
OSError: [Errno 30] Read-only file system: '/tmp/x'

UnionFS-like mounting

fslib provides a UnionFS-like wrapper as fslib.stacking.UnionFS. This backend will provide a merged view of several branch, redirecting all writes to the branch(es) declared writable=True.

>>> import fslib,, fslib.stacking
>>> mem_fs =
>>> union_fs = fslib.stacking.UnionFS()
>>> union_fs.add_branch(mem_fs, ref='memory', rank=0, writable=True)
>>> union_fs.add_branch(fslib.stacking.ReadOnlyFS(fslib.OSFS('/')), ref='os', rank=1)
>>> fs = fslib.FileSystem(backend=union_fs)
>>> fs.writelines('/tmp/x', ['aa', 'bb'])
>>> open('/tmp/x', 'r')
IOError: [Errno 2] No such file or directory: '/tmp/x'
>>> fs.file_exists('/tmp/x')
>>> fs.readlines('/tmp/x')
['aa', 'bb']
>>> fs.access('/tmp/x', os.F_OK)

Unix-like filesystem tree

It is possible to “overlay” physical or virtual file systems to present a simple, unified structure to the program.

>>> import fslib, fslib.stacking
>>> mnt = fslib.MountFS()
>>> mnt.mount_fs('/', fslib.stacking.ReadOnlyFS(fslib.OSFS('/')))
>>> mnt.mount_fs('/home/xelnor/.myapp', fslib.stacking.MemoryFS())
>>> mnt.mount_fs('/home/xelnor/.myapp/cache', fslib.OSFS('/tmp/myapp/shared_cache'))

With this setup:

  • All reads/writes to /home/xelnor/.myapp/cache will actually occur within /tmp/myapp/shared_cache
  • All reads/writes within /home/xelnor/.myapp (except for /cache) will occur in memory
  • No write will be permitted anywhere else.
File Type Py Version Uploaded on Size
fslib-0.2.1.tar.gz (md5) Source 2014-01-03 14KB