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

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

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

По умолчанию используется кодировка UTF-8, следующая за RFC 2640.

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

>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> 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()
'221 Goodbye.'

Модуль определяет следующие элементы:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

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

Класс 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: Был добавлен параметр адрес_источника.

Изменено в версии 3.9: Если параметр timeout установлен в нулевое значение, то будет вызвана ошибка ValueError для предотвращения создания неблокирующего сокета. Был добавлен параметр encoding, и значение по умолчанию было изменено с Latin-1 на UTF-8, чтобы следовать RFC 2640.

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')

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

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

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

Изменено в версии 3.3: Был добавлен параметр адрес_источника.

Изменено в версии 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() выбрать для вас сертификаты доверенных центров сертификации системы.

Изменено в версии 3.9: Если параметр timeout установлен в нулевое значение, то будет вызвана ошибка ValueError для предотвращения создания неблокирующего сокета. Был добавлен параметр encoding, и значение по умолчанию было изменено с Latin-1 на UTF-8, чтобы следовать RFC 2640.

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

Вызывает auditing event ftplib.connect с аргументами self, host, port.

Изменено в версии 3.3: Был добавлен параметр адрес_источника.

FTP.getwelcome()

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

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

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

FTP.abort()

Прервать выполняющуюся передачу файла. Это не всегда срабатывает, но попробовать стоит.

FTP.sendcmd(cmd)

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

Вызывает auditing event ftplib.sendcmd с аргументами self, cmd.

FTP.voidcmd(cmd)

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

Вызывает auditing event ftplib.sendcmd с аргументами self, cmd.

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

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

FTP.retrlines(cmd, callback=None)

Получение списка файлов или каталогов в кодировке, указанной параметром encoding при инициализации. 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 - это file object (открытый в двоичном режиме), который считывается до EOF с помощью своего метода read() блоками размером blocksize для предоставления данных для хранения. Аргумент blocksize по умолчанию равен 8192. callback - это необязательный однопараметрический вызываемый параметр, который вызывается на каждом блоке данных после его отправки. rest означает то же самое, что и в методе transfercmd().

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

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

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

FTP.transfercmd(cmd, rest=None)

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

Если указано необязательное значение rest, на сервер отправляется команда REST, передающая rest в качестве аргумента. Обычно rest - это смещение байта в запрашиваемом файле, указывающее серверу начать отправку байтов файла с запрашиваемого смещения, пропуская начальные байты. Обратите внимание, что метод transfercmd() преобразует rest в строку с параметром encoding, указанным при инициализации, но никакой проверки содержимого строки не производится. Если сервер не распознает команду 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"]). Возвращает объект-генератор, дающий кортеж из двух элементов для каждого файла, найденного в path. Первый элемент - имя файла, второй - словарь, содержащий факты об имени файла. Содержание этого словаря может быть ограничено аргументом facts, но сервер не гарантированно вернет все запрошенные факты.

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

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

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

Примечание

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

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

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

Установите соединение для передачи данных открытым текстом.

http.client — Клиент протокола HTTP
poplib — Клиент протокола POP3
Вернуться на верх