0
# pyftpdlib
1

2
A comprehensive Python library providing high-level portable interface for building efficient, scalable and asynchronous FTP servers. It implements RFC-959 compliant FTP servers with advanced features including FTPS (RFC-4217), IPv6 (RFC-2428), Unicode file names (RFC-2640), and MLSD/MLST commands (RFC-3659). The library is designed for maximum performance using sendfile(2) system calls for uploads, asynchronous I/O with epoll/kqueue/select, and can optionally support multi-threaded/multi-process models.
3

4
## Package Information
5

6
- **Package Name**: pyftpdlib
7
- **Language**: Python
8
- **Installation**: `pip install pyftpdlib`
9

10
## Core Imports
11

12
```python
13
from pyftpdlib.authorizers import DummyAuthorizer
14
from pyftpdlib.handlers import FTPHandler
15
from pyftpdlib.servers import FTPServer
16
```
17

18
For SSL/TLS support:
19

20
```python
21
from pyftpdlib.handlers import TLS_FTPHandler
22
```
23

24
For system user authentication:
25

26
```python
27
# Unix systems
28
from pyftpdlib.authorizers import UnixAuthorizer
29

30
# Windows systems  
31
from pyftpdlib.authorizers import WindowsAuthorizer
32
```
33

34
For multi-threading/multi-processing:
35

36
```python
37
from pyftpdlib.servers import ThreadedFTPServer, MultiprocessFTPServer
38
```
39

40
## Basic Usage
41

42
```python
43
from pyftpdlib.authorizers import DummyAuthorizer
44
from pyftpdlib.handlers import FTPHandler
45
from pyftpdlib.servers import FTPServer
46

47
# Create a basic FTP server with virtual users
48
authorizer = DummyAuthorizer()
49
authorizer.add_user("user", "12345", "/home/giampaolo", perm="elradfmwMT")
50
authorizer.add_anonymous("/home/nobody")
51

52
handler = FTPHandler
53
handler.authorizer = authorizer
54

55
server = FTPServer(("127.0.0.1", 21), handler)
56
server.serve_forever()
57
```
58

59
Command line usage:
60

61
```bash
62
# Start FTP server with anonymous write access on port 2121
63
python3 -m pyftpdlib --write
64

65
# Start with custom settings
66
python3 -m pyftpdlib -i 0.0.0.0 -p 2121 -d /path/to/share -u username -P password
67
```
68

69
## Architecture
70

71
The pyftpdlib follows a hierarchical class structure that provides flexibility and extensibility:
72

73
- **FTPServer**: Accepts connections and dispatches them to handlers, with support for async, threaded, and multi-process models
74
- **FTPHandler**: Main server-protocol-interpreter implementing 40+ FTP commands per RFC-959
75
- **Authorizers**: Handle authentication and permissions for virtual users, Unix users, or Windows users
76
- **DTPHandler**: Manages data transfer operations with support for active/passive modes and SSL/TLS
77
- **AbstractedFS**: Cross-platform filesystem interface providing virtualized file system access
78

79
This design enables production-grade FTP servers with performance comparable to C-based servers while maintaining Python's flexibility and ease of customization.
80

81
## Capabilities
82

83
### FTP Servers
84

85
Core server implementations supporting different concurrency models and configuration options for building scalable FTP services.
86

87
```python { .api }
88
class FTPServer:
89
    def __init__(self, address_or_socket, handler, ioloop=None, backlog=100): ...
90
    def serve_forever(self, timeout=None, blocking=True, handle_exit=True, worker_processes=1): ...
91
    def close_all(self): ...
92

93
class ThreadedFTPServer(FTPServer): ...
94
class MultiprocessFTPServer(FTPServer): ...  # POSIX only
95
```
96

97
[FTP Servers](./servers.md)
98

99
### Authentication & Authorization
100

101
User authentication and permission management systems supporting virtual users, system users, and custom authorization schemes.
102

103
```python { .api }
104
class DummyAuthorizer:
105
    def add_user(self, username, password, homedir, perm='elr', msg_login="Login successful.", msg_quit="Goodbye."): ...
106
    def add_anonymous(self, homedir, **kwargs): ...
107
    def validate_authentication(self, username, password, handler): ...
108
    def has_perm(self, username, perm, path=None): ...
109

110
class UnixAuthorizer:  # Unix only
111
    def __init__(self, global_perm="elradfmwMT", allowed_users=None, rejected_users=None, 
112
                 require_valid_shell=True, anonymous_user=None, msg_login="Login successful.", 
113
                 msg_quit="Goodbye."): ...
114

115
class WindowsAuthorizer: ...  # Windows only
116
```
117

118
[Authentication & Authorization](./authorizers.md)
119

120
### FTP Protocol Handlers
121

122
Main FTP protocol implementation with support for 40+ FTP commands, SSL/TLS encryption, and extensive customization options.
123

124
```python { .api }
125
class FTPHandler:
126
    # Core configuration
127
    authorizer: Authorizer
128
    timeout: int = 300
129
    banner: str
130
    max_login_attempts: int = 3
131
    passive_ports: range = None
132
    masquerade_address: str = None
133
    use_sendfile: bool = True
134
    
135
    # SSL/TLS support
136
    def secure_connection(self, ssl_context): ...
137
    
138
    # Callback hooks
139
    def on_connect(self): ...
140
    def on_login(self, username): ...
141
    def on_file_sent(self, file): ...
142

143
class TLS_FTPHandler(FTPHandler):
144
    tls_control_required: bool = False
145
    tls_data_required: bool = False
146
    certfile: str = None
147
    keyfile: str = None
148
```
149

150
[FTP Protocol Handlers](./handlers.md)
151

152
### File System Interface
153

154
Cross-platform filesystem abstraction providing virtualized access to local and remote filesystems with security controls.
155

156
```python { .api }
157
class AbstractedFS:
158
    def __init__(self, root, cmd_channel): ...
159
    def chdir(self, path): ...
160
    def listdir(self, path): ...
161
    def open(self, filename, mode): ...
162
    def remove(self, path): ...
163
    def rename(self, src, dst): ...
164
    def mkdir(self, path): ...
165
    def chmod(self, path, mode): ...
166

167
class UnixFilesystem(AbstractedFS): ...  # POSIX only
168
```
169

170
[File System Interface](./filesystems.md)
171

172
### Async I/O Framework  
173

174
High-performance asynchronous I/O framework with platform-specific optimizations and network programming primitives.
175

176
```python { .api }
177
class IOLoop:
178
    READ: int = 1
179
    WRITE: int = 2
180
    
181
    @classmethod
182
    def instance(cls): ...
183
    def register(self, fd, instance, events): ...
184
    def loop(self, timeout=None, blocking=True): ...
185
    def call_later(self, seconds, target, *args, **kwargs): ...
186

187
class AsyncChat:
188
    def connect(self, addr): ...
189
    def send(self, data): ...
190
    def close(self): ...
191
```
192

193
[Async I/O Framework](./ioloop.md)
194

195
### Logging & Utilities
196

197
Logging configuration, process management, and utility functions for debugging and deployment.
198

199
```python { .api }
200
# Logging functions
201
def config_logging(level=logging.INFO, prefix='[%(levelname)1.1s %(asctime)s]', other_loggers=None): ...
202
def debug(s, inst=None): ...
203

204
# Process management  
205
def cpu_count(): ...
206
def fork_processes(number, max_restarts=100): ...
207

208
# Command line interface
209
def main(args=None): ...  # Entry point for python -m pyftpdlib
210
```
211

212
[Logging & Utilities](./utilities.md)
213

214
## Exception Classes
215

216
```python { .api }
217
class AuthorizerError(Exception): ...
218
class AuthenticationFailed(Exception): ...
219
class FilesystemError(Exception): ...
220
class RetryError(Exception): ...
221
```
222

223
## Constants
224

225
```python { .api }
226
__ver__: str = '2.0.1'
227
__author__: str = "Giampaolo Rodola' <g.rodola@gmail.com>"
228
__web__: str = 'https://github.com/giampaolo/pyftpdlib/'
229
```