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

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

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

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

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # подключиться к хосту, порт по умолчанию
>>> ftp.login()                     # пользователь anonymous, пароль anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # перейти в каталог "debian"
>>> ftp.retrlines('LIST')           # список содержимого каталога
-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 является 2-кортежным (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).

Не рекомендуется, начиная с версии 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 и EOFError.

См.также

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

Объекты 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) для сокет, который должен быть привязан в качестве адреса источника перед подключением.

Raises an auditing event ftplib.connect with arguments self, 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)

Отправка простой команды строка на сервер и ответ возвращает строка.

Raises an auditing event ftplib.sendcmd with arguments self, cmd.

FTP.voidcmd(cmd)

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

Raises an auditing event ftplib.sendcmd with arguments self, cmd.

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

Извлечение файла в режиме двоичной передачи. cmd должна быть соответствующей командой RETR: 'RETR filename'. Функция callback вызывается для каждого принятого блока данных, причем один аргумент байтов дает блок данных. Необязательный аргумент 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 верен, иначе отключите пассивный режим. Пассивный режим включен по умолчанию.

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 до ASCII код 126. Таким образом, способ transfercmd() преобразует rest в строка, но проверка содержимого строка не выполняется. Если сервер не распознает команду REST, возникает исключение error_reply. Если это происходит, просто вызовите transfercmd() без аргумента rest.

FTP.ntransfercmd(cmd, rest=None)

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

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

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

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

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

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

Примечание

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

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

Создайте каталог в виде команды возвращенныйby 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 на сервере. При успехе размер файла возвращенныйas равен целому числу, в противном случае возвращается 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 и Указание имени сервера (см. ssl.HAS_SNI).

FTP_TLS.ccc()

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

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

FTP_TLS.prot_p()

Настройка безопасного подключения к данным.

FTP_TLS.prot_c()

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