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

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

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

Этот модуль определяет класс 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 задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).

FTP класс поддерживает оператор with. Вот пример его использования:

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
...
'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
>>>

Изменено в версии 3.2: Добавлена поддержка оператора with.

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

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

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

Вот пример сеанса работы с классом 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.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, rest=None)¶

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

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

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.2. Объекты FTP_TLS¶FTP_TLS Objects

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

FTP_TLS.ssl_version¶: Используемая версия SSL (по умолчанию TLSv1).

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

FTP_TLS.prot_p()¶: Устанавливает защищённое соединение данных.

FTP_TLS.prot_c()¶: Устанавливает незащищённое соединение данных.

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

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

20.11.2. Объекты FTP_TLS¶FTP_TLS Objects

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