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

---

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

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

Вот пример сеанса с использованием модуля `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()
```

Модуль определяет следующие элементы:

#### `[ftplib.FTP]class ftplib.FTP([host[, user[, passwd[, acct[, timeout]]]]])`

Возвращает новый экземпляр класса [`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP). Когда указан *host*, вызывается метод `connect(host)`. Когда указан *user*, дополнительно вызывается метод `login(user, passwd, acct)` (где *passwd* и *acct* по умолчанию равны пустой строке, если не заданы). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).

#### `[ftplib.FTP.all_errors]all_errors`

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

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

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

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

и

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

.

#### `[ftplib.FTP.error_reply]exception error_reply`

Исключение, возникающее при получении неожиданного ответа от сервера.

#### `[ftplib.error_temp]exception ftplib.error_temp`

Исключение возбуждается при получении кода ошибки в диапазоне 400–499.

#### `[ftplib.error_perm]exception ftplib.error_perm`

Исключение возбуждается при получении кода ошибки в диапазоне 500–599.

#### `[ftplib.error_proto]exception ftplib.error_proto`

Исключение возбуждается, когда от сервера получен ответ, который не начинается с цифры в диапазоне 1–5.

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

## Объекты FTP

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

Экземпляры [`FTP`](https://python-all.ru/3.0/library/ftplib.html#ftplib.FTP) имеют следующие методы:

#### `[ftplib.FTP.set_debuglevel]FTP.set_debuglevel(level)`

Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию,

`0`

, не даёт отладочного вывода. Значение

`1`

даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение

`2`

или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.

#### `[ftplib.FTP.connect]FTP.connect(host[, port[, timeout]])`

Подключается к указанному хосту и порту. Номер порта по умолчанию – `21`, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Эту функцию следует вызывать только один раз для каждого экземпляра; её не следует вызывать вообще, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения.

Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использована глобальная настройка тайм-аута по умолчанию.

#### `[ftplib.FTP.getwelcome]FTP.getwelcome()`

Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)

#### `[ftplib.FTP.login]FTP.login([user[, passwd[, acct]]])`

Log in as the given

*user*

. The

*passwd*

and

*acct*

parameters are optional and default to the empty string. If no

*user*

is specified, it defaults to

`'anonymous'`

. If

*user*

is

`'anonymous'`

, the default

*passwd*

is

`'anonymous@'`

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

#### `[ftplib.FTP.abort]FTP.abort()`

Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.

#### `[ftplib.FTP.sendcmd]FTP.sendcmd(command)`

Отправляет простую строку команды на сервер и возвращает строку ответа.

#### `[ftplib.FTP.voidcmd]FTP.voidcmd(command)`

Отправляет простую командную строку серверу и обрабатывает ответ. Ничего не возвращает, если получен код ответа в диапазоне 200–299. В противном случае возбуждает исключение.

#### `[ftplib.FTP.retrbinary]FTP.retrbinary(command, callback[, maxblocksize[, rest]])`

Извлекает файл в двоичном режиме передачи. Параметр

*command*

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

`RETR`

:

`'RETR filename'`

. Функция

*колбэк*

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

*maxblocksize*

задаёт максимальный размер блока для чтения из низкоуровневого сокета, созданного для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в

*колбэк*

). Выбирается разумное значение по умолчанию.

*rest*

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

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

.

#### `[ftplib.FTP.retrlines]FTP.retrlines(command[, callback])`

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

*command*

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

`RETR`

(см.

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

) или команду типа

`LIST`

,

`NLST`

или

`MLSD`

(обычно просто строка

`'LIST'`

). Функция

*колбэк*

вызывается для каждой строки с удалёнными завершающими символами CRLF. Функция

*колбэк*

по умолчанию выводит строку в

`sys.stdout`

.

#### `[ftplib.FTP.set_pasv]FTP.set_pasv(boolean)`

Включает пассивный режим, если

*boolean*

истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию.

#### `[ftplib.FTP.storbinary]FTP.storbinary(command, file[, blocksize, callback])`

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

*command*

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

`STOR`

:

`"STOR filename"`

. Параметр

*file*

– это открытый файловый объект, который читается до конца файла с помощью его метода

`read()`

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

*blocksize*

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

*blocksize*

по умолчанию равен 8192.

*колбэк*

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

#### `[ftplib.FTP.storlines]FTP.storlines(command, file[, callback])`

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

*command*

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

`STOR`

(см.

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

). Строки читаются до конца файла из открытого файлового объекта

*file*

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

`readline()`

для предоставления сохраняемых данных.

*колбэк*

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

#### `[ftplib.FTP.transfercmd]FTP.transfercmd(cmd[, rest])`

Инициирует передачу по соединению данных. Если передача активная, отправляется команда `EPRT` или `PORT` и команда передачи, указанная параметром *cmd*, и принимается соединение. Если сервер пассивный, отправляется команда `EPSV` или `PASV`, выполняется подключение к нему и запускается команда передачи. В любом случае возвращается сокет для соединения.

Если задан необязательный параметр *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*.

#### `[ftplib.FTP.ntransfercmd]FTP.ntransfercmd(cmd[, rest])`

Подобно

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

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

`None`

. Параметры

*cmd*

и

*rest*

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

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

.

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

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

`NLST`

. Необязательный

*аргумент*

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

`NLST`

.

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

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

`LIST`

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

*argument*

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

`LIST`

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

*колбэк*

аналогично

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

; по умолчанию вывод осуществляется в

`sys.stdout`

. Этот метод возвращает

`None`

.

#### `[ftplib.FTP.rename]FTP.rename(fromname, toname)`

Переименовывает файл

*fromname*

на сервере в

*toname*

.

#### `[ftplib.FTP.delete]FTP.delete(filename)`

Удаляет файл с именем

*filename*

с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает

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

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

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

при других ошибках.

#### `[ftplib.FTP.cwd]FTP.cwd(pathname)`

Устанавливает текущий каталог на сервере.

#### `[ftplib.FTP.mkd]FTP.mkd(pathname)`

Создаёт новый каталог на сервере.

#### `[ftplib.FTP.pwd]FTP.pwd()`

Возвращает путь к текущему каталогу на сервере.

#### `[ftplib.FTP.rmd]FTP.rmd(dirname)`

Удаляет каталог с именем

*dirname*

на сервере.

#### `[ftplib.FTP.size]FTP.size(filename)`

Запрос размера файла с именем

*filename*

на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается

`None`

. Обратите внимание, что команда

`SIZE`

не стандартизирована, но поддерживается многими распространёнными реализациями серверов.

#### `[ftplib.FTP.quit]FTP.quit()`

Отправляет команду

`QUIT`

серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но может вызвать исключение, если сервер отвечает ошибкой на команду

`QUIT`

. Это подразумевает вызов метода

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

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

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

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

#### `[ftplib.FTP.close]FTP.close()`

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

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

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

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

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

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

или

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

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

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

).