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

21.13. `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.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=None, source_address=None)¶

Возвращает новый экземпляр класса FTP. Если указан host, вызывается метод connect(host). Если указан user, дополнительно вызывается метод login(user, passwd, acct) (где passwd и acct по умолчанию равны пустой строке, если не заданы). Необязательный параметр timeout задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию). source_address – это кортеж из двух элементов (host, port), к которому привязывается сокет в качестве исходного адреса перед подключением.

Класс 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.

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

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

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

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

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

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

Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

Вот пример сеанса работы с классом FTP_TLS:

>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

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

См. также

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

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

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

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

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

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

FTP.connect(host='', port=0, timeout=None, source_address=None)¶: Подключается к указанному хосту и порту. Номер порта по умолчанию – 21, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эта функция должна вызываться только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установления соединения. Необязательный параметр timeout задаёт тайм-аут в секундах для попытки подключения. Если timeout не передан, будет использована глобальная настройка тайм-аута по умолчанию. source_address – это кортеж из двух элементов (host, port), к которому привязывается сокет в качестве исходного адреса перед подключением.

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

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 (обычно просто строка 'LIST'). LIST возвращает список файлов и информацию об этих файлах. NLST возвращает список имён файлов. Функция колбэк вызывается для каждой строки с аргументом-строкой, содержащей строку с удалённым завершающим CRLF. Функция колбэк по умолчанию выводит строку в sys.stdout.

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

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

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

FTP.storlines(cmd, fp, callback=None)¶: Сохраняет файл в ASCII-режиме передачи. Параметр cmd должен быть соответствующей командой STOR (см. storbinary()). Строки читаются до EOF из файлового объекта fp (открытого в бинарном режиме) с помощью его метода 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.mlsd(path="", facts=[])¶: Выводит список каталога в стандартизированном формате с помощью команды MLSD (RFC 3659). Если path опущен, подразумевается текущий каталог. facts – это список строк, представляющих тип запрашиваемой информации (например, ["type", "size", "perm"]). Возвращает объект-генератор, выдающий кортеж из двух элементов для каждого файла, найденного в path. Первый элемент – имя файла, второй – словарь, содержащий сведения об имени файла. Содержимое этого словаря может быть ограничено аргументом facts, но сервер не гарантирует возврат всех запрошенных сведений.

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

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

Устарело с версии 3.3: используйте mlsd() вместо этого.

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

Устарело с версии 3.3: используйте mlsd() вместо этого.

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()).

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

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

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

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

Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

FTP_TLS.ccc()¶: Возвращает управляющий канал обратно в открытый текст. Это может быть полезно для использования межсетевых экранов, которые умеют обрабатывать NAT с небезопасным FTP без открытия фиксированных портов.

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

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

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

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

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

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

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