ftplib — Протокол FTP¶

Объекты FTP¶

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

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

Parameters:

• host (str) – Имя хоста, к которому нужно подключиться. Если задано, connect(host) неявно вызывается конструктором.

• user (str) – The username to log in with (default: 'anonymous'). Если задан, то login(host, passwd, acct) неявно вызывается конструктором.

• passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

• acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

• timeout (float | None) – Время ожидания в секундах для блокировки операций, таких как connect() (по умолчанию: глобальная настройка времени ожидания по умолчанию).

• source_address (tuple | None) – |параметр_doc_source_address|

• encoding (str) – |параметр_doc_encoding|

Класс 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 могут быть вызваны только после успешного установления соединения.

Parameters:

• host (str) – Хост, к которому нужно подключиться.

• port (int) – TCP-порт для подключения (по умолчанию: 21, как указано в спецификации протокола FTP). Редко возникает необходимость указывать другой номер порта.

• timeout (float | None) – Время ожидания в секундах для попытки подключения (по умолчанию: глобальная настройка времени ожидания по умолчанию).

• source_address (tuple | None) – |параметр_doc_source_address|

Создает auditing event ftplib.connect с аргументами self, host, port.

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

getwelcome()¶

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

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

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

Parameters:

• user (str) – |параметр_doc_user|

• passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

• acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

abort()¶

Прервите текущую передачу файла. Это не всегда работает, но попробовать стоит.

sendcmd(cmd)¶

Отправьте простую командную строку на сервер и верните строку ответа.

Создает auditing event ftplib.sendcmd с аргументами self, cmd.

voidcmd(cmd)¶

Отправьте простую командную строку на сервер и обработайте ответ. Верните строку ответа, если код ответа соответствует успешному завершению (коды в диапазоне 200-299). В противном случае увеличьте значение error_reply.

Создает auditing event ftplib.sendcmd с аргументами self, cmd.

retrbinary(cmd, callback, blocksize=8192, rest=None)¶

Извлеките файл в режиме двоичной передачи.

Parameters:

• cmd (str) – Соответствующая команда STOR: "STOR filename".

• callback (callable) – Единственный доступный для вызова параметр, который вызывается для каждого полученного блока данных, причем его единственным аргументом являются данные в виде 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)¶

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

Parameters:

• cmd (str) – Соответствующая команда STOR: "STOR filename".

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

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

• callback (callable) – Единственный доступный для вызова параметр, который вызывается для каждого отправляемого блока данных, причем его единственным аргументом являются данные в виде bytes.

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

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

storlines(cmd, fp, callback=None)¶

Сохраните файл в линейном режиме. cmd должна быть соответствующей командой STOR (см. storbinary()). Строки считываются до EOF из file object 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=[])¶

Выведите список каталогов в стандартном формате с помощью команды MLSD (RFC 3659). Если path опущен, предполагается, что это текущий каталог. facts - это список строк, представляющих желаемый тип информации (например, ["type", "size", "perm"]). Возвращает объект generator, который выдает кортеж из двух элементов для каждого файла, найденного в path. Первый элемент - это имя файла, второй - словарь, содержащий информацию об имени файла. Содержимое этого словаря может быть ограничено аргументом facts, но сервер не гарантирует, что вернет все запрошенные факты.

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

nlst(argument[, ...])¶

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

Примечание

Если ваш сервер поддерживает эту команду, mlsd() предлагает лучший API.

dir(argument[, ...])¶

Создайте список каталогов, возвращаемый командой LIST, и выведите его на стандартный вывод. Необязательный аргумент - это каталог, который нужно указать (по умолчанию это текущий каталог сервера). Для передачи нестандартных параметров команде 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¶

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')¶

Подкласс FTP, который добавляет поддержку TLS к FTP, как описано в RFC 4217. Подключитесь к порту 21, неявно защищая управляющее соединение FTP перед аутентификацией.

Примечание

Пользователь должен явно защитить подключение для передачи данных, вызвав метод prot_p().

Parameters:

• host (str) – Имя хоста, к которому нужно подключиться. Если задано, connect(host) неявно вызывается конструктором.

• user (str) – The username to log in with (default: 'anonymous'). Если задан, то login(host, passwd, acct) неявно вызывается конструктором.

• passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

• acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

• context (ssl.SSLContext) – Объект SSLContext, который позволяет объединять параметры конфигурации SSL, сертификаты и закрытые ключи в единую, потенциально долговечную структуру. Пожалуйста, ознакомьтесь с рекомендациями в Соображения безопасности.

• timeout (float | None) – Время ожидания в секундах для блокировки операций, таких как connect() (по умолчанию: глобальная настройка времени ожидания по умолчанию).

• source_address (tuple | None) – |параметр_doc_source_address|

• encoding (str) – |параметр_doc_encoding|

keyfile и certfile являются устаревшей альтернативой context - они могут указывать на файлы закрытого ключа в формате PEM и файлы цепочки сертификатов (соответственно) для SSL-соединения.

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

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

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

Не рекомендуется, начиная с версии 3.6: keyfile и certfile устарели в пользу context. Пожалуйста, используйте вместо этого ssl.SSLContext.load_cert_chain() или позвольте ssl.create_default_context() выбрать для вас сертификаты доверенного центра сертификации системы.

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

Вот пример сеанса с использованием класса 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.