`ftplib.md`

505 строк · 20.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/ftplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `ftplib` – клиент протокола FTP89Этот модуль определяет класс [`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP) и несколько связанных с ним элементов. Класс [`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP) реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем [`urllib.request`](https://python-all.ru/3.0/library/urllib.request.html#module-urllib.request) для обработки URL, использующих FTP. Для получения дополнительной информации о FTP (File Transfer Protocol) см. [**RFC 959**](https://python-all.ru/3.0/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#### `[ftplib.FTP]class ftplib.FTP([host[, user[, passwd[, acct[, timeout]]]]])`3334Возвращает новый экземпляр класса [`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP). Когда указан *host*, вызывается метод `connect(host)`. Когда указан *user*, дополнительно вызывается метод `login(user, passwd, acct)` (где *passwd* и *acct* по умолчанию равны пустой строке, если не заданы). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).3536#### `[ftplib.FTP.all_errors]all_errors`3738Набор всех исключений (в виде кортежа), которые могут возбуждать методы экземпляров3940[`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP)4142в результате проблем с FTP-соединением (в отличие от ошибок программирования, допущенных вызывающей стороной). Этот набор включает четыре перечисленных ниже исключения, а также4344[`socket.error`](https://python-all.ru/3.0/library/socket.html#socket.error)4546и4748[`IOError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IOError)4950.5152#### `[ftplib.FTP.error_reply]exception error_reply`5354Исключение, возникающее при получении неожиданного ответа от сервера.5556#### `[ftplib.error_temp]exception ftplib.error_temp`5758Исключение возбуждается при получении кода ошибки в диапазоне 400–499.5960#### `[ftplib.error_perm]exception ftplib.error_perm`6162Исключение возбуждается при получении кода ошибки в диапазоне 500–599.6364#### `[ftplib.error_proto]exception ftplib.error_proto`6566Исключение возбуждается, когда от сервера получен ответ, который не начинается с цифры в диапазоне 1–5.6768> **См. также**69>70> **Модуль [`netrc`](https://python-all.ru/3.0/library/netrc.html#module-netrc)**71>72> Парсер для формата файла73>74> `.netrc`75>76> . Файл77>78> `.netrc`79>80> обычно используется FTP-клиентами для загрузки данных аутентификации пользователя перед запросом у пользователя.81>82> Файл `Tools/scripts/ftpmirror.py` в дистрибутиве исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля `ftplib`. Его можно использовать как расширенный пример применения этого модуля.8384## Объекты FTP8586Некоторые методы доступны в двух вариантах: один для работы с текстовыми файлами, другой для двоичных файлов. Они названы по имени используемой команды, за которым следует `lines` для текстовой версии или `binary` для двоичной версии.8788Экземпляры [`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP) имеют следующие методы:8990#### `[ftplib.FTP.set_debuglevel]FTP.set_debuglevel(level)`9192Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию,9394`0`9596, не даёт отладочного вывода. Значение9798`1`99100даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение101102`2`103104или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.105106#### `[ftplib.FTP.connect]FTP.connect(host[, port[, timeout]])`107108Подключается к указанному хосту и порту. Номер порта по умолчанию – `21`, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения.109110Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использована глобальная настройка тайм-аута по умолчанию.111112#### `[ftplib.FTP.getwelcome]FTP.getwelcome()`113114Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)115116#### `[ftplib.FTP.login]FTP.login([user[, passwd[, acct]]])`117118Log in as the given119120*user*121122. The123124*passwd*125126and127128*acct*129130parameters are optional and default to the empty string. If no131132*user*133134is specified, it defaults to135136`'anonymous'`137138. If139140*user*141142is143144`'anonymous'`145146, the default147148*passwd*149150is151152`'anonymous@'`153154. This function should be called only once for each instance, after a connection has been established; it should not be called at all if a host and user were given when the instance was created. Most FTP commands are only allowed after the client has logged in.155156#### `[ftplib.FTP.abort]FTP.abort()`157158Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.159160#### `[ftplib.FTP.sendcmd]FTP.sendcmd(command)`161162Отправляет простую строку команды на сервер и возвращает строку ответа.163164#### `[ftplib.FTP.voidcmd]FTP.voidcmd(command)`165166Отправляет простую командную строку серверу и обрабатывает ответ. Ничего не возвращает, если получен код ответа в диапазоне 200–299. В противном случае возбуждает исключение.167168#### `[ftplib.FTP.retrbinary]FTP.retrbinary(command, callback[, maxblocksize[, rest]])`169170Извлекает файл в двоичном режиме передачи. Параметр171172*command*173174должен содержать соответствующую команду175176`RETR`177178:179180`'RETR filename'`181182. Функция183184*колбэк*185186вызывается для каждого полученного блока данных с одним строковым аргументом, представляющим блок данных. Необязательный аргумент187188*maxblocksize*189190задаёт максимальный размер блока для чтения из низкоуровневого сокета, созданного для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в191192*колбэк*193194). Выбирается разумное значение по умолчанию.195196*rest*197198означает то же самое, что и в методе199200[`transfercmd()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.transfercmd)201202.203204#### `[ftplib.FTP.retrlines]FTP.retrlines(command[, callback])`205206Извлекает файл или список каталога в текстовом режиме передачи. Параметр207208*command*209210должен содержать соответствующую команду211212`RETR`213214(см.215216[`retrbinary()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.retrbinary)217218) или команду типа219220`LIST`221222,223224`NLST`225226или227228`MLSD`229230(обычно просто строка231232`'LIST'`233234). Функция235236*колбэк*237238вызывается для каждой строки с удалёнными завершающими символами CRLF. Функция239240*колбэк*241242по умолчанию выводит строку в243244`sys.stdout`245246.247248#### `[ftplib.FTP.set_pasv]FTP.set_pasv(boolean)`249250Включает пассивный режим, если251252*boolean*253254истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию.255256#### `[ftplib.FTP.storbinary]FTP.storbinary(command, file[, blocksize, callback])`257258Сохраняет файл в двоичном режиме передачи. Параметр259260*command*261262должен содержать соответствующую команду263264`STOR`265266:267268`"STOR filename"`269270. Параметр271272*file*273274– это открытый файловый объект, который читается до конца файла с помощью его метода275276`read()`277278блоками размера279280*blocksize*281282для предоставления сохраняемых данных. Аргумент283284*blocksize*285286по умолчанию равен 8192.287288*колбэк*289290– необязательный вызываемый объект с одним параметром, который вызывается для каждого отправленного блока данных.291292#### `[ftplib.FTP.storlines]FTP.storlines(command, file[, callback])`293294Сохраняет файл в текстовом режиме передачи. Параметр295296*command*297298должен содержать соответствующую команду299300`STOR`301302(см.303304[`storbinary()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.storbinary)305306). Строки читаются до конца файла из открытого файлового объекта307308*file*309310с помощью его метода311312`readline()`313314для предоставления сохраняемых данных.315316*колбэк*317318– необязательный вызываемый объект с одним параметром, который вызывается для каждой отправленной строки.319320#### `[ftplib.FTP.transfercmd]FTP.transfercmd(cmd[, rest])`321322Инициирует передачу по соединению данных. Если передача активная, отправляется команда `EPRT` или `PORT` и команда передачи, указанная параметром *cmd*, и принимается соединение. Если сервер пассивный, отправляется команда `EPSV` или `PASV`, выполняется подключение к нему и запускается команда передачи. В любом случае возвращается сокет для соединения.323324Если задан необязательный параметр *rest*, серверу отправляется команда `REST` с передачей *rest* в качестве аргумента. Обычно *rest* – это байтовое смещение в запрашиваемом файле; серверу указывается возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы *rest* был строкой, содержащей символы из печатного диапазона кодов ASCII от 33 до 126. Поэтому метод [`transfercmd()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.transfercmd) преобразует *rest* в строку, но проверка содержимого строки не выполняется. Если сервер не распознаёт команду `REST`, будет вызвано исключение [`error_reply`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.error_reply). Если это происходит, просто вызовите [`transfercmd()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.transfercmd) без аргумента *rest*.325326#### `[ftplib.FTP.ntransfercmd]FTP.ntransfercmd(cmd[, rest])`327328Подобно329330[`transfercmd()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.transfercmd)331332, но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается333334`None`335336. Параметры337338*cmd*339340и341342*rest*343344означают то же самое, что и в345346[`transfercmd()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.transfercmd)347348.349350#### `[ftplib.FTP.nlst]FTP.nlst(argument[, ...])`351352Возвращает список файлов, возвращаемый командой353354`NLST`355356. Необязательный357358*аргумент*359360– каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно указать несколько аргументов для передачи нестандартных параметров команде361362`NLST`363364.365366#### `[ftplib.FTP.dir]FTP.dir(argument[, ...])`367368Формирует список каталога, возвращаемый командой369370`LIST`371372, выводя его в стандартный вывод. Необязательный аргумент373374*argument*375376– это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде377378`LIST`379380. Если последний аргумент является функцией, он используется как функция381382*колбэк*383384аналогично385386[`retrlines()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.retrlines)387388; по умолчанию вывод осуществляется в389390`sys.stdout`391392. Этот метод возвращает393394`None`395396.397398#### `[ftplib.FTP.rename]FTP.rename(fromname, toname)`399400Переименовывает файл401402*fromname*403404на сервере в405406*toname*407408.409410#### `[ftplib.FTP.delete]FTP.delete(filename)`411412Удаляет файл с именем413414*filename*415416с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает417418[`error_perm`](https://python-all.ru/3.0/library/ftplib.html#ftplib.error_perm)419420при ошибках разрешения или421422[`error_reply`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.error_reply)423424при других ошибках.425426#### `[ftplib.FTP.cwd]FTP.cwd(pathname)`427428Устанавливает текущий каталог на сервере.429430#### `[ftplib.FTP.mkd]FTP.mkd(pathname)`431432Создаёт новый каталог на сервере.433434#### `[ftplib.FTP.pwd]FTP.pwd()`435436Возвращает путь к текущему каталогу на сервере.437438#### `[ftplib.FTP.rmd]FTP.rmd(dirname)`439440Удаляет каталог с именем441442*dirname*443444на сервере.445446#### `[ftplib.FTP.size]FTP.size(filename)`447448Запрос размера файла с именем449450*filename*451452на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается453454`None`455456. Обратите внимание, что команда457458`SIZE`459460не стандартизирована, но поддерживается многими распространёнными реализациями серверов.461462#### `[ftplib.FTP.quit]FTP.quit()`463464Отправляет команду465466`QUIT`467468серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но может вызвать исключение, если сервер отвечает ошибкой на команду469470`QUIT`471472. Это подразумевает вызов метода473474[`close()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.close)475476, который делает экземпляр477478[`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP)479480бесполезным для последующих вызовов (см. ниже).481482#### `[ftplib.FTP.close]FTP.close()`483484Закрывает соединение в одностороннем порядке. Не следует применять к уже закрытому соединению, например после успешного вызова485486[`quit()`](https://python-all.ru/3.0/library/constants.html#quit)487488. После этого вызова экземпляр489490[`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP)491492больше не следует использовать (после вызова493494[`close()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.close)495496или497498[`quit()`](https://python-all.ru/3.0/library/constants.html#quit)499500вы не сможете снова открыть соединение, вызвав другой метод501502[`login()`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP.login)503504).505