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) – 2-элементный кортеж (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) – 2-элементный кортеж (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) – Подходящая команда RETR: "RETR 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 имеет значение true; в противном случае отключает его. По умолчанию пассивный режим включен.

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='', *, 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) – 2-элементный кортеж (host, port), задающий исходный адрес, к которому привязывается сокет перед подключением.
• encoding (str) – Кодировка каталогов и имен файлов (по умолчанию: 'utf-8').

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

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

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

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

Изменено в версии 3.12: Устаревшие параметры keyfile и certfile удалены.

Пример сеанса с использованием класса 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 и индикацию имени сервера (Server Name Indication; см. 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.