README.rst
1.. image:: http://pepy.tech/badge/pyftpdlib
2 :target: http://pepy.tech/project/pyftpdlib
3 :alt: Downloads
4
5.. image:: https://img.shields.io/travis/giampaolo/pyftpdlib/master.svg?maxAge=3600&label=Linux%20/%20OSX
6 :target: https://travis-ci.org/giampaolo/pyftpdlib
7 :alt: Linux tests (Travis)
8
9.. image:: https://img.shields.io/appveyor/ci/giampaolo/pyftpdlib/master.svg?maxAge=3600&label=Windows
10 :target: https://ci.appveyor.com/project/giampaolo/pyftpdlib
11 :alt: Windows tests (Appveyor)
12
13.. image:: https://coveralls.io/repos/github/giampaolo/pyftpdlib/badge.svg?branch=master
14 :target: https://coveralls.io/github/giampaolo/pyftpdlib?branch=master
15 :alt: Test coverage (coverall.io)
16
17.. image:: https://readthedocs.org/projects/pyftpdlib/badge/?version=latest
18 :target: http://pyftpdlib.readthedocs.io/en/latest/?badge=latest
19 :alt: Documentation Status
20
21.. image:: https://img.shields.io/pypi/v/pyftpdlib.svg?label=pypi
22 :target: https://pypi.python.org/pypi/pyftpdlib/
23 :alt: Latest version
24
25.. image:: https://img.shields.io/github/stars/giampaolo/pyftpdlib.svg
26 :target: https://github.com/giampaolo/pyftpdlib/
27 :alt: Github stars
28
29.. image:: https://img.shields.io/pypi/l/pyftpdlib.svg
30 :target: https://pypi.python.org/pypi/pyftpdlib/
31 :alt: License
32
33Quick links
34===========
35
36- `Home <https://github.com/giampaolo/pyftpdlib>`__
37- `Documentation <http://pyftpdlib.readthedocs.io>`__
38- `Download <https://pypi.python.org/pypi/pyftpdlib/>`__
39- `Blog <http://grodola.blogspot.com/search/label/pyftpdlib>`__
40- `Mailing list <http://groups.google.com/group/pyftpdlib/topics>`__
41- `What's new <https://github.com/giampaolo/pyftpdlib/blob/master/HISTORY.rst>`__
42
43About
44=====
45
46Python FTP server library provides a high-level portable interface to easily
47write very efficient, scalable and asynchronous FTP servers with Python. It is
48the most complete `RFC-959 <http://www.faqs.org/rfcs/rfc959.html>`__ FTP server
49implementation available for `Python <http://www.python.org/>`__ programming
50language and it's used in projects like
51`Google Chromium <http://www.code.google.com/chromium/>`__ and
52`Bazaar <http://bazaar-vcs.org/>`__ and included in
53`Debian <http://packages.debian.org/sid/python-pyftpdlib>`__,
54`Fedora <https://admin.fedoraproject.org/pkgdb/packages/name/pyftpdlib>`__ and
55`FreeBSD <http://www.freshports.org/ftp/py-pyftpdlib/>`__ package repositories.
56
57Features
58========
59
60- Extremely **lightweight**, **fast** and **scalable** (see
61 `why <https://github.com/giampaolo/pyftpdlib/issues/203>`__ and
62 `benchmarks <http://pyftpdlib.readthedocs.io/en/latest/benchmarks.html>`__).
63- Uses **sendfile(2)** (see `pysendfile <https://github.com/giampaolo/pysendfile>`__)
64 system call for uploads.
65- Uses epoll() / kqueue() / select() to handle concurrency asynchronously.
66- ...But can optionally skip to a
67 `multiple thread / process <http://pyftpdlib.readthedocs.io/en/latest/tutorial.html#changing-the-concurrency-model>`__
68 model (as in: you'll be free to block or use slow filesystems).
69- Portable: entirely written in pure Python; works with Python from **2.6** to
70 **3.5** by using a single code base.
71- Supports **FTPS** (`RFC-4217 <http://tools.ietf.org/html/rfc4217>`__),
72 **IPv6** (`RFC-2428 <ftp://ftp.rfc-editor.org/in-notes/rfc2428.txt>`__),
73 **Unicode** file names (`RFC-2640 <http://tools.ietf.org/html/rfc2640>`__),
74 **MLSD/MLST** commands (`RFC-3659 <ftp://ftp.rfc-editor.org/in-notes/rfc3659.txt>`__).
75- Support for virtual users and virtual filesystem.
76- Extremely flexible system of "authorizers" able to manage both "virtual" and
77 "real" users on on both
78 `UNIX <http://pyftpdlib.readthedocs.io/en/latest/tutorial.html#unix-ftp-server>`__
79 and
80 `Windows <http://pyftpdlib.readthedocs.io/en/latest/tutorial.html#windows-ftp-server>`__.
81- `Test coverage <https://github.com/giampaolo/pyftpdlib/blob/master/pyftpdlib/test/>`__
82 close to 100%.
83
84Performances
85============
86
87Despite being written in an intepreted language, pyftpdlib has transfer rates
88superior to most common UNIX FTP servers. It also scales better since whereas
89vsftpd and proftpd use multiple processes to achieve concurrency, pyftpdlib
90will only use one process and handle concurrency asynchronously (see
91`the C10K problem <http://www.kegel.com/c10k.html>`__). Here are some
92`benchmarks <https://github.com/giampaolo/pyftpdlib/blob/master/scripts/ftpbench>`__
93made against my Linux 3.0.0 box, Intel core-duo 3.1 Ghz:
94
95pyftpdlib vs. proftpd 1.3.4
96---------------------------
97
98+-----------------------------------------+----------------+----------------+-------------+
99| **benchmark type** | **pyftpdlib** | **proftpd** | **speedup** |
100+-----------------------------------------+----------------+----------------+-------------+
101| STOR (client -> server) | 585.90 MB/sec | 600.49 MB/sec | -0.02x |
102+-----------------------------------------+----------------+----------------+-------------+
103| RETR (server -> client) | 1652.72 MB/sec | 1524.05 MB/sec | **+0.08** |
104+-----------------------------------------+----------------+----------------+-------------+
105| 300 concurrent clients (connect, login) | 0.19 secs | 9.98 secs | **+51x** |
106+-----------------------------------------+----------------+----------------+-------------+
107| STOR (1 file with 300 idle clients) | 585.59 MB/sec | 518.55 MB/sec | **+0.1x** |
108+-----------------------------------------+----------------+----------------+-------------+
109| RETR (1 file with 300 idle clients) | 1497.58 MB/sec | 1478.19 MB/sec | 0x |
110+-----------------------------------------+----------------+----------------+-------------+
111| 300 concurrent clients (RETR 10M file) | 3.41 secs | 3.60 secs | **+0.05x** |
112+-----------------------------------------+----------------+----------------+-------------+
113| 300 concurrent clients (STOR 10M file) | 8.60 secs | 11.56 secs | **+0.3x** |
114+-----------------------------------------+----------------+----------------+-------------+
115| 300 concurrent clients (QUIT) | 0.03 secs | 0.39 secs | **+12x** |
116+-----------------------------------------+----------------+----------------+-------------+
117
118pyftpdlib vs. vsftpd 2.3.5
119--------------------------
120
121+-----------------------------------------+----------------+----------------+-------------+
122| **benchmark type** | **pyftpdlib** | **vsftpd** | **speedup** |
123+-----------------------------------------+----------------+----------------+-------------+
124| STOR (client -> server) | 585.90 MB/sec | 611.73 MB/sec | -0.04x |
125+-----------------------------------------+----------------+----------------+-------------+
126| RETR (server -> client) | 1652.72 MB/sec | 1512.92 MB/sec | **+0.09** |
127+-----------------------------------------+----------------+----------------+-------------+
128| 300 concurrent clients (connect, login) | 0.19 secs | 20.39 secs | **+106x** |
129+-----------------------------------------+----------------+----------------+-------------+
130| STOR (1 file with 300 idle clients) | 585.59 MB/sec | 610.23 MB/sec | -0.04x |
131+-----------------------------------------+----------------+----------------+-------------+
132| RETR (1 file with 300 idle clients) | 1497.58 MB/sec | 1493.01 MB/sec | 0x |
133+-----------------------------------------+----------------+----------------+-------------+
134| 300 concurrent clients (RETR 10M file) | 3.41 secs | 3.67 secs | **+0.07x** |
135+-----------------------------------------+----------------+----------------+-------------+
136| 300 concurrent clients (STOR 10M file) | 8.60 secs | 9.82 secs | **+0.07x** |
137+-----------------------------------------+----------------+----------------+-------------+
138| 300 concurrent clients (QUIT) | 0.03 secs | 0.01 secs | +0.14x |
139+-----------------------------------------+----------------+----------------+-------------+
140
141For more benchmarks see `here <http://pyftpdlib.readthedocs.io/en/latest/benchmarks.html>`__.
142
143Quick start
144===========
145
146.. code-block:: python
147
148 >>> from pyftpdlib.authorizers import DummyAuthorizer
149 >>> from pyftpdlib.handlers import FTPHandler
150 >>> from pyftpdlib.servers import FTPServer
151 >>>
152 >>> authorizer = DummyAuthorizer()
153 >>> authorizer.add_user("user", "12345", "/home/giampaolo", perm="elradfmwMT")
154 >>> authorizer.add_anonymous("/home/nobody")
155 >>>
156 >>> handler = FTPHandler
157 >>> handler.authorizer = authorizer
158 >>>
159 >>> server = FTPServer(("127.0.0.1", 21), handler)
160 >>> server.serve_forever()
161 [I 13-02-19 10:55:42] >>> starting FTP server on 127.0.0.1:21 <<<
162 [I 13-02-19 10:55:42] poller: <class 'pyftpdlib.ioloop.Epoll'>
163 [I 13-02-19 10:55:42] masquerade (NAT) address: None
164 [I 13-02-19 10:55:42] passive ports: None
165 [I 13-02-19 10:55:42] use sendfile(2): True
166 [I 13-02-19 10:55:45] 127.0.0.1:34178-[] FTP session opened (connect)
167 [I 13-02-19 10:55:48] 127.0.0.1:34178-[user] USER 'user' logged in.
168 [I 13-02-19 10:56:27] 127.0.0.1:34179-[user] RETR /home/giampaolo/.vimrc completed=1 bytes=1700 seconds=0.001
169 [I 13-02-19 10:56:39] 127.0.0.1:34179-[user] FTP session closed (disconnect).
170
171`other code samples <http://pyftpdlib.readthedocs.io/en/latest/tutorial.html>`__
172
173Donate
174======
175
176A lot of time and effort went into making pyftpdlib as it is right now.
177If you feel pyftpdlib is useful to you or your business and want to support its
178future development please consider donating me
179(`Giampaolo Rodola' <http://grodola.blogspot.com/p/about.html>`_) some money.
180I only ask for a small donation, but of course I appreciate any amount.
181
182.. image:: https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif
183 :target: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ZSSF7G42VA2XE
184 :alt: Donate via PayPal
185
186Don't want to donate money? Then maybe you could
187`write me a recommendation on Linkedin <http://www.linkedin.com/in/grodola>`_.
188In case you're using pyftpdlib into a software of yours
189`mail me <http://grodola.blogspot.com/p/about.html>`_ and I'll add your
190software to the
191`adoptions list <http://pyftpdlib.readthedocs.io/en/latest/adoptions.html>`__.
192
193Trademarks
194==========
195
196Some famous trademarks which adopted pyftpdlib (`complete list <http://pyftpdlib.readthedocs.io/en/latest/adoptions.html>`__).
197
198.. image:: docs/images/chrome.jpg
199 :target: http://www.google.com/chrome
200.. image:: docs/images/debian.png
201 :target: http://www.debian.org
202.. image:: docs/images/fedora.png
203 :target: http://fedoraproject.org/
204.. image:: docs/images/freebsd.gif
205 :target: http://www.freebsd.org
206.. image:: docs/images/openerp.jpg
207 :target: http://openerp.com
208.. image:: docs/images/bazaar.jpg
209 :target: http://bazaar-vcs.org
210.. image:: docs/images/bitsontherun.png
211 :target: http://www.bitsontherun.com
212.. image:: docs/images/openvms.png
213 :target: http://www.openvms.org/
214.. image:: docs/images/smartfile.png
215 :target: https://www.smartfile.com/
216
