ftplib — Клиент протокола FTP

Исходный код: Lib/ftplib.py

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

Вот пример сеанса, использующего модуль ftplib:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> 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 задает таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указан, используется глобальный таймаут по умолчанию).

Изменено в версии 2.6: Добавлен параметр timeout.

class ftplib.FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])

Подкласс FTP, который добавляет поддержку TLS к FTP, как описано в RFC 4217. Подключается к порту 21 по умолчанию, неявно обеспечивая безопасность соединения FTP-управления перед аутентификацией. Для обеспечения безопасности канала данных необходимо явно запросить его, вызвав метод prot_p(). Параметр context — объект ssl.SSLContext, который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну (возможно, долгоживущую) структуру. Для ознакомления с лучшими практиками обратитесь к разделу «Учетные соображения безопасности».

Параметры keyfile и certfile — это устаревшая альтернатива context. Они могут указывать на файлы закрытого ключа и цепочки сертификатов (соответственно) в формате PEM для SSL-соединения.

Введено в версии 2.7.

Изменено в версии 2.7.10: Добавлен параметр context.

Вот пример сеанса, использующего класс FTP_TLS:

>>> from ftplib import FTP_TLS
>>> ftps = FTP_TLS('ftp.python.org')
>>> ftps.login()           # login anonymously before securing control channel
>>> ftps.prot_p()          # switch to secure data connection
>>> ftps.retrlines('LIST') # list directory content securely
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

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

ftplib.all_errors

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

1. Объекты FTP

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

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

FTP.set_debuglevel(level)

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

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

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

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

Изменено в версии 2.6: Добавлен параметр timeout.

FTP.getwelcome()

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

FTP.login([user[, passwd[, acct]]])

Вход под указанным пользователем user. Параметры passwd и acct являются необязательными и по умолчанию равны пустой строке. Если пользователь user не указан, он устанавливается по умолчанию в 'anonymous'. Если user равен 'anonymous', то значение passwd по умолчанию равно 'anonymous@'. Эта функция должна вызываться только один раз для каждого экземпляра после установления соединения; ее не следует вызывать вообще, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после входа клиента. Параметр acct предоставляет «информацию об учёте»; мало систем её реализуют.

FTP.abort()

Прервать процесс передачи файла. Иногда это не срабатывает, но попробовать стоит.

FTP.sendcmd(command)

Отправить простую строку команды на сервер и вернуть строку ответа.

FTP.voidcmd(command)

Отправка простой команды на сервер и обработка ответа. Возвращает ничего, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). Иначе генерирует исключение error_reply.

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

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

FTP.retrlines(command[, callback])

Получение файла или списка каталогов в режиме ASCII-передачи. command должна быть соответствующей командой RETR (см. retrbinary()) или командой, такой как LIST, NLST или MLSD (обычно просто строка 'LIST'). LIST извлекает список файлов и информации о них. NLST извлекает список имён файлов. На некоторых серверах MLSD извлекает читаемый машиной список файлов и информации о них. Функция callback вызывается для каждой строки со строковым аргументом, содержащим строку с удалёнными завершающими CRLF. По умолчанию callback печатает строку в sys.stdout.

FTP.set_pasv(val)

Включить режим «пассивный» если val истинно, в противном случае отключить пассивный режим. (В Python 2.0 и ранее, пассивный режим был по умолчанию выключен; в Python 2.1 и позднее, он включен по умолчанию.)

FTP.storbinary(command, fp[, blocksize, callback, rest])

Сохранение файла в двоичном режиме передачи. command должно быть соответствующей STOR командой: "STOR filename". fp — это открытый объект файла, который читается до конца файла с помощью его read() метода блоками размером blocksize, чтобы предоставить данные для хранения. Аргумент blocksize по умолчанию равен 8192. callback — это необязаемая вызываемая функция с одним параметром, которая вызывается для каждого блока данных после его отправки. rest означает то же самое, что и в методе transfercmd().

Изменено в версии 2.1: добавлено значение по умолчанию для blocksize.

Изменено в версии 2.6: добавлен параметр callback.

Изменено в версии 2.7: добавлен параметр rest.

FTP.storlines(command, fp[, callback])

Сохранение файла в текстовом режиме передачи. command должна быть соответствующей STOR командой (см. storbinary()). Строки читаются до конца файла из открытого объекта файла fp с помощью его метода readline() для предоставления данных для хранения. callback — это необязаемая вызываемая функция с одним параметром, которая вызывается для каждой строки после ее отправки.

Изменено в версии 2.6: добавлен параметр callback.

FTP.transfercmd(cmd[, rest])

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

Если задан необязательный rest, на сервер отправляется команда REST, передавая rest в качестве аргумента. rest обычно представляет собой байтовый смещение в запрошенном файле, сообщая серверу о перезапуске отправки байтов файла с запрошенного смещения, пропуская начальные байты. Однако RFC 959 требует только, чтобы rest был строкой, содержащей символы в печатном диапазоне от ASCII-кода 33 до ASCII-кода 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, выводя его в стандартный вывод. Необязательный аргумент — это каталог для отображения (по умолчанию — текущий каталог сервера). Несколько аргументов могут быть использованы для передачи нестандартных параметров к команде 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()).

2. Объекты FTP_TLS

FTP_TLS класс наследуется от FTP, определяя эти дополнительные объекты:

FTP_TLS.ssl_version

Версия SSL для использования (по умолчанию ssl.PROTOCOL_SSLv23).

FTP_TLS.auth()

Настройка защищенного управляющего соединения с использованием TLS или SSL в зависимости от указанного в атрибуте ssl_version().

FTP_TLS.prot_p()

Настройка безопасного соединения данных.

FTP_TLS.prot_c()

Настройка соединения данных в текстовом формате.