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 — кортеж из двух элементов (host, port), представляющий адрес сокета для привязки перед подключением.

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

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
... # doctest: +SKIP
'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).

Вот пример сеанса с использованием класса 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.

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 — кортеж из двух элементов (host, port), представляющий адрес сокета для привязки перед подключением.

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

FTP.getwelcome()

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

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

Выполняет вход под указанным пользователем user. Параметры 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)

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

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

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

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

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

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

FTP.transfercmd(cmd, rest=None)

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

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

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