Programming Python (112 page)

#!/usr/local/bin/python
"""
A Python script to download and play a media file by FTP.
Uses getfile.py, a utility module which encapsulates FTP step.
"""
import getfile
from getpass import getpass
filename = 'monkeys.jpg'
# fetch with utility
getfile.getfile(file=filename,
site='ftp.rmi.net',
dir ='.',
user=('lutz', getpass('Pswd?')),
refetch=True)
# rest is the same
if input('Open file?') in ['Y', 'y']:
from PP4E.System.Media.playfile import playfile
playfile(filename)

retrbinary


This method
downloads the requested file in binary mode,
sending its bytes in chunks to a supplied function, without
line-feed mapping. Typically, the supplied function is a write
method of an open local file object, such that the bytes are
placed in the local file on the client.

retrlines


This method
downloads the requested file in ASCII text mode,
sending each line of text to a supplied function with all
end-of-line characters stripped. Typically, the supplied
function adds a
\n
newline
(mapped appropriately for the client machine), and writes the
line to a local file.

Example 13-4. PP4E\Internet\Ftp\getfile.py

#!/usr/local/bin/python
"""
Fetch an arbitrary file by FTP.  Anonymous FTP unless you pass a
user=(name, pswd) tuple. Self-test FTPs a test file and site.
"""
from ftplib  import FTP          # socket-based FTP tools
from os.path import exists       # file existence test
def getfile(file, site, dir, user=(), *, verbose=True, refetch=False):
"""
fetch a file by ftp from a site/directory
anonymous or real login, binary transfer
"""
if exists(file) and not refetch:
if verbose: print(file, 'already fetched')
else:
if verbose: print('Downloading', file)
local = open(file, 'wb')                # local file of same name
try:
remote = FTP(site)                  # connect to FTP site
remote.login(*user)                 # anonymous=() or (name, pswd)
remote.cwd(dir)
remote.retrbinary('RETR ' + file, local.write, 1024)
remote.quit()
finally:
local.close()                       # close file no matter what
if verbose: print('Download done.')     # caller handles exceptions
if __name__ == '__main__':
from getpass import getpass
file = 'monkeys.jpg'
dir  = '.'
site = 'ftp.rmi.net'
user = ('lutz', getpass('Pswd?'))
getfile(file, site, dir, user)

FTP mode

The
getfile
function in this script runs in anonymous FTP mode
by default, but a two-item tuple containing a username and
password string may be passed to the
user
argument in order to log in to
the remote server in nonanonymous mode. To use anonymous FTP,
either don’t pass the
user
argument or pass it an empty tuple,
()
. The FTP object
login
method allows two optional
arguments to denote a username and password, and the
function(*args)
call syntax in
Example 13-4
sends it
whatever argument tuple you pass to
user
as individual arguments.

Processing modes

If passed, the last two arguments (
verbose
,
refetch
) allow us to turn off status
messages printed to the
stdout
stream (perhaps undesirable in
a GUI context) and to force downloads to happen even if the file
already exists locally (the download overwrites the existing
local file).

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,
exceptions 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 requirements; 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 directories if
needed. (We could instead assume
filename
is the local file’s name, and strip the local directory with
os.path.split
to get the
remote name, or accept two distinct filename arguments—local and
remote.)

• storbinary
method
  can be used to upload bytes from an open local file
  object
  

• storlines
method
  can be used to upload text in ASCII mode from an
  open local file object
  

Example 13-5. PP4E\Internet\Ftp\putfile.py

#!/usr/local/bin/python
"""
Store an arbitrary file by FTP in binary mode.  Uses anonymous
ftp unless you pass in a user=(name, pswd) tuple of arguments.
"""
import ftplib                    # socket-based FTP tools
def putfile(file, site, dir, user=(), *, verbose=True):
"""
store a file by ftp to a site/directory
anonymous or real login, binary transfer
"""
if verbose: print('Uploading', file)
local  = open(file, 'rb')               # local file of same name
remote = ftplib.FTP(site)               # connect to FTP site
remote.login(*user)                     # anonymous or real login
remote.cwd(dir)
remote.storbinary('STOR ' + file, local, 1024)
remote.quit()
local.close()
if verbose: print('Upload done.')
if __name__ == '__main__':
site = 'ftp.rmi.net'
dir  = '.'
import sys, getpass
pswd = getpass.getpass(site + ' pswd?')                # filename on cmdline
putfile(sys.argv[1], site, dir, user=('lutz', pswd))   # nonanonymous login