ftplib – клиент протокола FTP¶ftplib – FTP protocol client

Объекты FTP¶FTP objects

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) – Информация об учётной записи для команды ACCT FTP. Немногие системы реализуют это. Подробнее см. 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)¶

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

Параметры:

• user (str) – имя пользователя для входа (по умолчанию: 'anonymous').

• passwd (str) – Пароль для входа. Если не указан, и если passwd – пустая строка или "-", пароль будет сгенерирован автоматически.

• acct (str) – Информация об учётной записи для команды 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 (str) – подходящая команда RETR: "RETR filename".

• callback (callable) – A single parameter callable that is called for each block of data received, with its single argument being the data as bytes.

• blocksize (int) – The maximum chunk size to read on the low-level socket object created to do the actual transfer. This also corresponds to the largest size of data that will be passed to callback. Defaults to 8192.

• rest (int) – команда REST, отправляемая серверу. См. документацию к параметру rest метода transfercmd().

retrlines(cmd, callback=None)¶

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

set_pasv(val)¶

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

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

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

Параметры:

• cmd (str) – подходящая команда STOR: "STOR filename".

• fp (file object) – файловый объект (открытый в двоичном режиме), который читается до EOF, используя его метод read() блоками размера blocksize для предоставления сохраняемых данных.

• blocksize (int) – размер блока чтения. По умолчанию 8192.

• callback (callable) – A single parameter callable that is called for each block of data sent, with its single argument being the data as bytes.

• rest (int) – команда REST, отправляемая серверу. См. документацию к параметру rest метода transfercmd().

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

storlines(cmd, fp, callback=None)¶

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

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=[])¶

List a directory in a standardized format by using MLSD command (RFC 3659). If path is omitted the current directory is assumed. facts is a list of strings representing the type of information desired (e.g. ["type", "size", "perm"]). Return a generator object yielding a tuple of two elements for every file found in path. First element is the file name, the second one is a dictionary containing facts about the file name. Content of this dictionary might be limited by the facts argument but server is not guaranteed to return all requested facts.

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

nlst(argument[, ...])¶

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

Примечание

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

dir(argument[, ...])¶

Выводит список каталога, возвращаемый командой LIST, печатая его в стандартный вывод. Необязательный аргумент argument – это каталог для вывода списка (по умолчанию текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде LIST. Если последний аргумент является функцией, он используется как функция обратного вызова колбэк, как в 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¶FTP_TLS objects

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) – Информация об учётной записи для команды ACCT FTP. Немногие системы реализуют это. Подробнее см. 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 и 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()¶

Устанавливает незащищённое соединение данных.

Переменные модуля¶Module variables

exception ftplib.error_reply¶

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

exception ftplib.error_temp¶

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

exception ftplib.error_perm¶

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

exception ftplib.error_proto¶

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

ftplib.all_errors¶

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