Содержание страницы

20.11. `ftplib` – клиент протокола FTP¶ftplib – FTP protocol client

Этот модуль определяет класс FTP и несколько связанных с ним элементов. Класс FTP реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем urllib.request для обработки URL, использующих FTP. Для получения дополнительной информации о FTP (File Transfer Protocol) см. RFC 959.

Вот пример сеанса с использованием модуля ftplib:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.cwi.nl')   # подключение к хосту, порт по умолчанию
>>> ftp.login()               # пользователь anonymous, пароль anonymous@
>>> ftp.retrlines('LIST')     # список содержимого каталога
total 24418
drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .
dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..
-rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX
 .
 .
 .
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()

Модуль определяет следующие элементы:

class ftplib.FTP(host='', user='', passwd='', acct=''[, timeout])¶: Возвращает новый экземпляр класса FTP. Когда указан host, вызывается метод connect(host). Когда указан user, дополнительно вызывается метод login(user, passwd, acct) (где passwd и acct по умолчанию равны пустой строке, если не заданы). Необязательный параметр timeout задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).

exception ftplib.error_reply¶: Исключение, возникающее при получении неожиданного ответа от сервера.

exception ftplib.error_temp¶: Исключение, возникающее при получении кода ошибки, указывающего на временную ошибку (коды ответов в диапазоне 400–499).

exception ftplib.error_perm¶: Исключение, возникающее при получении кода ошибки, указывающего на постоянную ошибку (коды ответов в диапазоне 500–599).

exception ftplib.error_proto¶: Исключение, возникающее при получении ответа от сервера, который не соответствует спецификациям ответов протокола передачи файлов (File Transfer Protocol), то есть начинается с цифры в диапазоне 1–5.

ftplib.all_errors¶: Набор всех исключений (в виде кортежа), которые могут возбуждать методы экземпляров FTP в результате проблем с FTP-соединением (в отличие от ошибок программирования со стороны вызывающего кода). В этот набор входят четыре исключения, перечисленные выше, а также socket.error и IOError.

См. также

Модуль netrc: Синтаксический анализатор формата файла .netrc. Файл .netrc обычно используется FTP-клиентами для загрузки информации об аутентификации пользователя перед запросом к пользователю.

Файл Tools/scripts/ftpmirror.py в дистрибутиве исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля ftplib. Его можно использовать как расширенный пример применения этого модуля.

20.11.1. Объекты FTP¶FTP Objects

Некоторые методы доступны в двух вариантах: один для работы с текстовыми файлами, другой для двоичных файлов. Они названы по имени используемой команды, за которым следует lines для текстовой версии или binary для двоичной версии.

Экземпляры FTP имеют следующие методы:

FTP.set_debuglevel(level)¶: Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, 0, не даёт отладочного вывода. Значение 1 даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение 2 или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.

FTP.connect(host='', port=0[, timeout])¶

Подключается к указанному хосту и порту. Номер порта по умолчанию – 21, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения.

Необязательный параметр timeout задаёт тайм-аут в секундах для попытки подключения. Если timeout не передан, будет использована глобальная настройка тайм-аута по умолчанию.

FTP.getwelcome()¶: Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)

FTP.login(user='anonymous', passwd='', acct='')¶: Выполняет вход в систему под указанным именем user. Параметры passwd и acct являются необязательными и по умолчанию равны пустой строке. Если user не указан, по умолчанию используется 'anonymous'. Если user равен 'anonymous', то passwd по умолчанию принимает значение 'anonymous@'. Эта функция должна вызываться только один раз для каждого экземпляра после установления соединения; её не следует вызывать, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после того, как клиент выполнил вход. Параметр acct предоставляет «учётную информацию»; мало систем реализуют это.

FTP.abort()¶: Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.

FTP.sendcmd(cmd)¶: Отправляет простую строку команды на сервер и возвращает строку ответа.

FTP.voidcmd(cmd)¶: Отправляет простую командную строку на сервер и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае вызывает исключение error_reply.

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)¶: Извлекает файл в бинарном режиме передачи. Параметр cmd должен быть соответствующей командой RETR: 'RETR filename'. Функция колбэк вызывается для каждого полученного блока данных с одним строковым аргументом, содержащим блок данных. Необязательный аргумент blocksize задаёт максимальный размер порции для чтения из низкоуровневого сокетного объекта, создаваемого для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в колбэк). Выбирается разумное значение по умолчанию. rest означает то же самое, что и в методе transfercmd().

FTP.retrlines(cmd, callback=None)¶: Получает список файлов или каталогов в режиме передачи ASCII. cmd должна быть соответствующей командой RETR (см. retrbinary()) или такой командой, как LIST, NLST или MLSD (обычно это просто строка 'LIST'). LIST получает список файлов и информацию о них. NLST получает список имён файлов. На некоторых серверах MLSD получает машиночитаемый список файлов и информацию о них. Функция колбэк вызывается для каждой строки с аргументом-строкой, содержащим строку с удалённым завершающим CRLF. По умолчанию колбэк выводит строку в sys.stdout.

FTP.set_pasv(boolean)¶: Включает пассивный режим, если boolean истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию.

FTP.storbinary(cmd, file, blocksize=8192, callback=None)¶: Сохраняет файл в бинарном режиме передачи. cmd должна быть соответствующей командой STOR: "STOR filename". file – это открытый файловый объект, который читается до EOF с помощью его метода read() блоками размера blocksize для предоставления сохраняемых данных. По умолчанию аргумент blocksize равен 8192. колбэк – необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки.

FTP.storlines(cmd, file, callback=None)¶: Сохраняет файл в ASCII режиме передачи. cmd должна быть соответствующей командой STOR (см. storbinary()). Строки читаются до EOF из открытого файлового объекта file с помощью его метода readline() для предоставления сохраняемых данных. колбэк – необязательный вызываемый объект с одним параметром, который вызывается для каждой строки после её отправки.

FTP.transfercmd(cmd, rest=None)¶

Инициирует передачу по соединению данных. Если передача активная, отправляется команда EPRT или PORT и команда передачи, указанная параметром cmd, и принимается соединение. Если сервер пассивный, отправляется команда EPSV или PASV, выполняется подключение к нему и запускается команда передачи. В любом случае возвращается сокет для соединения.

Если задан необязательный параметр rest, серверу отправляется команда REST с передачей rest в качестве аргумента. Обычно rest – это байтовое смещение в запрашиваемом файле; серверу указывается возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы rest был строкой, содержащей символы из печатного диапазона кодов ASCII от 33 до 126. Поэтому метод transfercmd() преобразует rest в строку, но проверка содержимого строки не выполняется. Если сервер не распознаёт команду REST, будет вызвано исключение error_reply. Если это происходит, просто вызовите transfercmd() без аргумента rest.

FTP.ntransfercmd(cmd, rest=None)¶: Подобно transfercmd(), но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается None. Параметры cmd и rest означают то же самое, что и в transfercmd().

FTP.nlst(argument[, ...])¶: Возвращает список имён файлов, полученный от команды NLST. Необязательный аргумент argument – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде NLST.

FTP.dir(argument[, ...])¶: Формирует список каталога, возвращаемый командой LIST, выводя его в стандартный вывод. Необязательный аргумент argument – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде LIST. Если последний аргумент является функцией, он используется как функция колбэк аналогично retrlines(); по умолчанию вывод осуществляется в sys.stdout. Этот метод возвращает None.

FTP.rename(fromname, toname)¶: Переименовывает файл fromname на сервере в toname.

FTP.delete(filename)¶: Удаляет файл с именем filename с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает error_perm при ошибках разрешения или error_reply при других ошибках.

FTP.cwd(pathname)¶: Устанавливает текущий каталог на сервере.

FTP.mkd(pathname)¶: Создаёт новый каталог на сервере.

FTP.pwd()¶: Возвращает путь к текущему каталогу на сервере.

FTP.rmd(dirname)¶: Удаляет каталог с именем dirname на сервере.

FTP.size(filename)¶: Запрос размера файла с именем filename на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается None. Обратите внимание, что команда SIZE не стандартизирована, но поддерживается многими распространёнными реализациями серверов.

FTP.quit()¶: Отправляет команду QUIT серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но может вызвать исключение, если сервер отвечает ошибкой на команду QUIT. Это подразумевает вызов метода close(), который делает экземпляр FTP бесполезным для последующих вызовов (см. ниже).

FTP.close()¶: Закрывает соединение в одностороннем порядке. Не следует применять к уже закрытому соединению, например после успешного вызова quit(). После этого вызова экземпляр FTP больше не следует использовать (после вызова close() или quit() вы не сможете снова открыть соединение, вызвав другой метод login()).

20.11. ftplib – клиент протокола FTP¶ftplib – FTP protocol client

20.11.1. Объекты FTP¶FTP Objects

20.11. `ftplib` – клиент протокола FTP¶ftplib – FTP protocol client