Содержание страницы

`ftplib` – клиент протокола FTP¶ftplib – FTP protocol client

Этот модуль определяет класс FTP и несколько связанных с ним элементов. Класс FTP реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других FTP-серверов. Он также используется модулем urllib.request для обработки URL, использующих FTP. Для получения дополнительной информации о FTP (File Transfer Protocol) см. RFC 959.

Вот пример сеанса с использованием модуля ftplib:

>>> 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. Когда указан host, вызывается метод connect(host). Когда указан user, дополнительно вызывается метод login(user, passwd, acct) (где passwd и acct по умолчанию равны пустой строке, если не заданы). Необязательный параметр timeout задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальная настройка тайм-аута по умолчанию).

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

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

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

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

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

См. также

Модуль netrc: Парсер для формата файла .netrc. Файл .netrc обычно используется FTP-клиентами для загрузки данных аутентификации пользователя перед запросом у пользователя.

Файл Tools/scripts/ftpmirror.py в дистрибутиве исходного кода Python – это скрипт, который может зеркалировать FTP-сайты или их части с помощью модуля ftplib. Его можно использовать как расширенный пример применения этого модуля.

Объекты FTP¶FTP Objects

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

Экземпляры FTP имеют следующие методы:

FTP.set_debuglevel(level)¶: Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, 0, не даёт отладочного вывода. Значение 1 даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение 2 или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.

FTP.connect(host[, port[, timeout]])¶

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

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

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

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.

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

FTP.sendcmd(command)¶: Отправляет простую строку команды на сервер и возвращает строку ответа.

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

FTP.retrbinary(command, callback[, maxblocksize[, rest]])¶: Извлекает файл в двоичном режиме передачи. Параметр command должен содержать соответствующую команду RETR: 'RETR filename'. Функция колбэк вызывается для каждого полученного блока данных с одним строковым аргументом, представляющим блок данных. Необязательный аргумент maxblocksize задаёт максимальный размер блока для чтения из низкоуровневого сокета, созданного для фактической передачи (это также будет максимальным размером блоков данных, передаваемых в колбэк). Выбирается разумное значение по умолчанию. rest означает то же самое, что и в методе transfercmd().

FTP.retrlines(command[, callback])¶: Извлекает файл или список каталога в текстовом режиме передачи. Параметр command должен содержать соответствующую команду RETR (см. retrbinary()) или команду типа LIST, NLST или MLSD (обычно просто строка 'LIST'). Функция колбэк вызывается для каждой строки с удалёнными завершающими символами CRLF. Функция колбэк по умолчанию выводит строку в sys.stdout.

FTP.set_pasv(boolean)¶: Включает пассивный режим, если boolean истинно, в противном случае отключает пассивный режим. Пассивный режим включён по умолчанию.

FTP.storbinary(command, file[, blocksize, callback])¶: Сохраняет файл в двоичном режиме передачи. Параметр command должен содержать соответствующую команду STOR: "STOR filename". Параметр file – это открытый файловый объект, который читается до конца файла с помощью его метода read() блоками размера blocksize для предоставления сохраняемых данных. Аргумент blocksize по умолчанию равен 8192. колбэк – необязательный вызываемый объект с одним параметром, который вызывается для каждого отправленного блока данных.

FTP.storlines(command, file[, callback])¶: Сохраняет файл в текстовом режиме передачи. Параметр command должен содержать соответствующую команду STOR (см. storbinary()). Строки читаются до конца файла из открытого файлового объекта file с помощью его метода readline() для предоставления сохраняемых данных. колбэк – необязательный вызываемый объект с одним параметром, который вызывается для каждой отправленной строки.

FTP.transfercmd(cmd[, rest])¶

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

Если задан необязательный параметр rest, серверу отправляется команда REST с передачей rest в качестве аргумента. Обычно rest – это байтовое смещение в запрашиваемом файле; серверу указывается возобновить отправку байтов файла с указанного смещения, пропустив начальные байты. Однако обратите внимание, что RFC 959 требует только, чтобы rest был строкой, содержащей символы из печатного диапазона кодов ASCII от 33 до 126. Поэтому метод transfercmd() преобразует rest в строку, но проверка содержимого строки не выполняется. Если сервер не распознаёт команду REST, будет вызвано исключение error_reply. Если это происходит, просто вызовите transfercmd() без аргумента rest.

FTP.ntransfercmd(cmd[, rest])¶: Подобно transfercmd(), но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается None. Параметры cmd и rest означают то же самое, что и в transfercmd().

FTP.nlst(argument[, ...])¶: Возвращает список файлов, возвращаемый командой NLST. Необязательный аргумент – каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно указать несколько аргументов для передачи нестандартных параметров команде NLST .

FTP.dir(argument[, ...])¶: Формирует список каталога, возвращаемый командой LIST, выводя его в стандартный вывод. Необязательный аргумент argument – это каталог для вывода списка (по умолчанию – текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде LIST. Если последний аргумент является функцией, он используется как функция колбэк аналогично retrlines(); по умолчанию вывод осуществляется в sys.stdout. Этот метод возвращает None.

FTP.rename(fromname, toname)¶: Переименовывает файл fromname на сервере в toname.

FTP.delete(filename)¶: Удаляет файл с именем filename с сервера. В случае успеха возвращает текст ответа, в противном случае вызывает error_perm при ошибках разрешения или 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(), который делает экземпляр FTP бесполезным для последующих вызовов (см. ниже).

FTP.close()¶: Закрывает соединение в одностороннем порядке. Не следует применять к уже закрытому соединению, например после успешного вызова quit(). После этого вызова экземпляр FTP больше не следует использовать (после вызова close() или quit() вы не сможете снова открыть соединение, вызвав другой метод login()).

ftplib – клиент протокола FTP¶ftplib – FTP protocol client

Объекты FTP¶FTP Objects

`ftplib` – клиент протокола FTP¶ftplib – FTP protocol client