0
# MFusepy
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: mfusepy
7
- **Language**: Python
8
- **Installation**: `pip install mfusepy`
9
- **Version**: 3.0.0
10
- **License**: ISC
11

12
## Core Imports
13

14
```python
15
import mfusepy
16
```
17

18
Common for filesystem operations:
19

20
```python
21
from mfusepy import FUSE, Operations, FuseOSError
22
```
23

24
For logging functionality:
25

26
```python
27
from mfusepy import LoggingMixIn
28
```
29

30
## Basic Usage
31

32
```python
33
from mfusepy import FUSE, Operations, FuseOSError
34
import os
35
import errno
36

37
class MemoryFS(Operations):
38
    """A simple in-memory filesystem."""
39
    
40
    def __init__(self):
41
        self.files = {}
42
        self.data = {}
43
        self.fd = 0
44
        
45
    def getattr(self, path, fh=None):
46
        """Get file attributes."""
47
        if path == '/':
48
            return {'st_mode': 0o755 | 0x4000, 'st_nlink': 2}
49
        elif path in self.files:
50
            return self.files[path]
51
        else:
52
            raise FuseOSError(errno.ENOENT)
53
    
54
    def readdir(self, path, fh):
55
        """Read directory contents."""
56
        return ['.', '..'] + [x[1:] for x in self.files if x != '/']
57
    
58
    def read(self, path, size, offset, fh):
59
        """Read file content."""
60
        return self.data[path][offset:offset + size]
61
    
62
    def create(self, path, mode, fi=None):
63
        """Create and open a new file."""
64
        self.files[path] = {'st_mode': mode, 'st_nlink': 1, 'st_size': 0}
65
        self.data[path] = b''
66
        self.fd += 1
67
        return self.fd
68

69
# Mount the filesystem
70
if __name__ == '__main__':
71
    filesystem = MemoryFS()
72
    fuse = FUSE(filesystem, '/tmp/mymount', foreground=True)
73
```
74

75
## Architecture
76

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

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

84
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.
85

86
## Capabilities
87

88
### Core Filesystem Interface
89

90
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.
91

92
```python { .api }
93
from typing import Optional, Any, Iterable, Union
94

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

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

105
# Type aliases
106
ReadDirResult = Iterable[Union[str, tuple[str, dict[str, int], int], tuple[str, int, int]]]
107
```
108

109
[Core Classes](./core-classes.md)
110

111
### Exception Handling
112

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

115
```python { .api }
116
class FuseOSError(OSError):
117
    def __init__(self, errno): ...
118

119
class LoggingMixIn: ...
120
```
121

122
[Exception Handling](./exception-handling.md)
123

124
### Utility Functions
125

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

128
```python { .api }
129
def fuse_get_context() -> tuple[int, int, int]: ...
130
def fuse_exit() -> None: ...
131
def get_fuse_version(libfuse) -> tuple[int, int]: ...
132
def time_of_timespec(ts, use_ns: bool = False) -> float: ...
133
```
134

135
[Utilities](./utilities.md)
136

137
## Platform Support
138

139
- **Linux**: Full FUSE 2.6+ and FUSE 3.x support
140
- **macOS**: MacFUSE/OSXFUSE compatibility  
141
- **FreeBSD/OpenBSD**: Native FUSE support
142
- **Windows/Cygwin**: WinFsp integration
143
- **Architectures**: x86, x86_64, ARM, PowerPC, MIPS
144

145
## Key Features
146

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