fs.expose.dokan

Expose an FS object to the native filesystem via Dokan.

This module provides the necessary interfaces to mount an FS object into the local filesystem using Dokan on win32:

http://dokan-dev.github.io/

For simple usage, the function ‘mount’ takes an FS object and new device mount point or an existing empty folder and exposes the given FS as that path:

>>> from fs.memoryfs import MemoryFS
>>> from fs.expose import dokan
>>> fs = MemoryFS()
>>> # Mount device mount point
>>> mp = dokan.mount(fs, "Q:\")
>>> mp.path
'Q:\'
>>> mp.unmount()
>>> fs = MemoryFS()
>>> # Mount in an existing empty folder.
>>> mp = dokan.mount(fs, "C:\test")
>>> mp.path
'C:\test'
>>> mp.unmount()

The above spawns a new background process to manage the Dokan 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
>>> dokan.mount(fs, "Q:\", foreground=True)

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

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

>>> from subprocess import PIPE
>>> mp = dokan.MountProcess(fs, "Q:\", stderr=PIPE)
>>> dokan_errors = mp.communicate()[1]

If you are exposing an untrusted filesystem, you may like to apply the wrapper class Win32SafetyFS before passing it into dokan. This will take a number of steps to avoid suspicious operations on windows, such as hiding autorun files.

The binding to Dokan is created via ctypes. Due to the very stable ABI of win32, this should work without further configuration on just about all systems with Dokan installed.

class fs.expose.dokan.FSOperations(fs, fsname='NTFS', volname='Dokan Volume', securityfolder='/home/docs')

Object delegating all DOKAN_OPERATIONS pointers to an FS object.

get_ops_struct()

Get a DOKAN_OPERATIONS struct mapping to our methods.

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

subprocess.Popen subclass managing a Dokan mount.

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

In order to be passed successfully to the new process, the FS object must be pickleable. Since win32 has no fork() this restriction is not likely to be lifted (see also the “multiprocessing” module)

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

unmount()

Cleanly unmount the Dokan filesystem, terminating this subprocess.

class fs.expose.dokan.Win32SafetyFS(wrapped_fs, allow_autorun=False)

FS wrapper for extra safety when mounting on win32.

This wrapper class provides some safety features when mounting untrusted filesystems on win32. Specifically:

  • hiding autorun files
  • removing colons from paths
fs.expose.dokan.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, then returns the negated error number. It also makes the function return zero instead of None as an indication of successful execution.

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

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

By default, this function spawns a new background process to manage the Dokan 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 Dokan 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 control the behavior of the final dokan mount point. Some interesting options include:

  • numthreads: number of threads to use for handling Dokan requests
  • fsname: name to display in explorer etc
  • flags: DOKAN_OPTIONS bitmask
  • securityfolder: folder path used to duplicate security rights on all folders
  • FSOperationsClass: custom FSOperations subclass to use
fs.expose.dokan.timeout_protect(func)

Method decorator to enable timeout protection during call.

This decorator adds an entry to the timeout protect queue before executing the function, and marks it as finished when the function exits.

fs.expose.dokan.unmount(path)

Unmount the given path.

This function unmounts the dokan path mounted at the given path. It works but may leave dangling processes; its better to use the “unmount” method on the MountProcess class if you have one.