| 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 |
|---|
