`ftplib.md`

563 строк · 21.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/ftplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.11. `ftplib` – клиент протокола FTP89Этот модуль определяет класс [`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP) и несколько связанных с ним элементов. Класс [`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP) реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем [`urllib.request`](https://python-all.ru/3.1/library/urllib.request.html#module-urllib.request) для обработки URL, использующих FTP. Для получения дополнительной информации о FTP (File Transfer Protocol) см. [**RFC 959**](https://python-all.ru/3.1/library/ftplib.html).1011Вот пример сеанса с использованием модуля `ftplib`:1213```python14>>> from ftplib import FTP15>>> ftp = FTP('ftp.cwi.nl')   # подключение к хосту, порт по умолчанию16>>> ftp.login()               # пользователь anonymous, пароль anonymous@17>>> ftp.retrlines('LIST')     # список содержимого каталога18total 2441819drwxrwsr-x   5 ftp-usr  pdmaint     1536 Mar 20 09:48 .20dr-xr-srwt 105 ftp-usr  pdmaint     1536 Mar 21 14:32 ..21-rw-r--r--   1 ftp-usr  pdmaint     5305 Mar 20 09:48 INDEX22 .23 .24 .25>>> ftp.retrbinary('RETR README', open('README', 'wb').write)26'226 Transfer complete.'27>>> ftp.quit()28```2930Модуль определяет следующие элементы:3132#### `class ftplib.FTP(host='', user='', passwd='', acct=''[, timeout])`3334Возвращает новый экземпляр класса3536[`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP)3738. Когда указан3940*host*4142, вызывается метод4344`connect(host)`4546. Когда указан4748*user*4950, дополнительно вызывается метод5152`login(user, passwd, acct)`5354(где5556*passwd*5758и5960*acct*6162по умолчанию равны пустой строке, если не заданы). Необязательный параметр6364*timeout*6566задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).6768#### `exception ftplib.error_reply`6970Исключение, возникающее при получении неожиданного ответа от сервера.7172#### `exception ftplib.error_temp`7374Исключение, возникающее при получении кода ошибки, указывающего на временную ошибку (коды ответов в диапазоне 400–499).7576#### `exception ftplib.error_perm`7778Исключение, возникающее при получении кода ошибки, указывающего на постоянную ошибку (коды ответов в диапазоне 500–599).7980#### `exception ftplib.error_proto`8182Исключение, возникающее при получении ответа от сервера, который не соответствует спецификациям ответов протокола передачи файлов (File Transfer Protocol), то есть начинается с цифры в диапазоне 1–5.8384#### `ftplib.all_errors`8586Набор всех исключений (в виде кортежа), которые могут возбуждать методы экземпляров8788[`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP)8990в результате проблем с FTP-соединением (в отличие от ошибок программирования со стороны вызывающего кода). В этот набор входят четыре исключения, перечисленные выше, а также9192[`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error)9394и9596[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)9798.99100> **См. также**101>102> **Модуль [`netrc`](https://python-all.ru/3.1/library/netrc.html#module-netrc)**103>104> Синтаксический анализатор формата файла105>106> `.netrc`107>108> . Файл109>110> `.netrc`111>112> обычно используется FTP-клиентами для загрузки информации об аутентификации пользователя перед запросом к пользователю.113>114> Файл `Tools/scripts/ftpmirror.py` в дистрибутиве исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля `ftplib`. Его можно использовать как расширенный пример применения этого модуля.115116## 20.11.1. Объекты FTP117118Некоторые методы доступны в двух вариантах: один для работы с текстовыми файлами, другой для двоичных файлов. Они названы по имени используемой команды, за которым следует `lines` для текстовой версии или `binary` для двоичной версии.119120Экземпляры [`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP) имеют следующие методы:121122#### `FTP.set_debuglevel(level)`123124Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию,125126`0`127128, не даёт отладочного вывода. Значение129130`1`131132даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение133134`2`135136или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.137138#### `FTP.connect(host='', port=0[, timeout])`139140Подключается к указанному хосту и порту. Номер порта по умолчанию – `21`, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения.141142Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использована глобальная настройка тайм-аута по умолчанию.143144#### `FTP.getwelcome()`145146Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)147148#### `FTP.login(user='anonymous', passwd='', acct='')`149150Выполняет вход в систему под указанным именем151152*user*153154. Параметры155156*passwd*157158и159160*acct*161162являются необязательными и по умолчанию равны пустой строке. Если163164*user*165166не указан, по умолчанию используется167168`'anonymous'`169170. Если171172*user*173174равен175176`'anonymous'`177178, то179180*passwd*181182по умолчанию принимает значение183184`'anonymous@'`185186. Эта функция должна вызываться только один раз для каждого экземпляра после установления соединения; её не следует вызывать, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после того, как клиент выполнил вход. Параметр187188*acct*189190предоставляет «учётную информацию»; мало систем реализуют это.191192#### `FTP.abort()`193194Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.195196#### `FTP.sendcmd(cmd)`197198Отправляет простую строку команды на сервер и возвращает строку ответа.199200#### `FTP.voidcmd(cmd)`201202Отправляет простую командную строку на сервер и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае вызывает исключение203204[`error_reply`](https://python-all.ru/3.1/library/ftplib.html#ftplib.error_reply)205206.207208#### `FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)`209210Извлекает файл в бинарном режиме передачи. Параметр211212*cmd*213214должен быть соответствующей командой215216`RETR`217218:219220`'RETR filename'`221222. Функция223224*колбэк*225226вызывается для каждого полученного блока данных с одним строковым аргументом, содержащим блок данных. Необязательный аргумент227228*blocksize*229230задаёт максимальный размер порции для чтения из низкоуровневого сокетного объекта, создаваемого для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в231232*колбэк*233234). Выбирается разумное значение по умолчанию.235236*rest*237238означает то же самое, что и в методе239240[`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd)241242.243244#### `FTP.retrlines(cmd, callback=None)`245246Получает список файлов или каталогов в режиме передачи ASCII.247248*cmd*249250должна быть соответствующей командой251252`RETR`253254(см.255256[`retrbinary()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.retrbinary)257258) или такой командой, как259260`LIST`261262,263264`NLST`265266или267268`MLSD`269270(обычно это просто строка271272`'LIST'`273274).275276`LIST`277278получает список файлов и информацию о них.279280`NLST`281282получает список имён файлов. На некоторых серверах283284`MLSD`285286получает машиночитаемый список файлов и информацию о них. Функция287288*колбэк*289290вызывается для каждой строки с аргументом-строкой, содержащим строку с удалённым завершающим CRLF. По умолчанию291292*колбэк*293294выводит строку в295296`sys.stdout`297298.299300#### `FTP.set_pasv(boolean)`301302Включает пассивный режим, если303304*boolean*305306истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию.307308#### `FTP.storbinary(cmd, file, blocksize=8192, callback=None)`309310Сохраняет файл в бинарном режиме передачи.311312*cmd*313314должна быть соответствующей командой315316`STOR`317318:319320`"STOR filename"`321322.323324*file*325326– это открытый327328[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)329330, который читается до EOF с помощью его метода331332`read()`333334блоками размера335336*blocksize*337338для предоставления сохраняемых данных. По умолчанию аргумент339340*blocksize*341342равен 8192.343344*колбэк*345346– необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки.347348#### `FTP.storlines(cmd, file, callback=None)`349350Сохраняет файл в ASCII режиме передачи.351352*cmd*353354должна быть соответствующей командой355356`STOR`357358(см.359360[`storbinary()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.storbinary)361362). Строки читаются до EOF из открытого363364[*файлового объекта*](https://python-all.ru/3.1/glossary.html#term-file-object)365366*file*367368с помощью его метода369370`readline()`371372для предоставления сохраняемых данных.373374*колбэк*375376– необязательный вызываемый объект с одним параметром, который вызывается для каждой строки после её отправки.377378#### `FTP.transfercmd(cmd, rest=None)`379380Инициирует передачу по соединению данных. Если передача активная, отправляется команда `EPRT` или `PORT` и команда передачи, указанная параметром *cmd*, и принимается соединение. Если сервер пассивный, отправляется команда `EPSV` или `PASV`, выполняется подключение к нему и запускается команда передачи. В любом случае возвращается сокет для соединения.381382Если задан необязательный параметр *rest*, серверу отправляется команда `REST` с передачей *rest* в качестве аргумента. Обычно *rest* – это байтовое смещение в запрашиваемом файле; серверу указывается возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы *rest* был строкой, содержащей символы из печатного диапазона кодов ASCII от 33 до 126. Поэтому метод [`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd) преобразует *rest* в строку, но проверка содержимого строки не выполняется. Если сервер не распознаёт команду `REST`, будет вызвано исключение [`error_reply`](https://python-all.ru/3.1/library/ftplib.html#ftplib.error_reply). Если это происходит, просто вызовите [`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd) без аргумента *rest*.383384#### `FTP.ntransfercmd(cmd, rest=None)`385386Подобно387388[`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd)389390, но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается391392`None`393394. Параметры395396*cmd*397398и399400*rest*401402означают то же самое, что и в403404[`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd)405406.407408#### `FTP.nlst(argument[, ...])`409410Возвращает список имён файлов, полученный от команды411412`NLST`413414. Необязательный аргумент415416*argument*417418– это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде419420`NLST`421422.423424#### `FTP.dir(argument[, ...])`425426Формирует список каталога, возвращаемый командой427428`LIST`429430, выводя его в стандартный вывод. Необязательный аргумент431432*argument*433434– это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде435436`LIST`437438. Если последний аргумент является функцией, он используется как функция439440*колбэк*441442аналогично443444[`retrlines()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.retrlines)445446; по умолчанию вывод осуществляется в447448`sys.stdout`449450. Этот метод возвращает451452`None`453454.455456#### `FTP.rename(fromname, toname)`457458Переименовывает файл459460*fromname*461462на сервере в463464*toname*465466.467468#### `FTP.delete(filename)`469470Удаляет файл с именем471472*filename*473474с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает475476[`error_perm`](https://python-all.ru/3.1/library/ftplib.html#ftplib.error_perm)477478при ошибках разрешения или479480[`error_reply`](https://python-all.ru/3.1/library/ftplib.html#ftplib.error_reply)481482при других ошибках.483484#### `FTP.cwd(pathname)`485486Устанавливает текущий каталог на сервере.487488#### `FTP.mkd(pathname)`489490Создаёт новый каталог на сервере.491492#### `FTP.pwd()`493494Возвращает путь к текущему каталогу на сервере.495496#### `FTP.rmd(dirname)`497498Удаляет каталог с именем499500*dirname*501502на сервере.503504#### `FTP.size(filename)`505506Запрос размера файла с именем507508*filename*509510на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается511512`None`513514. Обратите внимание, что команда515516`SIZE`517518не стандартизирована, но поддерживается многими распространёнными реализациями серверов.519520#### `FTP.quit()`521522Отправляет команду523524`QUIT`525526серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но может вызвать исключение, если сервер отвечает ошибкой на команду527528`QUIT`529530. Это подразумевает вызов метода531532[`close()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.close)533534, который делает экземпляр535536[`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP)537538бесполезным для последующих вызовов (см. ниже).539540#### `FTP.close()`541542Закрывает соединение в одностороннем порядке. Не следует применять к уже закрытому соединению, например после успешного вызова543544[`quit()`](https://python-all.ru/3.1/library/constants.html#quit)545546. После этого вызова экземпляр547548[`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP)549550больше не следует использовать (после вызова551552[`close()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.close)553554или555556[`quit()`](https://python-all.ru/3.1/library/constants.html#quit)557558вы не сможете снова открыть соединение, вызвав другой метод559560[`login()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.login)561562).563