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.

Доступность: не Emscripten, не WASI.

Этот модуль не работает и не доступен на платформах WebAssembly wasm32-emscripten и wasm32-wasi. Более подробную информацию см. в Плаформах WebAssembly.

Вот пример сеанса с использованием модуля 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 — кортеж из двух элементов (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: Добавлен параметр source_address.

Изменено в версии 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: Добавлен параметр 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.

См. также

Module netrc: Парсер для формата файла .netrc. Файл .netrc обычно используется клиентами FTP для загрузки информации об аутентификации пользователя перед запросом.

END_OF_DOCUMENT_MARKER

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

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

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

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

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

FTP.abort(): Прервать процесс передачи файла. Использование этого метода не всегда работает, но стоит попробовать.

FTP.sendcmd(cmd)

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

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

FTP.voidcmd(cmd)

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

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

FTP.retrbinary(cmd, callback, blocksize=8192, rest=None): Получить файл в двоичном режиме передачи. cmd должна быть соответствующей RETR командой: 'RETR filename'. Функция callback вызывается для каждого блока полученных данных, принимая один аргумент 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 — это объект файла (открытый в двоичном режиме), который считывается до EOF с помощью его метода read() блоками размером blocksize для предоставления данных для хранения. Аргумент blocksize по умолчанию равен 8192. callback — это необязательная вызываемая функция с одним параметром, которая вызывается для каждого блока данных после его отправки. rest имеет то же значение, что и в методе transfercmd().

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

FTP.storlines(cmd, fp, callback=None): Сохранить файл в текстовом режиме. cmd должна быть соответствующей STOR командой (см. storbinary()). Строки считываются до EOF из объекта файла 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"]). Возвращает генератор объекта, возвращающий кортеж из двух элементов для каждого найденного файла в пути. Первый элемент — имя файла, второй — словарь, содержащий сведения о файле. Содержимое этого словаря может быть ограничено аргументом 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(): Настройка канала данных в текстовом формате.