Документация Python неофициальный перевод
Содержание страницы

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

Исходный код: Lib/ftplib.py

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

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

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # подключение к хосту, порт по умолчанию
>>> ftp.login()                     # пользователь anonymous, пароль anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # перейти в каталог "debian"
>>> ftp.retrlines('LIST')           # список содержимого каталога
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> 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 задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если он не указан, используется глобальная настройка тайм-аута по умолчанию).

Изменено в версии 2.6: добавлен параметр timeout.

class ftplib.FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])

Подкласс FTP, добавляющий поддержку TLS для FTP, как описано в RFC 4217. Подключение выполняется как обычно к порту 21, неявно защищая управляющее соединение FTP перед аутентификацией. Для защиты соединения данных требуется явный вызов метода prot_p(). context – это объект ssl.SSLContext, который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну (потенциально долгоживущую) структуру. Ознакомьтесь с рекомендациями по безопасности для получения лучших практик.

keyfile и certfile – это устаревшая альтернатива context – они могут указывать на PEM-форматированные файлы закрытого ключа и цепочки сертификатов (соответственно) для SSL-соединения.

Новое в версии 2.7.

Изменено в версии 2.7.10: добавлен параметр context.

Вот пример сеанса с использованием класса FTP_TLS:

>>> from ftplib import FTP_TLS
>>> ftps = FTP_TLS('ftp.python.org')
>>> ftps.login()           # анонимный вход до защиты управляющего канала
>>> ftps.prot_p()          # переключиться на защищённое соединение данных
>>> ftps.retrlines('LIST') # безопасно вывести содержимое каталога
total 9
drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 .
drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 ..
drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 bin
drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 etc
d-wxrwxr-x   2 ftp      wheel        1024 Sep  5 13:43 incoming
drwxr-xr-x   2 root     wheel        1024 Nov 17  1993 lib
drwxr-xr-x   6 1094     wheel        1024 Sep 13 19:07 pub
drwxr-xr-x   3 root     wheel        1024 Jan  3  1994 usr
-rw-r--r--   1 root     root          312 Aug  1  1994 welcome.msg
'226 Transfer complete.'
>>> ftps.quit()
>>>
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.8.1. Объекты FTPFTP Objects

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

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

FTP.set_debuglevel(level)

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

FTP.connect(host[, port[, timeout]])

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

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

Изменено в версии 2.6: добавлен параметр timeout.

FTP.getwelcome()

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

FTP.login([user[, passwd[, acct]]])

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

FTP.abort()

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

FTP.sendcmd(command)

Отправляет простую строку команды на сервер и возвращает строку ответа.

FTP.voidcmd(command)

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

FTP.retrbinary(command, callback[, maxblocksize[, rest]])

Получает файл в двоичном режиме передачи. command должна быть соответствующей командой RETR: 'RETR filename'. Функция колбэк вызывается для каждого полученного блока данных с одним строковым аргументом, содержащим блок данных. Необязательный аргумент maxblocksize задаёт максимальный размер фрагмента для чтения из низкоуровневого сокетного объекта, созданного для фактической передачи (это также будет максимальный размер блоков данных, передаваемых в колбэк). Выбирается разумное значение по умолчанию. rest означает то же самое, что и в методе transfercmd().

FTP.retrlines(command[, callback])

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

FTP.set_pasv(val)

Включает «пассивный» режим, если val истинно, в противном случае отключает пассивный режим. (В Python 2.0 и более ранних версиях пассивный режим был выключен по умолчанию; в Python 2.1 и более поздних версиях он включён по умолчанию.)

FTP.storbinary(command, fp[, blocksize, callback, rest])

Сохраняет файл в двоичном режиме передачи. command должна быть соответствующей командой STOR: "STOR filename". fp – это открытый файловый объект, который читается до EOF с помощью его метода read() блоками размера blocksize для предоставления сохраняемых данных. Значение аргумента blocksize по умолчанию равно 8192. колбэк – необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки. rest означает то же самое, что и в методе transfercmd().

Изменено в версии 2.1: добавлено значение по умолчанию для blocksize.

Изменено в версии 2.6: добавлен параметр колбэк.

Изменено в версии 2.7: добавлен параметр rest.

FTP.storlines(command, fp[, callback])

Сохраняет файл в ASCII-режиме передачи. command должна быть подходящей командой STOR (см. storbinary()). Строки читаются до EOF из открытого файлового объекта fp с помощью его метода readline() для предоставления сохраняемых данных. колбэк – необязательный вызываемый объект с одним параметром, который вызывается для каждой строки после её отправки.

Изменено в версии 2.6: добавлен параметр колбэк.

FTP.transfercmd(cmd[, rest])

Инициирует передачу по соединению данных. Если передача активная, отправляет команду 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])

Как и 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.8.2. Объекты FTP_TLSFTP_TLS Objects

FTP_TLS класс наследует от FTP, определяя эти дополнительные объекты:

FTP_TLS.ssl_version

Версия SSL для использования (по умолчанию ssl.PROTOCOL_SSLv23).

FTP_TLS.auth()

Устанавливает безопасное управляющее соединение с помощью TLS или SSL в зависимости от того, что указано в атрибуте ssl_version().

FTP_TLS.prot_p()

Устанавливает защищённое соединение данных.

FTP_TLS.prot_c()

Устанавливает незащищённое соединение данных.