MFusepy

A Python library that provides ctypes bindings for the high-level FUSE (Filesystem in Userspace) API, supporting both libfuse 2 and 3. This modern fork of the unmaintained fusepy enables developers to create custom filesystems in Python that run in user space with performance optimizations and cross-platform compatibility.

Package Information

• Package Name: mfusepy
• Language: Python
• Installation: pip install mfusepy
• Version: 3.0.0
• License: ISC

Core Imports

import mfusepy

Common for filesystem operations:

from mfusepy import FUSE, Operations, FuseOSError

For logging functionality:

from mfusepy import LoggingMixIn

Basic Usage

from mfusepy import FUSE, Operations, FuseOSError
import os
import errno

class MemoryFS(Operations):
    """A simple in-memory filesystem."""
    
    def __init__(self):
        self.files = {}
        self.data = {}
        self.fd = 0
        
    def getattr(self, path, fh=None):
        """Get file attributes."""
        if path == '/':
            return {'st_mode': 0o755 | 0x4000, 'st_nlink': 2}
        elif path in self.files:
            return self.files[path]
        else:
            raise FuseOSError(errno.ENOENT)
    
    def readdir(self, path, fh):
        """Read directory contents."""
        return ['.', '..'] + [x[1:] for x in self.files if x != '/']
    
    def read(self, path, size, offset, fh):
        """Read file content."""
        return self.data[path][offset:offset + size]
    
    def create(self, path, mode, fi=None):
        """Create and open a new file."""
        self.files[path] = {'st_mode': mode, 'st_nlink': 1, 'st_size': 0}
        self.data[path] = b''
        self.fd += 1
        return self.fd

# Mount the filesystem
if __name__ == '__main__':
    filesystem = MemoryFS()
    fuse = FUSE(filesystem, '/tmp/mymount', foreground=True)

Architecture

MFusepy uses a layered architecture that bridges Python and the native FUSE library:

• FUSE Class: Main interface that manages the mount process and callback translation
• Operations Base Class: Abstract base defining filesystem operations to be implemented
• C Structures: Platform-specific ctypes structures for FUSE library interaction
• Callback Translation: Optimized layer converting between Python and C function calls

The library automatically detects the platform and FUSE version, selecting appropriate C structures and function signatures for maximum compatibility across Linux, macOS, FreeBSD, OpenBSD, and Windows/Cygwin environments.

Capabilities

Core Filesystem Interface

Primary FUSE class for mounting filesystems and Operations base class for implementing filesystem behavior. The Operations class provides 33 operations covering all filesystem functionality. These provide the essential framework for creating custom filesystems in Python.

from typing import Optional, Any, Iterable, Union

class FUSE:
    def __init__(self, operations, mountpoint: str, raw_fi: bool = False, 
                 encoding: str = 'utf-8', **kwargs) -> None: ...

class Operations:
    def getattr(self, path: str, fh: Optional[int] = None) -> dict[str, Any]: ...
    def readdir(self, path: str, fh: int) -> ReadDirResult: ...
    def read(self, path: str, size: int, offset: int, fh: int) -> bytes: ...
    def write(self, path: str, data, offset: int, fh: int) -> int: ...

# Type aliases
ReadDirResult = Iterable[Union[str, tuple[str, dict[str, int], int], tuple[str, int, int]]]

Core Classes

Exception Handling

Structured error handling for FUSE operations with errno-based error codes and logging support for debugging filesystem implementations.

class FuseOSError(OSError):
    def __init__(self, errno): ...

class LoggingMixIn: ...

Exception Handling

Utility Functions

Helper functions for context management, library version detection, time handling, and decorators for logging and method validation.

def fuse_get_context() -> tuple[int, int, int]: ...
def fuse_exit() -> None: ...
def get_fuse_version(libfuse) -> tuple[int, int]: ...
def time_of_timespec(ts, use_ns: bool = False) -> float: ...

Utilities

Platform Support

• Linux: Full FUSE 2.6+ and FUSE 3.x support
• macOS: MacFUSE/OSXFUSE compatibility
• FreeBSD/OpenBSD: Native FUSE support
• Windows/Cygwin: WinFsp integration
• Architectures: x86, x86_64, ARM, PowerPC, MIPS

Key Features

1. Cross-platform compatibility: Automatic platform detection and adaptation
2. FUSE version flexibility: Supports both FUSE 2.x and 3.x APIs
3. Performance optimizations: Improved callback translation layer over fusepy
4. Type safety: Comprehensive type hints throughout the API
5. Raw mode support: Optional access to raw FUSE structures for advanced use cases
6. Comprehensive logging: Built-in debugging and monitoring capabilities