> **Источник:** https://python-all.ru/3.2/library/ftplib.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 20.11. [`ftplib`](https://python-all.ru/3.2/library/ftplib.html#module-ftplib) – клиент протокола FTP **Исходный код:** [Lib/ftplib.py](https://python-all.ru/src/3.2/Lib/ftplib.py) --- Этот модуль определяет класс [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) и несколько связанных с ним элементов. Класс [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем [`urllib.request`](https://python-all.ru/3.2/library/urllib.request.html#module-urllib.request) для обработки URL, использующих FTP. Для получения дополнительной информации о FTP (File Transfer Protocol) см. [**RFC 959**](https://python-all.ru/3.2/library/ftplib.html). Вот пример сеанса работы с модулем [`ftplib`](https://python-all.ru/3.2/library/ftplib.html#module-ftplib): ```python >>> from ftplib import FTP >>> ftp = FTP('ftp.cwi.nl') # подключение к хосту, порт по умолчанию >>> ftp.login() # пользователь anonymous, пароль anonymous@ >>> ftp.retrlines('LIST') # список содержимого каталога total 24418 drwxrwsr-x 5 ftp-usr pdmaint 1536 Mar 20 09:48 . dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 .. -rw-r--r-- 1 ftp-usr pdmaint 5305 Mar 20 09:48 INDEX . . . >>> ftp.retrbinary('RETR README', open('README', 'wb').write) '226 Transfer complete.' >>> ftp.quit() ``` Модуль определяет следующие элементы: #### `class ftplib.FTP(host='', user='', passwd='', acct=''[, timeout])` Возвращает новый экземпляр класса [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP). Когда указан *host*, вызывается метод `connect(host)`. Когда указан *user*, дополнительно вызывается метод `login(user, passwd, acct)` (где *passwd* и *acct* по умолчанию равны пустой строке, если не заданы). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию). [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) класс поддерживает оператор [`with`](https://python-all.ru/3.2/reference/compound_stmts.html#with). Вот пример его использования: ```python >>> 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`](https://python-all.ru/3.2/reference/compound_stmts.html#with). #### `class ftplib.FTP_TLS(host='', user='', passwd='', acct=''[, keyfile[, certfile[, context[, timeout]]]])` Подкласс [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP), который добавляет поддержку TLS к FTP, как описано в [**RFC 4217**](https://python-all.ru/3.2/library/ftplib.html). Обычно подключение выполняется к порту 21, при этом управляющее соединение FTP неявно защищается перед аутентификацией. Для защиты канала данных пользователь должен явно запросить её, вызвав метод [`prot_p()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP_TLS.prot_p). *keyfile* и *certfile* необязательны – они могут содержать имя файла закрытого ключа в формате PEM и цепочку сертификатов для SSL-соединения. Параметр *context* – это объект [`ssl.SSLContext`](https://python-all.ru/3.2/library/ssl.html#ssl.SSLContext), который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Новое в версии 3.2. Вот пример сеанса работы с классом [`FTP_TLS`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP_TLS): ```python >>> from ftplib import FTP_TLS >>> ftps = FTP_TLS('ftp.python.org') >>> ftps.login() # анонимный вход до защиты управляющего канала >>> ftps.prot_p() # переключиться на защищённое соединение данных >>> ftps.retrlines('LIST') # безопасно вывести содержимое каталога total 9 drwxr-xr-x 8 root wheel 1024 Jan 3 1994 . drwxr-xr-x 8 root wheel 1024 Jan 3 1994 .. drwxr-xr-x 2 root wheel 1024 Jan 3 1994 bin drwxr-xr-x 2 root wheel 1024 Jan 3 1994 etc d-wxrwxr-x 2 ftp wheel 1024 Sep 5 13:43 incoming drwxr-xr-x 2 root wheel 1024 Nov 17 1993 lib drwxr-xr-x 6 1094 wheel 1024 Sep 13 19:07 pub drwxr-xr-x 3 root wheel 1024 Jan 3 1994 usr -rw-r--r-- 1 root root 312 Aug 1 1994 welcome.msg '226 Transfer complete.' >>> ftps.quit() >>> ``` #### `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`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) в результате проблем с FTP-соединением (в отличие от ошибок программирования со стороны вызывающего кода). В этот набор входят четыре исключения, перечисленные выше, а также [`socket.error`](https://python-all.ru/3.2/library/socket.html#socket.error) и [`IOError`](https://python-all.ru/3.2/library/exceptions.html#IOError). > **См. также** > > **Модуль [`netrc`](https://python-all.ru/3.2/library/netrc.html#module-netrc)** > > Синтаксический анализатор формата файла > > `.netrc` > > . Файл > > `.netrc` > > обычно используется FTP-клиентами для загрузки информации об аутентификации пользователя перед запросом к пользователю. > > Файл `Tools/scripts/ftpmirror.py` в составе дистрибутива исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля [`ftplib`](https://python-all.ru/3.2/library/ftplib.html#module-ftplib). Его можно использовать как расширенный пример применения этого модуля. ## 20.11.1. Объекты FTP Некоторые методы доступны в двух вариантах: один для работы с текстовыми файлами, другой для двоичных файлов. Они названы по имени используемой команды, за которым следует `lines` для текстовой версии или `binary` для двоичной версии. Экземпляры [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) имеют следующие методы: #### `FTP.set_debuglevel(level)` Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, `0`, не даёт отладочного вывода. Значение `1` даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение `2` или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению. #### `FTP.connect(host='', port=0[, timeout])` Подключается к указанному хосту и порту. Номер порта по умолчанию – `21`, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения. Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использована глобальная настройка тайм-аута по умолчанию. #### `FTP.getwelcome()` Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.) #### `FTP.login(user='anonymous', passwd='', acct='')` Выполняет вход в систему под указанным именем *user*. Параметры *passwd* и *acct* являются необязательными и по умолчанию равны пустой строке. Если *user* не указан, по умолчанию используется `'anonymous'`. Если *user* равен `'anonymous'`, то *passwd* по умолчанию принимает значение `'anonymous@'`. Эта функция должна вызываться только один раз для каждого экземпляра после установления соединения; её не следует вызывать, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после того, как клиент выполнил вход. Параметр *acct* предоставляет «учётную информацию»; мало систем реализуют это. #### `FTP.abort()` Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит. #### `FTP.sendcmd(cmd)` Отправляет простую строку команды на сервер и возвращает строку ответа. #### `FTP.voidcmd(cmd)` Отправляет простую командную строку на сервер и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае вызывает исключение [`error_reply`](https://python-all.ru/3.2/library/ftplib.html#ftplib.error_reply). #### `FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)` Извлекает файл в бинарном режиме передачи. Параметр *cmd* должен быть соответствующей командой `RETR`: `'RETR filename'`. Функция *колбэк* вызывается для каждого полученного блока данных с одним строковым аргументом, содержащим блок данных. Необязательный аргумент *blocksize* задаёт максимальный размер порции для чтения из низкоуровневого сокетного объекта, создаваемого для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в *колбэк*). Выбирается разумное значение по умолчанию. *rest* означает то же самое, что и в методе [`transfercmd()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.transfercmd). #### `FTP.retrlines(cmd, callback=None)` Получает список файлов или каталогов в режиме передачи ASCII. *cmd* должна быть соответствующей командой `RETR` (см. [`retrbinary()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.retrbinary)) или такой командой, как `LIST`, `NLST` или `MLSD` (обычно это просто строка `'LIST'`). `LIST` получает список файлов и информацию о них. `NLST` получает список имён файлов. На некоторых серверах `MLSD` получает машиночитаемый список файлов и информацию о них. Функция *колбэк* вызывается для каждой строки с аргументом-строкой, содержащим строку с удалённым завершающим CRLF. По умолчанию *колбэк* выводит строку в `sys.stdout`. #### `FTP.set_pasv(boolean)` Включает пассивный режим, если *boolean* истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию. #### `FTP.storbinary(cmd, file, blocksize=8192, callback=None, rest=None)` Сохраняет файл в двоичном режиме передачи. *cmd* должен быть соответствующей командой `STOR`: `"STOR filename"`. *file* – это [*файловый объект*](https://python-all.ru/3.2/glossary.html#term-file-object) (открытый в двоичном режиме), который читается до EOF с помощью его метода `read()` блоками размером *blocksize* для предоставления сохраняемых данных. Аргумент *blocksize* по умолчанию равен 8192. *колбэк* – это необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки. *rest* означает то же самое, что и в методе [`transfercmd()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.transfercmd). Изменено в версии 3.2: добавлен параметр *rest*. #### `FTP.storlines(cmd, file, callback=None)` Сохраняет файл в текстовом режиме передачи (ASCII). *cmd* должен быть соответствующей командой `STOR` (см. [`storbinary()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.storbinary)). Строки читаются до EOF из [*файлового объекта*](https://python-all.ru/3.2/glossary.html#term-file-object) *file* (открытого в двоичном режиме) с помощью его метода [`readline()`](https://python-all.ru/3.2/library/readline.html#module-readline) для предоставления сохраняемых данных. *колбэк* – это необязательный вызываемый объект с одним параметром, который вызывается для каждой строки после её отправки. #### `FTP.transfercmd(cmd, rest=None)` Инициирует передачу по соединению данных. Если передача активная, отправляется команда `EPRT` или `PORT` и команда передачи, указанная параметром *cmd*, и принимается соединение. Если сервер пассивный, отправляется команда `EPSV` или `PASV`, выполняется подключение к нему и запускается команда передачи. В любом случае возвращается сокет для соединения. Если задан необязательный параметр *rest*, серверу отправляется команда `REST` с передачей *rest* в качестве аргумента. Обычно *rest* – это байтовое смещение в запрашиваемом файле; серверу указывается возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы *rest* был строкой, содержащей символы из печатного диапазона кодов ASCII от 33 до 126. Поэтому метод [`transfercmd()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.transfercmd) преобразует *rest* в строку, но проверка содержимого строки не выполняется. Если сервер не распознаёт команду `REST`, будет вызвано исключение [`error_reply`](https://python-all.ru/3.2/library/ftplib.html#ftplib.error_reply). Если это происходит, просто вызовите [`transfercmd()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.transfercmd) без аргумента *rest*. #### `FTP.ntransfercmd(cmd, rest=None)` Подобно [`transfercmd()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.transfercmd), но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается `None`. Параметры *cmd* и *rest* означают то же самое, что и в [`transfercmd()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.transfercmd). #### `FTP.nlst(argument[, ...])` Возвращает список имён файлов, полученный от команды `NLST`. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `NLST`. #### `FTP.dir(argument[, ...])` Формирует список каталога, возвращаемый командой `LIST`, выводя его в стандартный вывод. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `LIST`. Если последний аргумент является функцией, он используется как функция *колбэк* аналогично [`retrlines()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.retrlines); по умолчанию вывод осуществляется в `sys.stdout`. Этот метод возвращает `None`. #### `FTP.rename(fromname, toname)` Переименовывает файл *fromname* на сервере в *toname*. #### `FTP.delete(filename)` Удаляет файл с именем *filename* с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает [`error_perm`](https://python-all.ru/3.2/library/ftplib.html#ftplib.error_perm) при ошибках разрешения или [`error_reply`](https://python-all.ru/3.2/library/ftplib.html#ftplib.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()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.close), который делает экземпляр [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) бесполезным для последующих вызовов (см. ниже). #### `FTP.close()` Закрывает соединение в одностороннем порядке. Это не следует применять к уже закрытому соединению, например после успешного вызова [`quit()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.quit). После этого вызова экземпляр [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) больше не должен использоваться (после вызова [`close()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.close) или [`quit()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.quit) нельзя повторно открыть соединение, вызвав метод [`login()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP.login)). ## 20.11.2. Объекты FTP\_TLS Класс [`FTP_TLS`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP_TLS) наследуется от [`FTP`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP) и определяет следующие дополнительные объекты: #### `FTP_TLS.ssl_version` Используемая версия SSL (по умолчанию *TLSv1*). #### `FTP_TLS.auth()` Устанавливает защищённое управляющее соединение с использованием TLS или SSL, в зависимости от того, что указано в атрибуте [`ssl_version()`](https://python-all.ru/3.2/library/ftplib.html#ftplib.FTP_TLS.ssl_version). #### `FTP_TLS.prot_p()` Устанавливает защищённое соединение данных. #### `FTP_TLS.prot_c()` Устанавливает незащищённое соединение данных.