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

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

В этом модуле определен класс FTP и несколько связанных элементов. Класс FTP реализует клиентскую часть протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, такие как зеркалирование других серверов FTP. Он также используется модулем urllib.request для обработки 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=None, source_address=None)

Возвращает новый экземпляр класса FTP. При заданном параметре host вызывается метод connect(host). При заданном параметре user дополнительно вызывается метод login(user, passwd, acct), (где passwd и acct по умолчанию являются пустыми строками, если не указаны). Необязательный параметр timeout задает время ожидания в секундах для блокирующих операций, таких как попытка подключения (если он не указан, будет использоваться глобальное значение по умолчанию). source_address — кортеж из 2 элементов (host, port), определяющий адрес сокета, к которому он должен быть привязан перед подключением.

Класс FTP поддерживает оператор with, например:

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

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

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

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

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

Новое в версии 3.2.

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

Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

Устарело начиная с версии 3.6: keyfile и certfile устарели в пользу context. Используйте ssl.SSLContext.load_cert_chain() вместо них или позвольте ssl.create_default_context() выбрать доверенные сертификаты ЦС вашей системы.

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

>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

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-соединением (в отличие от ошибок программирования, допущенных вызывающим кодом). Это множество включает четыре перечисленных выше исключения, а также OSError.

21.13.1. Объекты FTP

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

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

FTP.set_debuglevel(level)

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

FTP.connect(host='', port=0, timeout=None, source_address=None)

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

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

FTP.getwelcome()

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

FTP.login(user='anonymous', passwd='', acct='')

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

FTP.abort()

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

FTP.sendcmd(cmd)

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

FTP.voidcmd(cmd)

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

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)

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

FTP.retrlines(cmd, callback=None)

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

FTP.set_pasv(val)

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

FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

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

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

FTP.storlines(cmd, fp, callback=None)

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

FTP.transfercmd(cmd, rest=None)

Инициализация передачи по подключению данных. Если передача активна, отправляет 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=None)

Аналогично transfercmd(), но возвращает кортеж из подключения данных и ожидаемого размера данных. Если ожидаемый размер не может быть вычислен, None будет возвращён как ожидаемый размер. cmd и rest означают то же, что и в transfercmd().

FTP.mlsd(path="", facts=[])

Выводит список каталога в стандартизированном формате, используя MLSD команду (RFC 3659). Если path опущен, предполагается текущий каталог. facts — это список строк, представляющих тип желаемой информации (например, ["type", "size", "perm"]). Возвращает генератор, возвращающий кортеж из двух элементов для каждого найденного файла в пути. Первый элемент — имя файла, второй — словарь, содержащий информацию об имени файла. Содержимое этого словаря может быть ограничено аргументом facts, но сервер не гарантирует возвращение всех запрошенных фактов.

Добавлен в версии 3.3.

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

Возвращает список имён файлов, как возвращается командой NLST. Необязательный аргумент argument представляет собой каталог для вывода (по умолчанию — текущий каталог сервера). Несколько аргументов могут быть использованы для передачи нестандартных параметров в команду NLST.

Примечание

Если ваш сервер поддерживает команду, mlsd() предлагает более удобный API.

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

Выводит список каталога, возвращаемый командой LIST, печатая его в стандартный вывод. Необязательный аргумент argument представляет собой каталог для вывода (по умолчанию — текущий каталог сервера). Несколько аргументов могут быть использованы для передачи нестандартных параметров в команду LIST . Если последним аргументом является функция, она используется как функция callback, как для retrlines(); по умолчанию выводятся в sys.stdout. Этот метод возвращает None.

Примечание

Если ваш сервер поддерживает команду, mlsd() предлагает более удобный API.

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

21.13.2. Объекты FTP_TLS

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

FTP_TLS.ssl_version

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

FTP_TLS.auth()

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

Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

FTP_TLS.ccc()

Возвращение управляющего канала обратно к текстовому формату. Это может быть полезно для использования брандмауэров, которые знают, как обращаться с NAT при использовании небезопасного FTP без открытия фиксированных портов.

Добавлен в версии 3.3.

FTP_TLS.prot_p()

Настройка защищённого канала передачи данных.

FTP_TLS.prot_c()

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