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

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

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

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

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

Изменено в версии 3.9: Если параметру timeout задано значение 0, будет вызвано исключение 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 и индикацию имени сервера (см. 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.