source: doc/README.txt @ 2050:f2974f53005e

Last change on this file since 2050:f2974f53005e was 2050:f2974f53005e, checked in by Stefan Schwarzer <sschwarzer@…>, 8 months ago
Patch version info for release
File size: 4.0 KB
Line 
1ftputil
2=======
3
4Purpose
5-------
6
7ftputil is a high-level FTP client library for the Python programming
8language. ftputil implements a virtual file system for accessing FTP
9servers, that is, it can generate file-like objects for remote files.
10The library supports many functions similar to those in the os,
11os.path and shutil modules. ftputil has convenience functions for
12conditional uploads and downloads, and handles FTP clients and servers
13in different timezones.
14
15What's new?
16-----------
17
18Backward-incompatible changes
19~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20
21This ftputil version isn't fully backward-compatible with the previous
22version due to changes in the `ftplib` module in the standard
23library of Python 3.9 [1].
24
25That said, if you only deal with directory and file paths which solely
26consist of ASCII characters, this change doesn't affect you.
27
28Here are some details. You can find more in the ftputil documentation
29[2] and in ticket #143 [3].
30
31Internally, ftputil uses `ftplib.FTP` or compatible classes to perform
32most low-level FTP operations. In Python 3.8 and before, the default
33encoding for FTP paths was latin-1, but there was no official
34documentation on using a different encoding. In Python 3.9, the
35default encoding changed to UTF-8 and the encoding is configurable
36with an `ftplib.FTP` constructor argument.
37
38The documentation of ftputil 4.0.0 and earlier stated:
39- ftputil uses latin-1 encoding for paths
40- ftputil uses `ftplib.FTP` as the default session factory
41
42With the change of the default encoding in Python 3.9 these two
43statements are contradictory. To resolve the conflict, the new
44behavior of ftputil is:
45- ftputil uses `ftplib.FTP` as default session factory, but explicitly
46  sets the path encoding to latin-1 (regardless of the Python
47  version). This is the same behavior as in ftputil 4.0.0 or earlier
48  if running under Python 3.8 or earlier.
49- If client code uses a custom session factory (i. e. the
50  `session_factory` argument of the `FTPHost` constructor), ftputil
51  will take the path encoding to use for `bytes` paths from the
52  `encoding` attribute of an FTP session from this factory. If there's
53  no such attribute, an exception is raised.
54
55Other changes
56~~~~~~~~~~~~~
57
58`ftputil.session.session_factory` got a new keyword argument
59`encoding` to set the path encoding of the sessions created by the
60factory. If the argument isn't specified, the path encoding will be
61taken from the `base_class` argument. (This means that the encoding
62will be different for `ftplib.FTP` in Python 3.8 or earlier vs.
63Python 3.9 or later.)
64
65Documentation
66-------------
67
68The documentation for ftputil can be found in the file ftputil.txt
69(reStructuredText format) or ftputil.html (recommended, generated from
70ftputil.txt).
71
72Prerequisites
73-------------
74
75To use ftputil, you need Python, at least version 3.6.
76
77Installation
78------------
79
80*If you have an older version of ftputil installed, delete it or
81move it somewhere else, so that it doesn't conflict with the new
82version.*
83
84You can install ftputil with pip:
85
86  pip install ftputil
87
88Unless you're installing ftputil in a virtual environment, you'll
89probably need root/administrator privileges.
90
91Note that ftputil versions with a different major version number won't
92be fully backward-compatible with the previous version. Examples are
93the changes from 2.8 to 3.0 and from 3.4 to 4.0.0.
94
95License
96-------
97
98ftputil is open source software. It is distributed under the
99new/modified/revised BSD license (see
100http://opensource.org/licenses/BSD-3-Clause ).
101
102Authors
103-------
104
105Stefan Schwarzer <sschwarzer@sschwarzer.net>
106
107Evan Prodromou <evan@bad.dynu.ca> (lrucache module)
108
109(See also the file `doc/contributors.txt`.)
110
111Please provide feedback! It's certainly appreciated. :-)
112
113
114[1] https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-python-api
115    "The encoding parameter has been added to the classes ftplib.FTP
116    and ftplib.FTP_TLS as a keyword-only parameter, and the default
117    encoding is changed from Latin-1 to UTF-8 to follow RFC 2640."
118[2] https://ftputil.sschwarzer.net/trac/wiki/Documentation
119[3] https://ftputil.sschwarzer.net/trac/ticket/143
Note: See TracBrowser for help on using the repository browser.