fs.expose.fuse

Expose an FS object to the native filesystem via FUSE

This module provides the necessary interfaces to mount an FS object into the local filesystem via FUSE:

http://fuse.sourceforge.net/

For simple usage, the function ‘mount’ takes an FS object and a local path, and exposes the given FS at that path:

>>> from fs.memoryfs import MemoryFS
>>> from fs.expose import fuse
>>> fs = MemoryFS()
>>> mp = fuse.mount(fs,"/mnt/my-memory-fs")
>>> mp.path
'/mnt/my-memory-fs'
>>> mp.unmount()

The above spawns a new background process to manage the FUSE event loop, which can be controlled through the returned subprocess.Popen object. To avoid spawning a new process, set the ‘foreground’ option:

>>> #  This will block until the filesystem is unmounted
>>> fuse.mount(fs,"/mnt/my-memory-fs",foreground=True)

Any additional options for the FUSE process can be passed as keyword arguments to the ‘mount’ function.

If you require finer control over the creation of the FUSE process, you can instantiate the MountProcess class directly. It accepts all options available to subprocess.Popen:

>>> from subprocess import PIPE
>>> mp = fuse.MountProcess(fs,"/mnt/my-memory-fs",stderr=PIPE)
>>> fuse_errors = mp.communicate()[1]

The binding to FUSE is created via ctypes, using a custom version of the fuse.py code from Giorgos Verigakis:

class fs.expose.fuse.FSOperations(fs, on_init=None, on_destroy=None)

FUSE Operations interface delegating all activities to an FS object.

class fs.expose.fuse.MountProcess(fs, path, fuse_opts={}, nowait=False, **kwds)

subprocess.Popen subclass managing a FUSE mount.

This is a subclass of subprocess.Popen, designed for easy management of a FUSE mount in a background process. Rather than specifying the command to execute, pass in the FS object to be mounted, the target mount point and a dictionary of options for the underlying FUSE class.

In order to be passed successfully to the new process, the FS object must be pickleable. This restriction may be lifted in the future.

This class has an extra attribute ‘path’ giving the path to the mounted filesystem, and an extra method ‘unmount’ that will cleanly unmount it and terminate the process.

By default, the spawning process will block until it receives notification that the filesystem has been mounted. Since this notification is sent by writing to a pipe, using the ‘close_fds’ option on this class will prevent it from being sent. You can also pass in the keyword argument ‘nowait’ to continue without waiting for notification.

unmount()

Cleanly unmount the FUSE filesystem, terminating this subprocess.

fs.expose.fuse.handle_fs_errors(func)

Method decorator to report FS errors in the appropriate way.

This decorator catches all FS errors and translates them into an equivalent OSError. It also makes the function return zero instead of None as an indication of successful execution.

fs.expose.fuse.mount(fs, path, foreground=False, ready_callback=None, unmount_callback=None, **kwds)

Mount the given FS at the given path, using FUSE.

By default, this function spawns a new background process to manage the FUSE event loop. The return value in this case is an instance of the ‘MountProcess’ class, a subprocess.Popen subclass.

If the keyword argument ‘foreground’ is given, we instead run the FUSE main loop in the current process. In this case the function will block until the filesystem is unmounted, then return None.

If the keyword argument ‘ready_callback’ is provided, it will be called when the filesystem has been mounted and is ready for use. Any additional keyword arguments will be passed through as options to the underlying FUSE class. Some interesting options include:

  • nothreads Switch off threading in the FUSE event loop
  • fsname Name to display in the mount info table
fs.expose.fuse.unmount(path)

Unmount the given mount point.

This function shells out to the ‘fusermount’ program to unmount a FUSE filesystem. It works, but it would probably be better to use the ‘unmount’ method on the MountProcess class if you have it.

On darwin, “diskutil umount <path>” is called On freebsd, “umount <path>” is called