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

Данный модуль определяет класс FTP и несколько связанных элементов. Класс FTP реализует клиентскую часть протокола FTP. Вы можете использовать его для написания Python программ, которые выполняют различные автоматизированные FTP задания, такие как зеркалирование других FTP-серверов. Он также используется модулем urllib.request для обработки URL-адресов, использующих FTP. Дополнительные сведения о FTP (протоколе передачи файлов) см. в Интернете RFC 959.

Пример сеанса с использованием модуля ftplib:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # подключиться к хосту, порт по умолчанию
>>> ftp.login()                     # пользователь anonymous, пароль anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # перейти в каталог "debian"
>>> ftp.retrlines('LIST')           # список содержимого каталога
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()

Модуль определяет следующие элементы:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None)¶

Возвращает новый экземпляр класса FTP. Когда задан host, выполняется вызов метода connect(host). Когда задан user, дополнительно выполняется вызов метода login(user, passwd, acct) (где passwd и acct по умолчанию являются пустой строкой, если они не заданы). Необязательный параметр timeout указывает тайм-аут в секундах для блокировки операций, таких как попытка подключения (если он не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). source_address — это 2-кортеж (host, port), к которому сокет привязывается в качестве исходного адреса перед подключением.

Класс FTP поддерживает оператор with, например.:

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
... # doctest: +SKIP
'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.

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

Подкласс FTP, добавляющий поддержку TLS для FTP, как приведено в RFC 4217. Подключение происходит по порту 21, неявно защищая управляющее FTP соединение перед аутентификацией. Для защиты подключения к данным пользователь должен явно запросить его, вызвав метод prot_p(). context — это объект ssl.SSLContext, который позволяет объединять параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Ознакомьтесь с рекомендациями Соображения безопасности.

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() выбрать для вас доверенные сертификаты CA системы.

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

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.

См.также

Модуль netrc: Парсер для формата файла .netrc. Файл .netrc есть обычно используется FTP-клиентами для загрузки информации аутентификации пользователя перед запросом пользователя.

FTP-объекты¶

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

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

FTP.set_debuglevel(level)¶: Устанавливает уровень отладки экземпляра. Это контролирует количество напечатанного отладочного вывода. Значение по умолчанию 0 не выводит отладочный вывод. Значение 1 даёт умеренный объем отладочной информации, как правило, одну строку на запрос. Значение 2 или выше создаёт максимальный объем отладочной информации, регистрируя каждую строку, отправленную и полученную по управляющему соединению.

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

Подключиться к заданному хосту и порту. Номер порта по умолчанию — 21, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; его вообще не следует вызывать, если хост был задан при создании экземпляра. Все остальные методы можно использовать только после установления соединения. Необязательный параметр timeout указывает время ожидания в секундах для попытки подключения. Если timeout не передан, будет использоваться глобальная настройка времени ожидания по умолчанию. source_address — это 2-кортеж (host, port), к которому сокет привязывается в качестве исходного адреса перед подключением.

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

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

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

FTP.login(user='anonymous', passwd='', acct='')¶: Войти в систему как данный user. Параметры passwd и acct являются необязательными и по умолчанию содержат пустую строку. Если user не указан, по умолчанию используется 'anonymous'. Если user — 'anonymous', passwd по умолчанию — 'anonymous@'. Эту функцию следует вызывать только один раз для каждого экземпляра после установления соединения; его вообще не следует вызывать, если хост и пользователь были заданы при создании экземпляра. Большинство команд FTP разрешены только после входа клиента в систему. Параметр acct предоставляет «учетную информацию»; несколько систем реализуют это.

FTP.abort()¶: Прервать текущую передачу файла. Использование этого не всегда работает, но попробовать стоит.

FTP.sendcmd(cmd)¶

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

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

FTP.voidcmd(cmd)¶

Отправить простую командную строку на сервер и обработать ответ. Ничего не возвращать, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае вызывается error_reply.

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

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)¶: Получить файл в двоичном режиме передачи. cmd должен быть соответствующей командой RETR: 'RETR filename'. Функция callback вызывается для каждого полученного блока данных с одним байтовым аргументом, задающим блок данных. Необязательный аргумент blocksize указывает максимальный размер фрагмента для чтения в объекте низкоуровневого сокета, созданном для фактической передачи (который также будет наибольшим размером блоков данных, переданных в callback). Выбирается разумное значение по умолчанию. rest означает то же самое, что и в методе transfercmd().

FTP.retrlines(cmd, callback=None)¶: Получить список файлов или каталогов в режиме передачи ASCII. cmd должна быть соответствующей командой RETR (см. retrbinary()) или такой командой, как LIST или NLST (обычно это просто строка 'LIST'). LIST извлекает список файлов и информацию об данных файлах. NLST извлекает список имён файлов. Функция callback вызывается для каждой строки со строковым аргументом, содержащим строку с удаленным конечным CRLF. По умолчанию callback печатает строку в sys.stdout.

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

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)¶: Сохранить файл в двоичном режиме передачи. cmd должна быть соответствующей командой STOR: "STOR filename". fp — это файловый объект (открытый в двоичном режиме), который считывается до завершения EOF с использованием метода read() в блоках размером blocksize для предоставления данных для сохранения. Аргумент blocksize по умолчанию равен 8192. callback — это необязательный единственный вызываемый параметр, который вызывается для каждого блока данных после его отправки. rest означает то же самое, что и в методе transfercmd().

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

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

FTP.transfercmd(cmd, rest=None)¶

Инициализация передачи через соединение для передачи данных. Если передача активна, отправить команду EPRT или PORT и команду передачи, указанную в cmd, и принять соединение. Если сервер пассивен, отправить команду EPSV или PASV, подключившись к нему и запустить команду передачи. В любом случае возвращает сокет для соединения.

Если указан необязательный rest, на сервер отправляется команда REST с передачей rest в качестве аргумента. rest обычно представляет собой смещение в байтах в запрошенном файле, указывающее серверу перезапустить отправку байтов файла с запрошенным смещением, пропуская начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы rest была строкой, содержащей символы в печатном диапазоне от кода ASCII 33 до кода ASCII 126. Таким образом, метод transfercmd() преобразует rest в строку, но проверка содержимого строки не выполняется. Если сервер не распознает команду REST, будет возбуждено исключение error_reply. Если это произойдет, просто вызовите transfercmd() без аргумента rest.

FTP.ntransfercmd(cmd, rest=None)¶: Аналогичен transfercmd(), но возвращает кортеж подключения к данным и ожидаемый размер данных. Если ожидаемый размер не может быть вычислен, None будет возвращён как ожидаемый размер. cmd и rest означают то же самое, что и transfercmd().

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

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

FTP.nlst(argument[, ...])¶: Возвращает список имён файлов, возвращаемый командой NLST. Необязательный argument — это каталог для списка (по умолчанию это текущий каталог сервера). Для передачи нестандартных параметров команде NLST можно использовать несколько аргументов.

Примечание

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

FTP.dir(argument[, ...])¶: Создаёт список каталогов, возвращённый командой LIST, и распечатывает его в стандартный вывод. Необязательный argument — это каталог для списка (по умолчанию это текущий каталог сервера). Для передачи нестандартных параметров команде LIST можно использовать несколько аргументов. Если последний аргумент является функцией, он используется как функция callback, как и для retrlines(); по умолчанию печатается sys.stdout. Данный метод возвращает None.

Примечание

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

FTP.rename(fromname, toname)¶: Переименовывает файл fromname на сервере в toname.

FTP.delete(filename)¶: Удаляет файл с именем filename с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает error_perm при ошибках прав доступа или error_reply при других ошибках.

FTP.cwd(pathname)¶: Устанавливает текущий каталог на сервере.

FTP.mkd(pathname)¶: Создаёт новый каталог на сервере.

FTP.pwd()¶: Возвращает путь к текущему каталогу на сервере.

FTP.rmd(dirname)¶: Удаляет каталог с именем dirname на сервере.

FTP.size(filename)¶: Запрашивает размер файла с именем filename на сервере. В случае успеха размер файла возвращается как целое число, в противном случае возвращается None. Обратите внимание, что команда SIZE не стандартизирована, но поддерживается многими распространенными реализациями серверов.

FTP.quit()¶: Отправляет на сервер команду QUIT и закрыть соединение. Это «вежливый» способ закрыть соединение, но он может вызвать исключение, если сервер ответит ошибкой на команду QUIT. Это подразумевает вызов метода close(), который делает экземпляр FTP бесполезным для последующих вызовов (см. ниже).

FTP.close()¶: Закрывает соединение в одностороннем порядке. Не следует применять к уже закрытому соединению, например, после успешного вызова quit(). После этого вызова экземпляр FTP больше не должен использоваться (после вызова close() или quit() вы не можете повторно открыть соединение, выполнив другой метод login()).

Объекты FTP_TLS¶

Класс FTP_TLS наследуется от FTP, определяя данные дополнительные объекты:

FTP_TLS.ssl_version¶: Используемая версия SSL (по умолчанию ssl.PROTOCOL_SSLv23).

FTP_TLS.auth()¶: Настраивает безопасное управляющее соединение с помощью TLS или SSL, в зависимости от того, что указано в атрибуте ssl_version.

Изменено в версии 3.4: Теперь данный метод поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Индикация имени сервера (см. ssl.HAS_SNI).

FTP_TLS.ccc()¶: Возвращает канал управления обратно в открытый текст. Может быть полезно, чтобы воспользоваться преимуществами брандмауэров, которые знают, как обрабатывать NAT с незащищенным FTP, не открывая фиксированные порты.

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

FTP_TLS.prot_p()¶: Настраивает безопасное соединение для передачи данных.

FTP_TLS.prot_c()¶: Настраивает соединение для передачи данных в виде открытого текста.

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

FTP-объекты¶

Объекты FTP_TLS¶

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