1 | ftputil |
---|
2 | ======= |
---|
3 | |
---|
4 | Purpose |
---|
5 | ------- |
---|
6 | |
---|
7 | ftputil is a high-level FTP client library for the Python programming |
---|
8 | language. ftputil implements a virtual file system for accessing FTP |
---|
9 | servers, that is, it can generate file-like objects for remote files. |
---|
10 | The library supports many functions similar to those in the os, |
---|
11 | os.path and shutil modules. ftputil has convenience functions for |
---|
12 | conditional uploads and downloads, and handles FTP clients and servers |
---|
13 | in different timezones. |
---|
14 | |
---|
15 | What's new? |
---|
16 | ----------- |
---|
17 | |
---|
18 | Backward-incompatible changes |
---|
19 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
20 | |
---|
21 | This ftputil version isn't fully backward-compatible with the previous |
---|
22 | version due to changes in the `ftplib` module in the standard |
---|
23 | library of Python 3.9 [1]. |
---|
24 | |
---|
25 | That said, if you only deal with directory and file paths which solely |
---|
26 | consist of ASCII characters, this change doesn't affect you. |
---|
27 | |
---|
28 | Here are some details. You can find more in the ftputil documentation |
---|
29 | [2] and in ticket #143 [3]. |
---|
30 | |
---|
31 | Internally, ftputil uses `ftplib.FTP` or compatible classes to perform |
---|
32 | most low-level FTP operations. In Python 3.8 and before, the default |
---|
33 | encoding for FTP paths was latin-1, but there was no official |
---|
34 | documentation on using a different encoding. In Python 3.9, the |
---|
35 | default encoding changed to UTF-8 and the encoding is configurable |
---|
36 | with an `ftplib.FTP` constructor argument. |
---|
37 | |
---|
38 | The 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 | |
---|
42 | With the change of the default encoding in Python 3.9 these two |
---|
43 | statements are contradictory. To resolve the conflict, the new |
---|
44 | behavior 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 | |
---|
55 | Other 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 |
---|
60 | factory. If the argument isn't specified, the path encoding will be |
---|
61 | taken from the `base_class` argument. (This means that the encoding |
---|
62 | will be different for `ftplib.FTP` in Python 3.8 or earlier vs. |
---|
63 | Python 3.9 or later.) |
---|
64 | |
---|
65 | Documentation |
---|
66 | ------------- |
---|
67 | |
---|
68 | The documentation for ftputil can be found in the file ftputil.txt |
---|
69 | (reStructuredText format) or ftputil.html (recommended, generated from |
---|
70 | ftputil.txt). |
---|
71 | |
---|
72 | Prerequisites |
---|
73 | ------------- |
---|
74 | |
---|
75 | To use ftputil, you need Python, at least version 3.6. |
---|
76 | |
---|
77 | Installation |
---|
78 | ------------ |
---|
79 | |
---|
80 | *If you have an older version of ftputil installed, delete it or |
---|
81 | move it somewhere else, so that it doesn't conflict with the new |
---|
82 | version.* |
---|
83 | |
---|
84 | You can install ftputil with pip: |
---|
85 | |
---|
86 | pip install ftputil |
---|
87 | |
---|
88 | Unless you're installing ftputil in a virtual environment, you'll |
---|
89 | probably need root/administrator privileges. |
---|
90 | |
---|
91 | Note that ftputil versions with a different major version number won't |
---|
92 | be fully backward-compatible with the previous version. Examples are |
---|
93 | the changes from 2.8 to 3.0 and from 3.4 to 4.0.0. |
---|
94 | |
---|
95 | License |
---|
96 | ------- |
---|
97 | |
---|
98 | ftputil is open source software. It is distributed under the |
---|
99 | new/modified/revised BSD license (see |
---|
100 | http://opensource.org/licenses/BSD-3-Clause ). |
---|
101 | |
---|
102 | Authors |
---|
103 | ------- |
---|
104 | |
---|
105 | Stefan Schwarzer <sschwarzer@sschwarzer.net> |
---|
106 | |
---|
107 | Evan Prodromou <evan@bad.dynu.ca> (lrucache module) |
---|
108 | |
---|
109 | (See also the file `doc/contributors.txt`.) |
---|
110 | |
---|
111 | Please 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 |
---|