ftplib.md
1> **Источник:** https://python-all.ru/3.4/library/ftplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.13. [`ftplib`](https://python-all.ru/3.4/library/ftplib.html#module-ftplib) – клиент протокола FTP89**Исходный код:** [Lib/ftplib.py](https://python-all.ru/src/3.4/Lib/ftplib.py)1011---1213Этот модуль определяет класс [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) и несколько связанных с ним элементов. Класс [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем [`urllib.request`](https://python-all.ru/3.4/library/urllib.request.html#module-urllib.request) для обработки URL, использующих FTP. Для получения дополнительной информации о FTP (File Transfer Protocol) см. [**RFC 959**](https://python-all.ru/3.4/library/ftplib.html).1415Вот пример сеанса работы с модулем [`ftplib`](https://python-all.ru/3.4/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=None, source_address=None)`3839Возвращает новый экземпляр класса [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP). Если указан *host*, вызывается метод `connect(host)`. Если указан *user*, дополнительно вызывается метод `login(user, passwd, acct)` (где *passwd* и *acct* по умолчанию равны пустой строке, если не заданы). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию). *source\_address* – это кортеж из двух элементов `(host, port)`, к которому привязывается сокет в качестве исходного адреса перед подключением.4041Класс [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) поддерживает оператор [`with`](https://python-all.ru/3.4/reference/compound_stmts.html#with), например:4243```python44>>> from ftplib import FTP45>>> with FTP("ftp1.at.proftpd.org") as ftp:46... ftp.login()47... ftp.dir()48...49'230 Anonymous login ok, restrictions apply.'50dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .51dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 ..52dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS53dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora54>>>55```5657Изменено в версии 3.2: Добавлена поддержка оператора [`with`](https://python-all.ru/3.4/reference/compound_stmts.html#with).5859Изменено в версии 3.3: добавлен параметр *source\_address*.6061#### `class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)`6263Подкласс [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP), добавляющий поддержку TLS в FTP, как описано в [**RFC 4217**](https://python-all.ru/3.4/library/ftplib.html). Обычно подключайтесь к порту 21, неявно защищая управляющее соединение FTP перед аутентификацией. Для защиты соединения с данными пользователь должен явно запросить её, вызвав метод [`prot_p()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP_TLS.prot_p). *context* – это объект [`ssl.SSLContext`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext), который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Пожалуйста, прочитайте [*Рекомендации по безопасности*](https://python-all.ru/3.4/library/ssl.html#ssl-security) для получения лучших практик.6465*keyfile* и *certfile* – это устаревшая альтернатива *context* – они могут указывать на PEM-форматированные файлы закрытого ключа и цепочки сертификатов (соответственно) для SSL-соединения.6667Новое в версии 3.2.6869Изменено в версии 3.3: добавлен параметр *source\_address*.7071Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.4/library/ssl.html#ssl.HAS_SNI)).7273Вот пример сеанса работы с классом [`FTP_TLS`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP_TLS):7475```python76>>> ftps = FTP_TLS('ftp.pureftpd.org')77>>> ftps.login()78'230 Anonymous user logged in'79>>> ftps.prot_p()80'200 Data protection level set to "private"'81>>> ftps.nlst()82['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']83```8485#### `exception ftplib.error_reply`8687Исключение, возникающее при получении неожиданного ответа от сервера.8889#### `exception ftplib.error_temp`9091Исключение, возникающее при получении кода ошибки, указывающего на временную ошибку (коды ответов в диапазоне 400–499).9293#### `exception ftplib.error_perm`9495Исключение, возникающее при получении кода ошибки, указывающего на постоянную ошибку (коды ответов в диапазоне 500–599).9697#### `exception ftplib.error_proto`9899Исключение, возникающее при получении ответа от сервера, который не соответствует спецификациям ответов протокола передачи файлов (File Transfer Protocol), то есть начинается с цифры в диапазоне 1–5.100101#### `ftplib.all_errors`102103Набор всех исключений (в виде кортежа), которые могут вызывать методы экземпляров [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) в результате проблем с FTP-соединением (в отличие от ошибок программирования, допущенных вызывающей стороной). Этот набор включает четыре исключения, перечисленные выше, а также [`OSError`](https://python-all.ru/3.4/library/exceptions.html#OSError).104105> **См. также**106>107> **Модуль [`netrc`](https://python-all.ru/3.4/library/netrc.html#module-netrc)**108>109> Синтаксический анализатор формата файла110>111> `.netrc`112>113> . Файл114>115> `.netrc`116>117> обычно используется FTP-клиентами для загрузки информации об аутентификации пользователя перед запросом к пользователю.118>119> Файл `Tools/scripts/ftpmirror.py` в составе дистрибутива исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля [`ftplib`](https://python-all.ru/3.4/library/ftplib.html#module-ftplib). Его можно использовать как расширенный пример применения этого модуля.120121## 21.13.1. Объекты FTP122123Некоторые методы доступны в двух вариантах: один для работы с текстовыми файлами, другой для двоичных файлов. Они названы по имени используемой команды, за которым следует `lines` для текстовой версии или `binary` для двоичной версии.124125Экземпляры [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) имеют следующие методы:126127#### `FTP.set_debuglevel(level)`128129Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, `0`, не даёт отладочного вывода. Значение `1` даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение `2` или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.130131#### `FTP.connect(host='', port=0, timeout=None, source_address=None)`132133Подключается к указанному хосту и порту. Номер порта по умолчанию – `21`, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эта функция должна вызываться только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установления соединения. Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использована глобальная настройка тайм-аута по умолчанию. *source\_address* – это кортеж из двух элементов `(host, port)`, к которому привязывается сокет в качестве исходного адреса перед подключением.134135Изменено в версии 3.3: добавлен параметр *source\_address*.136137#### `FTP.getwelcome()`138139Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)140141#### `FTP.login(user='anonymous', passwd='', acct='')`142143Выполняет вход в систему под указанным именем *user*. Параметры *passwd* и *acct* являются необязательными и по умолчанию равны пустой строке. Если *user* не указан, по умолчанию используется `'anonymous'`. Если *user* равен `'anonymous'`, то *passwd* по умолчанию принимает значение `'anonymous@'`. Эта функция должна вызываться только один раз для каждого экземпляра после установления соединения; её не следует вызывать, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после того, как клиент выполнил вход. Параметр *acct* предоставляет «учётную информацию»; мало систем реализуют это.144145#### `FTP.abort()`146147Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.148149#### `FTP.sendcmd(cmd)`150151Отправляет простую строку команды на сервер и возвращает строку ответа.152153#### `FTP.voidcmd(cmd)`154155Отправляет простую командную строку на сервер и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае вызывает исключение [`error_reply`](https://python-all.ru/3.4/library/ftplib.html#ftplib.error_reply).156157#### `FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)`158159Извлекает файл в бинарном режиме передачи. Параметр *cmd* должен быть соответствующей командой `RETR`: `'RETR filename'`. Функция *колбэк* вызывается для каждого полученного блока данных с одним строковым аргументом, содержащим блок данных. Необязательный аргумент *blocksize* задаёт максимальный размер порции для чтения из низкоуровневого сокетного объекта, создаваемого для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в *колбэк*). Выбирается разумное значение по умолчанию. *rest* означает то же самое, что и в методе [`transfercmd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.transfercmd).160161#### `FTP.retrlines(cmd, callback=None)`162163Извлекает файл или список каталогов в ASCII-режиме передачи. Параметр *cmd* должен быть соответствующей командой `RETR` (см. [`retrbinary()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.retrbinary)) или командой вроде `LIST` или `NLST` (обычно просто строка `'LIST'`). `LIST` возвращает список файлов и информацию об этих файлах. `NLST` возвращает список имён файлов. Функция *колбэк* вызывается для каждой строки с аргументом-строкой, содержащей строку с удалённым завершающим CRLF. Функция *колбэк* по умолчанию выводит строку в `sys.stdout`.164165#### `FTP.set_pasv(boolean)`166167Включает пассивный режим, если *boolean* истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию.168169#### `FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)`170171Сохраняет файл в бинарном режиме передачи. Параметр *cmd* должен быть соответствующей командой `STOR`: `"STOR filename"`. *fp* – это [*файловый объект*](https://python-all.ru/3.4/glossary.html#term-file-object) (открытый в бинарном режиме), из которого читаются данные до EOF с помощью его метода `read()` блоками размера *blocksize* для передачи сохраняемых данных. Аргумент *blocksize* по умолчанию равен 8192. *колбэк* – это необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки. *rest* означает то же самое, что и в методе [`transfercmd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.transfercmd).172173Изменено в версии 3.2: *rest* добавлен параметр.174175#### `FTP.storlines(cmd, fp, callback=None)`176177Сохраняет файл в ASCII-режиме передачи. Параметр *cmd* должен быть соответствующей командой `STOR` (см. [`storbinary()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.storbinary)). Строки читаются до EOF из [*файлового объекта*](https://python-all.ru/3.4/glossary.html#term-file-object) *fp* (открытого в бинарном режиме) с помощью его метода [`readline()`](https://python-all.ru/3.4/library/io.html#io.IOBase.readline) для передачи сохраняемых данных. *колбэк* – это необязательный вызываемый объект с одним параметром, который вызывается для каждой строки после её отправки.178179#### `FTP.transfercmd(cmd, rest=None)`180181Инициирует передачу через соединение данных. Если передача активная, отправляет команду `EPRT` или `PORT` и команду передачи, указанную в *cmd*, и принимает соединение. Если сервер пассивный, отправляет команду `EPSV` или `PASV`, подключается к нему и запускает команду передачи. В любом случае возвращает сокет для соединения.182183Если задан необязательный параметр *rest*, серверу отправляется команда `REST` с передачей *rest* в качестве аргумента. Обычно *rest* – это байтовое смещение в запрашиваемом файле; серверу указывается возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы *rest* был строкой, содержащей символы из печатного диапазона кодов ASCII от 33 до 126. Поэтому метод [`transfercmd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.transfercmd) преобразует *rest* в строку, но проверка содержимого строки не выполняется. Если сервер не распознаёт команду `REST`, будет вызвано исключение [`error_reply`](https://python-all.ru/3.4/library/ftplib.html#ftplib.error_reply). Если это происходит, просто вызовите [`transfercmd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.transfercmd) без аргумента *rest*.184185#### `FTP.ntransfercmd(cmd, rest=None)`186187Подобно [`transfercmd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.transfercmd), но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается `None`. Параметры *cmd* и *rest* означают то же самое, что и в [`transfercmd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.transfercmd).188189#### `FTP.mlsd(path="", facts=[])`190191Выводит список каталога в стандартизированном формате с помощью команды MLSD ([**RFC 3659**](https://python-all.ru/3.4/library/ftplib.html)). Если *path* опущен, подразумевается текущий каталог. *facts* – это список строк, представляющих тип запрашиваемой информации (например, `["type", "size", "perm"]`). Возвращает объект-генератор, выдающий кортеж из двух элементов для каждого файла, найденного в path. Первый элемент – имя файла, второй – словарь, содержащий сведения об имени файла. Содержимое этого словаря может быть ограничено аргументом *facts*, но сервер не гарантирует возврат всех запрошенных сведений.192193Новое в версии 3.3.194195#### `FTP.nlst(argument[, ...])`196197Возвращает список имён файлов, полученный от команды `NLST`. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `NLST`.198199Устарело с версии 3.3: используйте [`mlsd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.mlsd) вместо этого.200201#### `FTP.dir(argument[, ...])`202203Формирует список каталога, возвращаемый командой `LIST`, выводя его в стандартный вывод. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `LIST`. Если последний аргумент является функцией, он используется как функция *колбэк* аналогично [`retrlines()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.retrlines); по умолчанию вывод осуществляется в `sys.stdout`. Этот метод возвращает `None`.204205Устарело с версии 3.3: используйте [`mlsd()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.mlsd) вместо этого.206207#### `FTP.rename(fromname, toname)`208209Переименовывает файл *fromname* на сервере в *toname*.210211#### `FTP.delete(filename)`212213Удаляет файл с именем *filename* с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает [`error_perm`](https://python-all.ru/3.4/library/ftplib.html#ftplib.error_perm) при ошибках разрешения или [`error_reply`](https://python-all.ru/3.4/library/ftplib.html#ftplib.error_reply) при других ошибках.214215#### `FTP.cwd(pathname)`216217Устанавливает текущий каталог на сервере.218219#### `FTP.mkd(pathname)`220221Создаёт новый каталог на сервере.222223#### `FTP.pwd()`224225Возвращает путь к текущему каталогу на сервере.226227#### `FTP.rmd(dirname)`228229Удаляет каталог с именем *dirname* на сервере.230231#### `FTP.size(filename)`232233Запрос размера файла с именем *filename* на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается `None`. Обратите внимание, что команда `SIZE` не стандартизирована, но поддерживается многими распространёнными реализациями серверов.234235#### `FTP.quit()`236237Отправляет команду `QUIT` серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но может вызвать исключение, если сервер отвечает ошибкой на команду `QUIT`. Это подразумевает вызов метода [`close()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.close), который делает экземпляр [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) бесполезным для последующих вызовов (см. ниже).238239#### `FTP.close()`240241Закрывает соединение в одностороннем порядке. Это не следует применять к уже закрытому соединению, например после успешного вызова [`quit()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.quit). После этого вызова экземпляр [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) больше не должен использоваться (после вызова [`close()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.close) или [`quit()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.quit) нельзя повторно открыть соединение, вызвав метод [`login()`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP.login)).242243## 21.13.2. Объекты FTP\_TLS244245Класс [`FTP_TLS`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP_TLS) наследуется от [`FTP`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP) и определяет следующие дополнительные объекты:246247#### `FTP_TLS.ssl_version`248249Используемая версия SSL (по умолчанию [`ssl.PROTOCOL_SSLv23`](https://python-all.ru/3.4/library/ssl.html#ssl.PROTOCOL_SSLv23)).250251#### `FTP_TLS.auth()`252253Устанавливает защищённое управляющее соединение с использованием TLS или SSL в зависимости от того, что указано в атрибуте [`ssl_version`](https://python-all.ru/3.4/library/ftplib.html#ftplib.FTP_TLS.ssl_version).254255Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.4/library/ssl.html#ssl.HAS_SNI)).256257#### `FTP_TLS.ccc()`258259Возвращает управляющий канал обратно в открытый текст. Это может быть полезно для использования межсетевых экранов, которые умеют обрабатывать NAT с небезопасным FTP без открытия фиксированных портов.260261Новое в версии 3.3.262263#### `FTP_TLS.prot_p()`264265Устанавливает защищённое соединение данных.266267#### `FTP_TLS.prot_c()`268269Устанавливает незащищённое соединение данных.270