> **Источник:** https://python-all.ru/3.1/library/ftplib.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 20.11. `ftplib` – клиент протокола FTP

Этот модуль определяет класс [`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).

Вот пример сеанса с использованием модуля `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.1/library/ftplib.html#ftplib.FTP)

. Когда указан

*host*

, вызывается метод

`connect(host)`

. Когда указан

*user*

, дополнительно вызывается метод

`login(user, passwd, acct)`

(где

*passwd*

и

*acct*

по умолчанию равны пустой строке, если не заданы). Необязательный параметр

*timeout*

задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).

#### `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.1/library/ftplib.html#ftplib.FTP)

в результате проблем с FTP-соединением (в отличие от ошибок программирования со стороны вызывающего кода). В этот набор входят четыре исключения, перечисленные выше, а также

[`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error)

и

[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)

.

> **См. также**
>
> **Модуль [`netrc`](https://python-all.ru/3.1/library/netrc.html#module-netrc)**
>
> Синтаксический анализатор формата файла
>
> `.netrc`
>
> . Файл
>
> `.netrc`
>
> обычно используется FTP-клиентами для загрузки информации об аутентификации пользователя перед запросом к пользователю.
>
> Файл `Tools/scripts/ftpmirror.py` в дистрибутиве исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля `ftplib`. Его можно использовать как расширенный пример применения этого модуля.

## 20.11.1. Объекты FTP

Некоторые методы доступны в двух вариантах: один для работы с текстовыми файлами, другой для двоичных файлов. Они названы по имени используемой команды, за которым следует `lines` для текстовой версии или `binary` для двоичной версии.

Экземпляры [`FTP`](https://python-all.ru/3.1/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.1/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.1/library/ftplib.html#ftplib.FTP.transfercmd)

.

#### `FTP.retrlines(cmd, callback=None)`

Получает список файлов или каталогов в режиме передачи ASCII.

*cmd*

должна быть соответствующей командой

`RETR`

(см.

[`retrbinary()`](https://python-all.ru/3.1/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)`

Сохраняет файл в бинарном режиме передачи.

*cmd*

должна быть соответствующей командой

`STOR`

:

`"STOR filename"`

.

*file*

– это открытый

[*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object)

, который читается до EOF с помощью его метода

`read()`

блоками размера

*blocksize*

для предоставления сохраняемых данных. По умолчанию аргумент

*blocksize*

равен 8192.

*колбэк*

– необязательный вызываемый объект с одним параметром, который вызывается для каждого блока данных после его отправки.

#### `FTP.storlines(cmd, file, callback=None)`

Сохраняет файл в ASCII режиме передачи.

*cmd*

должна быть соответствующей командой

`STOR`

(см.

[`storbinary()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.storbinary)

). Строки читаются до EOF из открытого

[*файлового объекта*](https://python-all.ru/3.1/glossary.html#term-file-object)

*file*

с помощью его метода

`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.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*.

#### `FTP.ntransfercmd(cmd, rest=None)`

Подобно

[`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd)

, но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается

`None`

. Параметры

*cmd*

и

*rest*

означают то же самое, что и в

[`transfercmd()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.transfercmd)

.

#### `FTP.nlst(argument[, ...])`

Возвращает список имён файлов, полученный от команды

`NLST`

. Необязательный аргумент

*argument*

– это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде

`NLST`

.

#### `FTP.dir(argument[, ...])`

Формирует список каталога, возвращаемый командой

`LIST`

, выводя его в стандартный вывод. Необязательный аргумент

*argument*

– это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде

`LIST`

. Если последний аргумент является функцией, он используется как функция

*колбэк*

аналогично

[`retrlines()`](https://python-all.ru/3.1/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.1/library/ftplib.html#ftplib.error_perm)

при ошибках разрешения или

[`error_reply`](https://python-all.ru/3.1/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.1/library/ftplib.html#ftplib.FTP.close)

, который делает экземпляр

[`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP)

бесполезным для последующих вызовов (см. ниже).

#### `FTP.close()`

Закрывает соединение в одностороннем порядке. Не следует применять к уже закрытому соединению, например после успешного вызова

[`quit()`](https://python-all.ru/3.1/library/constants.html#quit)

. После этого вызова экземпляр

[`FTP`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP)

больше не следует использовать (после вызова

[`close()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.close)

или

[`quit()`](https://python-all.ru/3.1/library/constants.html#quit)

вы не сможете снова открыть соединение, вызвав другой метод

[`login()`](https://python-all.ru/3.1/library/ftplib.html#ftplib.FTP.login)

).