These two arguments are coded as Python 3.X default keyword-only arguments, so
if used they must be passed by name, not position. The user argument instead can
be passed either way, if it is passed at all. Keyword-only arguments here prevent
passed verbose or refetch values from being incorrectly matched against the user
argument if the user value is actually omitted in a call.Exception protocol
The caller is expected to handle exceptions; this function wraps downloads in a
try/finally statement to guarantee that the local output file is closed, but it lets
exceptions propagate. If used in a GUI or run from a thread, for instance, excep-
tions may require special handling unknown in this file.
Self-test
If run standalone, this file downloads an image file again from my website as a self-
test (configure for your server and file as desired), but the function will normally
be passed FTP filenames, site names, and directory names as well.
File mode
As in earlier examples, this script is careful to open the local output file in wb binary
mode to suppress end-line mapping and conform to Python 3.X’s Unicode string
model. As we learned in Chapter 4, it’s not impossible that true binary datafiles
may have bytes whose value is equal to a \n line-feed character; opening in w text
mode instead would make these bytes automatically expand to a \r\n two-byte
sequence when written locally on Windows. This is only an issue when run on
Windows; mode w doesn’t change end-lines elsewhere.
As we also learned in Chapter 4, though, binary mode is required to suppress the
automatic Unicode translations performed for text in Python 3.X. Without binary
mode, Python would attempt to encode fetched data when written per a default
or passed Unicode encoding scheme, which might fail for some types of fetched
text and would normally fail for truly binary data such as images and audio.
Because retrbinary writes bytes strings in 3.X, we really cannot open the output
file in text mode anyhow, or write will raise exceptions. Recall that in 3.X text-
mode files require str strings, and binary mode files expect bytes. Since
retrbinary writes bytes and retrlines writes str, they implicitly require binary
and text-mode output files, respectively. This constraint is irrespective of end-line
or Unicode issues, but it effectively accomplishes those goals as well.
As we’ll see in later examples, text-mode retrievals have additional encoding re-
quirements; in fact, ftplib will turn out to be a good example of the impacts of
Python 3.X’s Unicode string model on real-world code. By always using binary
mode in the script here, we sidestep the issue altogether.
Directory model
This function currently uses the same filename to identify both the remote file and
the local file where the download should be stored. As such, it should be run in
the directory where you want the file to show up; use os.chdir to move to direc-
tories if needed. (We could instead assume filename is the local file’s name, and
Transferring Files with ftplib | 863