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