`ftplib.md`

243 строк · 26.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/ftplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.8. [`ftplib`](https://python-all.ru/2.7/library/ftplib.html#module-ftplib) – клиент протокола FTP89**Исходный код:** [Lib/ftplib.py](https://python-all.ru/src/2.7/Lib/ftplib.py)1011---1213Этот модуль определяет класс [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP) и несколько связанных с ним элементов. Класс [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP) реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем [`urllib`](https://python-all.ru/2.7/library/urllib.html#module-urllib) для обработки URL-адресов, использующих FTP. Дополнительную информацию о FTP (протокол передачи файлов) см. в Internet [**RFC 959**](https://python-all.ru/2.7/library/ftplib.html).1415Вот пример сеанса с использованием модуля [`ftplib`](https://python-all.ru/2.7/library/ftplib.html#module-ftplib):1617```python18>>> from ftplib import FTP19>>> ftp = FTP('ftp.debian.org')     # подключение к хосту, порт по умолчанию20>>> ftp.login()                     # пользователь anonymous, пароль anonymous@21'230 Login successful.'22>>> ftp.cwd('debian')               # перейти в каталог "debian"23>>> ftp.retrlines('LIST')           # список содержимого каталога24-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README25...26drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool27drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project28drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools29'226 Directory send OK.'30>>> ftp.retrbinary('RETR README', open('README', 'wb').write)31'226 Transfer complete.'32>>> ftp.quit()33```3435Модуль определяет следующие элементы:3637#### `class ftplib.FTP([host[, user[, passwd[, acct[, timeout]]]]])`3839Возвращает новый экземпляр класса [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP). Когда указан *host*, выполняется вызов метода `connect(host)`. Когда указан *user*, дополнительно выполняется вызов метода `login(user, passwd, acct)` (где *passwd* и *acct* по умолчанию равны пустой строке, если не заданы). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если он не указан, используется глобальная настройка тайм-аута по умолчанию).4041Изменено в версии 2.6: добавлен параметр *timeout*.4243#### `class ftplib.FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])`4445Подкласс [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP), добавляющий поддержку TLS для FTP, как описано в [**RFC 4217**](https://python-all.ru/2.7/library/ftplib.html). Подключение выполняется как обычно к порту 21, неявно защищая управляющее соединение FTP перед аутентификацией. Для защиты соединения данных требуется явный вызов метода [`prot_p()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP_TLS.prot_p). *context* – это объект [`ssl.SSLContext`](https://python-all.ru/2.7/library/ssl.html#ssl.SSLContext), который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну (потенциально долгоживущую) структуру. Ознакомьтесь с [рекомендациями по безопасности](https://python-all.ru/2.7/library/ssl.html#ssl-security) для получения лучших практик.4647*keyfile* и *certfile* – это устаревшая альтернатива *context* – они могут указывать на PEM-форматированные файлы закрытого ключа и цепочки сертификатов (соответственно) для SSL-соединения.4849Новое в версии 2.7.5051Изменено в версии 2.7.10: добавлен параметр *context*.5253Вот пример сеанса с использованием класса [`FTP_TLS`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP_TLS):5455```python56>>> from ftplib import FTP_TLS57>>> ftps = FTP_TLS('ftp.python.org')58>>> ftps.login()           # анонимный вход до защиты управляющего канала59>>> ftps.prot_p()          # переключиться на защищённое соединение данных60>>> ftps.retrlines('LIST') # безопасно вывести содержимое каталога61total 962drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 .63drwxr-xr-x   8 root     wheel        1024 Jan  3  1994 ..64drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 bin65drwxr-xr-x   2 root     wheel        1024 Jan  3  1994 etc66d-wxrwxr-x   2 ftp      wheel        1024 Sep  5 13:43 incoming67drwxr-xr-x   2 root     wheel        1024 Nov 17  1993 lib68drwxr-xr-x   6 1094     wheel        1024 Sep 13 19:07 pub69drwxr-xr-x   3 root     wheel        1024 Jan  3  1994 usr70-rw-r--r--   1 root     root          312 Aug  1  1994 welcome.msg71'226 Transfer complete.'72>>> ftps.quit()73>>>74```7576#### `exception ftplib.error_reply`7778Исключение, возникающее при получении неожиданного ответа от сервера.7980#### `exception ftplib.error_temp`8182Исключение, возникающее при получении кода ошибки, указывающего на временную ошибку (коды ответов в диапазоне 400–499).8384#### `exception ftplib.error_perm`8586Исключение, возникающее при получении кода ошибки, указывающего на постоянную ошибку (коды ответов в диапазоне 500–599).8788#### `exception ftplib.error_proto`8990Исключение, возникающее при получении ответа от сервера, который не соответствует спецификациям ответов протокола передачи файлов (File Transfer Protocol), то есть начинается с цифры в диапазоне 1–5.9192#### `ftplib.all_errors`9394Набор всех исключений (в виде кортежа), которые могут возбуждать методы экземпляров [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP) в результате проблем с FTP-соединением (в отличие от ошибок программирования, допущенных вызывающим кодом). Этот набор включает четыре перечисленных выше исключения, а также [`socket.error`](https://python-all.ru/2.7/library/socket.html#socket.error) и [`IOError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.IOError).9596> **См. также**97>98> **Модуль [`netrc`](https://python-all.ru/2.7/library/netrc.html#module-netrc)**99>100> Синтаксический анализатор для формата файлов `.netrc`. Файл `.netrc` обычно используется FTP-клиентами для загрузки информации аутентификации пользователя перед запросом к пользователю.101>102> Файл `Tools/scripts/ftpmirror.py` в дистрибутиве исходного кода Python – это сценарий, который может зеркалировать FTP-сайты (или их части) с помощью модуля [`ftplib`](https://python-all.ru/2.7/library/ftplib.html#module-ftplib). Его можно использовать как расширенный пример применения этого модуля.103104## 20.8.1. Объекты FTP105106Несколько методов доступны в двух вариантах: один для работы с текстовыми файлами, другой – для двоичных. Они названы по команде, за которой следует `lines` для текстовой версии или `binary` для двоичной.107108Экземпляры [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP) имеют следующие методы:109110#### `FTP.set_debuglevel(level)`111112Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, `0`, не даёт отладочного вывода. Значение `1` даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение `2` или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.113114#### `FTP.connect(host[, port[, timeout]])`115116Подключается к указанному хосту и порту. Номер порта по умолчанию – `21`, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения.117118Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использована глобальная настройка тайм-аута по умолчанию.119120Изменено в версии 2.6: добавлен параметр *timeout*.121122#### `FTP.getwelcome()`123124Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)125126#### `FTP.login([user[, passwd[, acct]]])`127128Выполняет вход под указанным *user*. Параметры *passwd* и *acct* необязательны и по умолчанию равны пустой строке. Если *user* не указан, по умолчанию используется `'anonymous'`. Если *user* равен `'anonymous'`, пароль *passwd* по умолчанию – `'anonymous@'`. Эта функция должна вызываться только один раз для каждого экземпляра после установки соединения; её не следует вызывать, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после входа клиента. Параметр *acct* предоставляет «учётную информацию»; лишь немногие системы это реализуют.129130#### `FTP.abort()`131132Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.133134#### `FTP.sendcmd(command)`135136Отправляет простую строку команды на сервер и возвращает строку ответа.137138#### `FTP.voidcmd(command)`139140Отправляет простую командную строку серверу и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае возбуждает [`error_reply`](https://python-all.ru/2.7/library/ftplib.html#ftplib.error_reply).141142#### `FTP.retrbinary(command, callback[, maxblocksize[, rest]])`143144Получает файл в двоичном режиме передачи. *command* должна быть соответствующей командой `RETR`: `'RETR filename'`. Функция *колбэк* вызывается для каждого полученного блока данных с одним строковым аргументом, содержащим блок данных. Необязательный аргумент *maxblocksize* задаёт максимальный размер фрагмента для чтения из низкоуровневого сокетного объекта, созданного для фактической передачи (это также будет максимальный размер блоков данных, передаваемых в *колбэк*). Выбирается разумное значение по умолчанию. *rest* означает то же самое, что и в методе [`transfercmd()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.transfercmd).145146#### `FTP.retrlines(command[, callback])`147148Получает список файлов или каталогов в ASCII-режиме передачи. *command* должна быть подходящей командой `RETR` (см. [`retrbinary()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.retrbinary)) или такой командой, как `LIST`, `NLST` или `MLSD` (обычно просто строка `'LIST'`). `LIST` получает список файлов и информацию о них. `NLST` получает список имён файлов. На некоторых серверах `MLSD` получает машиночитаемый список файлов и информации о них. Функция *колбэк* вызывается для каждой строки с аргументом-строкой, содержащей строку с удалённым завершающим CRLF. По умолчанию *колбэк* выводит строку в `sys.stdout`.149150#### `FTP.set_pasv(val)`151152Включает «пассивный» режим, если *val* истинно, в противном случае отключает пассивный режим. (В Python 2.0 и более ранних версиях пассивный режим был выключен по умолчанию; в Python 2.1 и более поздних версиях он включён по умолчанию.)153154#### `FTP.storbinary(command, fp[, blocksize, callback, rest])`155156Сохраняет файл в двоичном режиме передачи. *command* должна быть соответствующей командой `STOR`: `"STOR filename"`. *fp* – это открытый файловый объект, который читается до EOF с помощью его метода `read()` блоками размера *blocksize* для предоставления сохраняемых данных. Значение аргумента *blocksize* по умолчанию равно 8192. *колбэк* – необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки. *rest* означает то же самое, что и в методе [`transfercmd()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.transfercmd).157158Изменено в версии 2.1: добавлено значение по умолчанию для *blocksize*.159160Изменено в версии 2.6: добавлен параметр *колбэк*.161162Изменено в версии 2.7: добавлен параметр *rest*.163164#### `FTP.storlines(command, fp[, callback])`165166Сохраняет файл в ASCII-режиме передачи. *command* должна быть подходящей командой `STOR` (см. [`storbinary()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.storbinary)). Строки читаются до EOF из открытого файлового объекта *fp* с помощью его метода [`readline()`](https://python-all.ru/2.7/library/stdtypes.html#file.readline) для предоставления сохраняемых данных. *колбэк* – необязательный вызываемый объект с одним параметром, который вызывается для каждой строки после её отправки.167168Изменено в версии 2.6: добавлен параметр *колбэк*.169170#### `FTP.transfercmd(cmd[, rest])`171172Инициирует передачу по соединению данных. Если передача активная, отправляет команду `EPRT` или `PORT` и команду передачи, указанную в *cmd*, и принимает соединение. Если сервер пассивный, отправляет команду `EPSV` или `PASV`, подключается к нему и запускает команду передачи. В любом случае возвращает сокет соединения.173174Если указан необязательный *rest*, на сервер отправляется команда `REST`, передающая *rest* в качестве аргумента. Обычно *rest* – это смещение в байтах в запрашиваемом файле, указывающее серверу возобновить передачу байтов файла с указанного смещения, пропуская начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы *rest* был строкой, содержащей символы из диапазона печатных символов ASCII с кодами от 33 до 126. Поэтому метод [`transfercmd()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.transfercmd) преобразует *rest* в строку, но не выполняет проверку её содержимого. Если сервер не распознаёт команду `REST`, будет возбуждено исключение [`error_reply`](https://python-all.ru/2.7/library/ftplib.html#ftplib.error_reply). Если это произошло, просто вызовите [`transfercmd()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.transfercmd) без аргумента *rest*.175176#### `FTP.ntransfercmd(cmd[, rest])`177178Как и [`transfercmd()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.transfercmd), но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается `None`. *cmd* и *rest* имеют тот же смысл, что и в [`transfercmd()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.transfercmd).179180#### `FTP.nlst(argument[, ...])`181182Возвращает список имён файлов, возвращаемый командой `NLST`. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `NLST`.183184#### `FTP.dir(argument[, ...])`185186Выводит список каталога, возвращаемый командой `LIST`, печатая его в стандартный вывод. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `LIST`. Если последний аргумент является функцией, он используется как функция обратного вызова *колбэк*, как в [`retrlines()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.retrlines); по умолчанию вывод производится в `sys.stdout`. Этот метод возвращает `None`.187188#### `FTP.rename(fromname, toname)`189190Переименовывает файл *fromname* на сервере в *toname*.191192#### `FTP.delete(filename)`193194Удаляет файл с именем *filename* с сервера. В случае успеха возвращает текст ответа, иначе возбуждает [`error_perm`](https://python-all.ru/2.7/library/ftplib.html#ftplib.error_perm) при ошибках прав доступа или [`error_reply`](https://python-all.ru/2.7/library/ftplib.html#ftplib.error_reply) при других ошибках.195196#### `FTP.cwd(pathname)`197198Устанавливает текущий каталог на сервере.199200#### `FTP.mkd(pathname)`201202Создаёт новый каталог на сервере.203204#### `FTP.pwd()`205206Возвращает путь к текущему каталогу на сервере.207208#### `FTP.rmd(dirname)`209210Удаляет каталог с именем *dirname* на сервере.211212#### `FTP.size(filename)`213214Запрашивает размер файла с именем *filename* на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается `None`. Обратите внимание, что команда `SIZE` не стандартизирована, но поддерживается многими распространёнными реализациями серверов.215216#### `FTP.quit()`217218Отправляет команду `QUIT` серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но он может возбудить исключение, если сервер отвечает ошибкой на команду `QUIT`. Это подразумевает вызов метода [`close()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.close), который делает экземпляр [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP) бесполезным для последующих вызовов (см. ниже).219220#### `FTP.close()`221222Односторонне закрывает соединение. Не следует применять к уже закрытому соединению, например, после успешного вызова [`quit()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.quit). После этого вызова экземпляр [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP) больше не должен использоваться (после вызова [`close()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.close) или [`quit()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.quit) нельзя снова открыть соединение, вызвав метод [`login()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP.login)).223224## 20.8.2. Объекты FTP\_TLS225226[`FTP_TLS`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP_TLS) класс наследует от [`FTP`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP), определяя эти дополнительные объекты:227228#### `FTP_TLS.ssl_version`229230Версия SSL для использования (по умолчанию [`ssl.PROTOCOL_SSLv23`](https://python-all.ru/2.7/library/ssl.html#ssl.PROTOCOL_SSLv23)).231232#### `FTP_TLS.auth()`233234Устанавливает безопасное управляющее соединение с помощью TLS или SSL в зависимости от того, что указано в атрибуте [`ssl_version()`](https://python-all.ru/2.7/library/ftplib.html#ftplib.FTP_TLS.ssl_version).235236#### `FTP_TLS.prot_p()`237238Устанавливает защищённое соединение данных.239240#### `FTP_TLS.prot_c()`241242Устанавливает незащищённое соединение данных.243