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) – Информация об учетной записи, используемая для команды 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) – Функция с одним параметром, которая вызывается для каждого блока полученных данных, где единственный аргумент — данные как 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()). Строки читаются до 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"]). Возвращает генератор, возвращающий кортеж из двух элементов для каждого найденного файла в path. Первый элемент – имя файла, второй – словарь, содержащий информацию о файле. Содержимое этого словаря может быть ограничено аргументом 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 и 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.