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

Объекты FTP

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

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

Параметры:

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

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

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

set_debuglevel(level)

Устанавливает уровень отладки экземпляра как int. Это управляет объёмом выводимой отладочной информации. Уровни отладки:

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

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

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

Параметры:

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

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

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

getwelcome()

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

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

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

Параметры:

• user (строка) – Имя пользователя для входа (по умолчанию: 'anonymous').
• passwd (строка) – Пароль для входа. Если не задан, и если passwd пустая строка или "-", пароль будет сгенерирован автоматически.
• acct (строка) – Данные учетной записи, используемые для команды ACCT FTP. Несколько систем поддерживают эту команду. Подробнее см. 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 (строка) – Соответствующая команда RETR: "RETR filename".
• callback (вызываемый объект) – Вызываемый объект с одним параметром, который вызывается для каждого блока полученных данных, содержащих данные в виде bytes.
• blocksize (целое число) – Максимальный размер блока для чтения на низком уровне объекта socket, созданного для выполнения фактической передачи. Это также соответствует максимальному размеру данных, которые будут переданы callback. По умолчанию 8192.
• rest (целое число) – Команда 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 (объект файла) – Объект файла (открыт в двоичном режиме), который читается до конца файла, используя метод read() блоками размером blocksize для предоставления данных для сохранения.
• blocksize (int) – Размер блока чтения. По умолчанию 8192.
• callback (вызываемый объект) – Вызываемый объект с одним параметром, который вызывается для каждого блока отправленных данных, с аргументом данных в виде bytes.
• rest (int) – Команда REST для отправки на сервер. См. документацию для параметра rest метода transfercmd().

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

storlines(cmd, fp, callback=None)

Сохранить файл в текстовом режиме. cmd должен быть подходящей STOR командой (см. storbinary()). Строки считываются до конца файла из объекта файла 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) – Пара (host, port) 2-кортеж для сокета, к которому необходимо привязаться в качестве адреса источника перед подключением.
• 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.