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.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.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()
... 
'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() выбрать доверенные сертификаты CA системы.

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

Объекты 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 разрешены только после входа клиента. Параметр acct содержит «информацию об учёте»; немногие системы её реализуют.

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)

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

FTP.set_pasv(val)

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

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)

Запись файла в текстовом режиме передачи. 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. Необязательный аргумент — каталог для вывода (по умолчанию — текущий каталог сервера). Несколько аргументов могут быть использованы для передачи нестандартных параметров к команде NLST.

Примечание

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

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

Генерирует список каталога, возвращаемый командой LIST, выводя его на стандартный вывод. Необязательный аргумент — каталог для вывода (по умолчанию — текущий каталог сервера). Несколько аргументов могут быть использованы для передачи нестандартных параметров к команде 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()).

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

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