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 и индикацию имени сервера (см. 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 и индикацию имени сервера (см. 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.