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.

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы 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.'

Ссылка

Объекты FTP

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

Возвращает новый экземпляр класса FTP.

Параметры:

  • host (str) – Имя хоста для подключения. Если задано, то connect(host) неявно вызывается конструктором.

  • user (str) – The username to log in with (default: 'anonymous'). Если задано, то login(host, passwd, acct) неявно вызывается конструктором.

  • passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

  • timeout (float | None) – Таймаут в секундах для блокирующих операций, таких как connect() (по умолчанию: глобальная настройка таймаута по умолчанию).

  • source_address (tuple | None) – A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

  • encoding (str) – The encoding for directories and filenames (default: 'utf-8').

Класс 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.

Несколько методов FTP доступны в двух вариантах: один для работы с текстовыми файлами, другой - с бинарными. Методы называются по имени команды, которая используется, после чего следует lines для текстовой версии или binary для бинарной версии.

У экземпляров FTP есть следующие методы:

set_debuglevel(level)

Установите уровень отладки экземпляра в виде int. Это управляет количеством выводимых отладочных данных. Уровнями отладки являются:

  • 0 (по умолчанию): Не выводить отладку.

  • 1: Выводит умеренное количество отладочной информации, обычно одну строку на запрос.

  • 2 или выше: Вывод максимального количества отладочных данных, регистрируя каждую строку, отправленную и полученную по управляющему соединению.

connect(host='', port=0, timeout=None, source_address=None)

Подключение к указанному хосту и порту. Эта функция должна вызываться только один раз для каждого экземпляра; ее не следует вызывать, если при создании экземпляра FTP был задан аргумент host. Все остальные методы FTP могут быть вызваны только после успешного установления соединения.

Параметры:

  • host (str) – Хост, к которому необходимо подключиться.

  • port (int) – TCP-порт для подключения (по умолчанию: 21, как указано в спецификации протокола FTP). Редко требуется указывать другой номер порта.

  • timeout (float | None) – Таймаут в секундах для попытки соединения (по умолчанию: глобальный таймаут по умолчанию).

  • source_address (tuple | None) – A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

Поднимает auditing event ftplib.connect с аргументами self, host, port.

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

getwelcome()

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

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

Вход на подключенный FTP-сервер. Эта функция должна вызываться только один раз для каждого экземпляра, после установления соединения; ее не следует вызывать, если аргументы host и user были заданы при создании экземпляра FTP. Большинство FTP-команд разрешается выполнять только после того, как клиент вошел в систему.

Параметры:

  • user (str) – The username to log in with (default: 'anonymous').

  • passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

abort()

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

sendcmd(cmd)

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

Поднимает auditing event ftplib.sendcmd с аргументами self, cmd.

voidcmd(cmd)

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

Поднимает auditing event ftplib.sendcmd с аргументами self, cmd.

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

Получение файла в режиме двоичной передачи.

Параметры:

  • cmd (str) – Соответствующая команда STOR: "STOR filename".

  • callback (callable) – Вызываемый модуль с одним параметром, который вызывается для каждого полученного блока данных, а его единственным аргументом являются данные в виде bytes.

  • blocksize (int) – Максимальный размер чанка для чтения на низкоуровневом объекте socket, созданном для выполнения фактической передачи. Это также соответствует наибольшему размеру данных, которые будут переданы в callback. По умолчанию 8192.

  • rest (int) – Команда REST, которая будет отправлена на сервер. Параметр rest метода transfercmd() см. в документации.

retrlines(cmd, callback=None)

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

set_pasv(val)

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

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

Сохранение файла в режиме двоичной передачи.

Параметры:

  • cmd (str) – Соответствующая команда STOR: "STOR filename".

  • fp (file object) – Файловый объект (открытый в двоичном режиме), который считывается до EOF, используя свой метод read() блоками размера blocksize для предоставления данных для хранения.

  • blocksize (int) – Размер блока чтения. По умолчанию 8192.

  • callback (callable) – Вызываемый модуль с одним параметром, который вызывается для каждого отправленного блока данных, а его единственным аргументом являются данные в виде bytes.

  • rest (int) – Команда REST, которая будет отправлена на сервер. Параметр rest метода transfercmd() см. в документации.

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

storlines(cmd, fp, callback=None)

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

transfercmd(cmd, rest=None)

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

Если указано необязательное значение rest, на сервер отправляется команда REST, передающая rest в качестве аргумента. Обычно rest - это смещение байта в запрашиваемом файле, указывающее серверу начать отправку байтов файла с запрашиваемого смещения, пропуская начальные байты. Обратите внимание, что метод transfercmd() преобразует rest в строку с параметром encoding, указанным при инициализации, но никакой проверки содержимого строки не производится. Если сервер не распознает команду REST, будет вызвано исключение error_reply. В этом случае просто вызовите transfercmd() без аргумента rest.

ntransfercmd(cmd, rest=None)

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

mlsd(path='', facts=[])

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

Added in version 3.3.

nlst(argument[, ...])

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

Примечание

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

dir(argument[, ...])

Создает список каталогов, возвращаемый командой LIST, и выводит его на стандартный вывод. Необязательный аргумент argument - это каталог, который нужно перечислить (по умолчанию это текущий каталог сервера). Несколько аргументов могут быть использованы для передачи нестандартных опций команде LIST. Если последний аргумент является функцией, он используется в качестве обратной функции, как для retrlines(); по умолчанию печатается sys.stdout. Этот метод возвращает None.

Примечание

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

rename(fromname, toname)

Переименуйте файл fromname на сервере в toname.

delete(filename)

Удаляет файл с именем filename с сервера. В случае успеха возвращает текст ответа, в противном случае поднимает error_perm при ошибках разрешения или error_reply при других ошибках.

cwd(pathname)

Установите текущий каталог на сервере.

mkd(pathname)

Создайте новый каталог на сервере.

pwd()

Возвращает имя пути к текущему каталогу на сервере.

rmd(dirname)

Удалите каталог с именем dirname на сервере.

size(filename)

Запрос размера файла с именем filename на сервере. В случае успеха размер файла возвращается в виде целого числа, в противном случае возвращается None. Обратите внимание, что команда SIZE не является стандартной, но поддерживается многими распространенными реализациями серверов.

quit()

Отправьте на сервер команду QUIT и закройте соединение. Это «вежливый» способ закрыть соединение, но он может вызвать исключение, если сервер ответит ошибкой на команду QUIT. Это подразумевает вызов метода close(), который делает экземпляр FTP бесполезным для последующих вызовов (см. ниже).

close()

Закрыть соединение в одностороннем порядке. Это не должно применяться к уже закрытому соединению, например после успешного вызова quit(). После этого вызова экземпляр FTP больше не должен использоваться (после вызова close() или quit() вы не сможете снова открыть соединение, выпустив другой метод login()).

Объекты FTP_TLS

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

Подкласс FTP, который добавляет поддержку TLS в FTP, как описано в RFC 4217. Подключение к порту 21, неявно защищающее управляющее соединение FTP до аутентификации.

Примечание

Пользователь должен явно защитить соединение для передачи данных, вызвав метод prot_p().

Параметры:

  • host (str) – Имя хоста для подключения. Если задано, то connect(host) неявно вызывается конструктором.

  • user (str) – The username to log in with (default: 'anonymous'). Если задано, то login(host, passwd, acct) неявно вызывается конструктором.

  • passwd (str) – The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) – Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

  • context (ssl.SSLContext) – Объект контекста SSL, позволяющий объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую, потенциально долгоживущую структуру. Пожалуйста, прочитайте Соображения безопасности о лучших практиках.

  • timeout (float | None) – Таймаут в секундах для блокирующих операций, таких как connect() (по умолчанию: глобальная настройка таймаута по умолчанию).

  • source_address (tuple | None) – A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

  • encoding (str) – The encoding for directories and filenames (default: 'utf-8').

Added in version 3.2.

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

Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Указание имени сервера (см. ssl.HAS_SNI).

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

Изменено в версии 3.12: Устаревшие параметры keyfile и certfile были удалены.

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

Класс FTP_TLS наследуется от FTP, определяя эти дополнительные методы и атрибуты:

ssl_version

Версия SSL, которую следует использовать (по умолчанию ssl.PROTOCOL_SSLv23).

auth()

Установите безопасное управляющее соединение, используя TLS или SSL, в зависимости от того, что указано в атрибуте ssl_version.

Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Указание имени сервера (см. ssl.HAS_SNI).

ccc()

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

Added in version 3.3.

prot_p()

Настройте безопасное соединение для передачи данных.

prot_c()

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

Переменные модуля

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-клиентами для загрузки информации об аутентификации пользователя перед запросом.