Содержание страницы

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

Исходный код: Lib/ftplib.py

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

По умолчанию используется кодировка UTF-8 в соответствии с RFC 2640.

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

>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # подключение к хосту, порт по умолчанию
>>> ftp.login()                     # пользователь anonymous, пароль anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # перейти в каталог "debian"
'250 Directory successfully changed.'
>>> 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()
'221 Goodbye.'

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

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

Возвращает новый экземпляр класса FTP. Когда указан host, выполняется вызов метода connect(host). Когда указан user, дополнительно выполняется вызов метода login(user, passwd, acct) (при этом passwd и acct по умолчанию равны пустой строке, если не заданы). Необязательный параметр timeout задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). source_address – это кортеж из двух элементов (host, port), к которому привязывается сокет в качестве исходного адреса перед подключением. Параметр 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.

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(). context – это объект ssl.SSLContext, который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну (потенциально долгоживущую) структуру. Ознакомьтесь с рекомендациями по безопасности для получения лучших практик.

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

Новое в версии 3.2.

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

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

Устарело с версии 3.6: keyfile и certfile устарели в пользу context. Вместо них используйте ssl.SSLContext.load_cert_chain(), или позвольте ssl.create_default_context() выбрать доверенные сертификаты ЦС системы.

Вот пример сеанса с использованием класса 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¶: Исключение, возникающее при получении ответа от сервера, который не соответствует спецификациям ответов протокола передачи файлов (File Transfer Protocol), то есть начинается с цифры в диапазоне 1–5.

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

См. также

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

Объекты FTP¶FTP Objects

Несколько методов доступны в двух вариантах: один для работы с текстовыми файлами, другой – для двоичных. Они названы по команде, за которой следует 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 – это кортеж из двух элементов (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'. Функция колбэк вызывается для каждого полученного блока данных с единственным аргументом bytes, содержащим блок данных. Необязательный аргумент blocksize задаёт максимальный размер фрагмента для чтения из низкоуровневого объекта сокета, созданного для фактической передачи (он также будет максимальным размером блоков данных, передаваемых в колбэк). Выбирается разумное значение по умолчанию. rest означает то же, что и в методе transfercmd().

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

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

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

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

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

FTP.transfercmd(cmd, rest=None)¶

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

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

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

FTP.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.

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

Примечание

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

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

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

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

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

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

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

Новое в версии 3.3.

FTP_TLS.prot_p()¶: Устанавливает защищённое соединение данных.

FTP_TLS.prot_c()¶: Устанавливает незащищённое соединение данных.

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

Объекты FTP¶FTP Objects

Объекты FTP_TLS¶FTP_TLS Objects

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