ftplib — клиент протокола FTP

Объекты FTP

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

Возвращает новый экземпляр класса FTP.

Параметры:

• host (str) – Имя хоста для подключения. Если оно указано, конструктор неявно вызывает connect(host).
• user (str) – Имя пользователя для входа (по умолчанию: 'anonymous'). Если оно указано, конструктор неявно вызывает login(host, passwd, acct).
• passwd (str) – Пароль для входа. Если он не указан, а passwd — пустая строка или "-", пароль будет сгенерирован автоматически.
• acct (str) – Данные учетной записи для команды FTP ACCT. Эту возможность поддерживают немногие системы. Подробности см. в RFC-959.
• timeout (float | None) – Тайм-аут в секундах для блокирующих операций, таких как connect() (по умолчанию: глобальное значение тайм-аута).
• source_address (tuple | None) – Кортеж из двух элементов (host, port), задающий адрес источника, к которому привязывается сокет перед подключением.
• encoding (str) – Кодировка каталогов и имен файлов (по умолчанию: 'utf-8').

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

Изменено в версии 3.9: Если для параметра timeout задано нулевое значение, будет вызвано исключение ValueError, чтобы предотвратить создание неблокирующего сокета. Добавлен параметр encoding; значение по умолчанию изменено с Latin-1 на UTF-8 в соответствии с RFC 2640.

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

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

set_debuglevel(level)

Задает уровень отладки экземпляра в виде int. Он определяет объем выводимой отладочной информации. Доступны следующие уровни отладки:

• 0 (по умолчанию): отладочная информация не выводится.
• 1: выводится умеренный объем отладочной информации, обычно одна строка на запрос.
• 2 или выше: выводится максимальный объем отладочной информации — регистрируется каждая отправленная и полученная строка управляющего соединения.

connect(host='', port=0, timeout=None, source_address=None)

Подключается к указанному хосту и порту. Эту функцию следует вызывать только один раз для каждого экземпляра; ее не следует вызывать, если при создании экземпляра FTP был задан аргумент host. Все остальные методы FTP можно вызывать только после успешного подключения.

Параметры:

• host (str) – Хост для подключения.
• port (int) – TCP-порт для подключения (по умолчанию: 21, как указано в спецификации протокола FTP). Указывать другой номер порта требуется редко.
• timeout (float | None) – Тайм-аут в секундах для попытки подключения (по умолчанию: глобальное значение тайм-аута).
• source_address (tuple | None) – Кортеж из двух элементов (host, port), задающий адрес источника, к которому привязывается сокет перед подключением.

Вызывает событие аудита ftplib.connect с аргументами self, host, port.

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

getwelcome()

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

login(user='anonymous', passwd='', acct='')

Выполняет вход на подключенный FTP-сервер. Эту функцию следует вызывать только один раз для каждого экземпляра, после установки соединения; ее не следует вызывать, если при создании экземпляра FTP были заданы аргументы host и user. Большинство команд FTP разрешено выполнять только после входа клиента в систему.

Параметры:

• user (str) – Имя пользователя для входа (по умолчанию: 'anonymous').
• passwd (str) – Пароль для входа. Если он не указан, а passwd — пустая строка или "-", пароль будет сгенерирован автоматически.
• acct (str) – Данные учетной записи для команды FTP ACCT. Эту возможность поддерживают немногие системы. Подробности см. в RFC-959.

abort()

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

sendcmd(cmd)

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

Вызывает событие аудита ftplib.sendcmd с аргументами self, cmd.

voidcmd(cmd)

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

Вызывает событие аудита ftplib.sendcmd с аргументами self, cmd.

retrbinary(cmd, callback, blocksize=8192, rest=None)

Получает файл в режиме двоичной передачи.

Параметры:

• cmd (str) – Подходящая команда STOR: "STOR filename".
• callback (вызываемый объект) – Вызываемый объект с одним параметром, который вызывается для каждого полученного блока данных. Его единственный аргумент — данные типа bytes.
• blocksize (int) – Максимальный размер блока для чтения из низкоуровневого объекта socket, созданного для выполнения самой передачи. Он также соответствует максимальному размеру данных, передаваемых в callback. По умолчанию — 8192.
• rest (int) – Команда REST, отправляемая серверу. См. документацию по параметру rest метода transfercmd().

retrlines(cmd, callback=None)

Получает файл или список каталога в кодировке, указанной при инициализации параметром encoding. cmd должна быть подходящей командой RETR (см. retrbinary()) или такой командой, как LIST либо NLST (обычно просто строка 'LIST'). Команда LIST возвращает список файлов и сведения о них. Команда NLST возвращает список имен файлов. Для каждой строки вызывается функция callback с аргументом-строкой, содержащей строку без завершающего CRLF. По умолчанию callback выводит строку в sys.stdout.

set_pasv(val)

Включает пассивный режим, если val имеет истинное значение, иначе выключает его. По умолчанию пассивный режим включен.

storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

Передает файл в режиме двоичной передачи.

Параметры:

• cmd (str) – Подходящая команда STOR: "STOR filename".
• fp (файловый объект) – Файловый объект (открытый в двоичном режиме), который считывается до EOF с помощью метода read() блоками размером blocksize; прочитанные данные передаются для сохранения.
• blocksize (int) – Размер блока чтения. По умолчанию — 8192.
• callback (вызываемый объект) – Вызываемый объект с одним параметром, который вызывается для каждого отправленного блока данных. Его единственный аргумент — данные типа bytes.
• rest (int) – Команда REST, отправляемая серверу. См. документацию по параметру rest метода transfercmd().

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

storlines(cmd, fp, callback=None)

Передает файл в построчном режиме. cmd должна быть подходящей командой STOR (см. storbinary()). Строки считываются до EOF из файлового объекта fp (открытого в двоичном режиме) с помощью метода readline(); прочитанные данные передаются для сохранения. Необязательный callback — вызываемый объект с одним параметром, который вызывается для каждой строки после ее отправки.

transfercmd(cmd, rest=None)

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

Если задан необязательный параметр rest, серверу отправляется команда REST с аргументом rest. Обычно rest — это смещение в байтах в запрошенном файле, указывающее серверу возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако метод transfercmd() преобразует rest в строку с использованием кодировки, заданной при инициализации параметром encoding, но содержимое строки не проверяется. Если сервер не распознает команду REST, будет вызвано исключение error_reply. В этом случае просто вызовите transfercmd() без аргумента rest.

ntransfercmd(cmd, rest=None)

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

mlsd(path='', facts=[])

Выводит список каталога в стандартизованном формате с помощью команды MLSD (RFC 3659). Если path не указан, используется текущий каталог. facts — это список строк, задающих тип требуемой информации (например, ["type", "size", "perm"]). Возвращает объект-генератор, который для каждого найденного в пути файла выдает кортеж из двух элементов. Первый элемент — имя файла, второй — словарь со сведениями о нем. Содержимое этого словаря может быть ограничено аргументом facts, однако сервер не гарантирует, что вернет все запрошенные сведения.

Добавлено в версии 3.3.

nlst(argument[, ...])

Возвращает список имен файлов, полученный с помощью команды NLST. Необязательный argument — каталог для просмотра (по умолчанию используется текущий каталог сервера). Можно передать несколько аргументов, чтобы указать нестандартные параметры команды NLST.

Примечание

Если сервер поддерживает эту команду, mlsd() предоставляет более удобный API.

dir(argument[, ...])

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

Примечание

Если сервер поддерживает эту команду, mlsd() предоставляет более удобный API.

rename(fromname, toname)

Переименовывает файл fromname на сервере в toname.

delete(filename)

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

cwd(pathname)

Задает текущий каталог на сервере.

mkd(pathname)

Создает новый каталог на сервере.

pwd()

Возвращает путь к текущему каталогу на сервере.

rmd(dirname)

Удаляет на сервере каталог с именем dirname.

size(filename)

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

quit()

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

close()

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

Объекты FTP_TLS

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')

Подкласс FTP, добавляющий поддержку TLS для FTP, как описано в RFC 4217. Подключается к порту 21, автоматически защищая управляющее соединение FTP до аутентификации.

Примечание

Пользователь должен явно защитить соединение для передачи данных, вызвав метод prot_p().

Параметры:

• host (str) – Имя хоста для подключения. Если оно указано, конструктор неявно вызывает connect(host).
• user (str) – Имя пользователя для входа (по умолчанию: 'anonymous'). Если оно указано, конструктор неявно вызывает login(host, passwd, acct).
• passwd (str) – Пароль для входа. Если он не указан, а passwd — пустая строка или "-", пароль будет сгенерирован автоматически.
• acct (str) – Данные учетной записи для команды FTP ACCT. Эту возможность поддерживают немногие системы. Подробности см. в RFC-959.
• context (ssl.SSLContext) – Объект контекста SSL, позволяющий объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну структуру, которая потенциально может использоваться длительное время. Рекомендации по настройке см. в разделе Рекомендации по безопасности.
• timeout (float | None) – Тайм-аут в секундах для блокирующих операций, таких как connect() (по умолчанию: глобальное значение тайм-аута).
• source_address (tuple | None) – Кортеж из двух элементов (host, port), задающий адрес источника, к которому привязывается сокет перед подключением.
• encoding (str) – Кодировка каталогов и имен файлов (по умолчанию: 'utf-8').

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

Добавлено в версии 3.2.

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

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

Устарело начиная с версии 3.6: keyfile и certfile объявлены устаревшими; вместо них следует использовать context. Используйте ssl.SSLContext.load_cert_chain() или позвольте ssl.create_default_context() самостоятельно выбрать доверенные системные сертификаты центра сертификации.

Изменено в версии 3.9: Если для параметра timeout задано нулевое значение, будет вызвано исключение ValueError, чтобы предотвратить создание неблокирующего сокета. Добавлен параметр encoding; значение по умолчанию изменено с Latin-1 на UTF-8 в соответствии с RFC 2640.

Пример сеанса с использованием класса 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']

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

ssl_version

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

auth()

Настраивает защищенное управляющее соединение с использованием TLS или SSL в зависимости от значения атрибута ssl_version.

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

ccc()

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

Добавлено в версии 3.3.

prot_p()

Настраивает защищенное соединение для передачи данных.

prot_c()

Настраивает незашифрованное соединение для передачи данных.

Переменные модуля

exception ftplib.error_reply

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

exception ftplib.error_temp

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

exception ftplib.error_perm

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

exception ftplib.error_proto

Исключение, возникающее при получении от сервера ответа, не соответствующего спецификациям протокола передачи файлов, то есть не начинающегося с цифры в диапазоне 1–5.

ftplib.all_errors

Набор всех исключений (в виде кортежа), которые могут возникнуть в методах экземпляров FTP в результате проблем с FTP-соединением (в отличие от ошибок программирования, допущенных вызывающим кодом). Этот набор включает четыре перечисленных выше исключения, а также OSError и EOFError.