import ftplib ftp = ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')
host=''
- хост FTP-сервера, user=''
- имя пользователя для доступа на FTP-сервер,passwd=''
- пароль пользователя для доступа на FTP-сервер,acct=''
- информация об аккаунте,timeout=None
- тайм-аут в секундах для попытки подключения к FTP,source_address=None
- привязывает сокет к исходному адресу,encoding='utf-8'
- кодировка FTP-сервера.Класс ftplib.FTP()
модуля ftplib
возвращает новый экземпляр класса FTP()
.
Когда указан хост host
, то выполняется вызов метода FTP.connect(host)
.
Когда указан пользователь user
, то дополнительно выполняется вызов метода FTP.login(user, passwd, acct)
, где passwd
и acct
по умолчанию используют пустую строку, если они не заданы.
Необязательный аргумент timeout
указывает тайм-аут в секундах для блокировки операций, таких как попытка подключения (если он не указан, будет использоваться глобальная настройка тайм-аута по умолчанию).
Аргумент source_address
- это двойной кортеж (host, port)
для привязки сокета к исходному адресу перед подключением.
Аргумент encoding
указывает кодировку для каталогов и имен файлов FTP-сервера.
Класс ftplib.FTP
поддерживает оператор with
, например:
>>> from ftplib import FTP >>> with FTP("ftp1.at.proftpd.org") as ftp: ... ftp.login() ... ftp.dir() # '230 Anonymous access granted, restrictions apply' # -rw-rw-r-- 1 ftp ftp 451 Jul 1 2005 README.MIRRORS # drwxrwxr-x 3 ftp ftp 4096 Jul 1 2005 devel # drwxrwxr-x 3 ftp ftp 4096 Dec 2 2010 distrib # drwxrwxr-x 4 ftp ftp 4096 Jul 1 2005 historic
Изменено в Python 3.9: если аргумент timeout=0
, то он вызовет ошибку ValueError
, чтобы предотвратить создание неблокирующего сокета. Был добавлен параметр encoding
, а значение по умолчанию было изменено с Latin-1
на UTF-8
в соответствии с RFC 2640.
Несколько методов доступны в двух вариантах: один для обработки текстовых файлов и другой для двоичных файлов. Их имена состоят из выполняемой команды, за которой следуют
...lines
для текстовой версии или...binary
файлы для двоичной версии.
FTP.set_debuglevel()
устанавливает уровень отладки,FTP.connect()
подключается к заданному host
и port
,FTP.getwelcome()
возвращает приветственное сообщение,FTP.login()
входит в систему как указанный пользователь user
,FTP.abort()
прерывает текущую передачу файла,FTP.sendcmd()
отправляет строку с командой cmd
,FTP.voidcmd()
отправляет команду и обрабатывает ответ,FTP.retrbinary()
получает файл в двоичном режиме передачи,FTP.retrlines()
получает список файлов или каталогов,FTP.set_pasv()
включает "пассивный" режим,FTP.storbinary()
сохраняет файл в двоичном режиме,FTP.storlines()
сохраняет файл в построчном режиме,FTP.transfercmd()
инициирует передачу через соединение,FTP.ntransfercmd()
возвращает кортеж с подключением и ожидаемый размер данных,FTP.mlsd()
возвращает список каталогов как объекта-генератора,FTP.nlst()
возвращает список имен файлов,FTP.dir()
возвращает список каталогов,FTP.rename()
переименовывает файл,FTP.delete()
удаляет файл,FTP.cwd()
устанавливает текущий каталог,FTP.mkd()
создает новый каталог,FTP.pwd()
возвращает путь к текущему каталогу,FTP.rmd()
удаляет каталог,FTP.size()
запрашивает размер файла,FTP.quit()
закрывает соединение,FTP.close()
закрывает соединение в одностороннем порядке.ftplib.FTP()
.FTP.set_debuglevel(level)
:Метод FTP.set_debuglevel()
устанавливает уровень отладки экземпляра. Он контролирует количество напечатанного отладочного вывода.
Значение по умолчанию, 0, не выводит отладочный вывод. Значение 1 дает умеренный объем отладочной информации, как правило, одну строку на запрос. Значение 2 или выше создает максимальный объем отладочной информации, регистрируя каждую строку, отправленную и полученную по управляющему соединению.
FTP.connect(host='', port=0, timeout=None, source_address=None)
:Метод FTP.connect()
подключается к заданному host
и port
. Номер порта по умолчанию - 21, как указано в спецификации протокола FTP. Редко требуется указывать другой номер порта. Этот метод следует вызывать только один раз для каждого экземпляра.
Метод FTP.connect()
вообще не следует вызывать, если хост host
был задан при создании экземпляра. Все остальные методы можно использовать только после установления соединения.
Необязательный аргумент timeout
указывает время ожидания в секундах для попытки подключения. Если тайм-аут не указан, то будет использоваться глобальная настройка тайм-аута по умолчанию.
Аргумент source_address
- это двойной кортеж (host, port)
для привязки сокета к исходному адресу перед подключением.
Вызывает событие аудита ftplib.connect
с аргументами self
, host
, port
.
FTP.getwelcome()
:Метод FTP.getwelcome()
возвращает приветственное сообщение, отправленное сервером в ответ на начальное соединение.
Это сообщение иногда содержит заявления об отказе от ответственности или справочную информацию, которая может иметь отношение к пользователю.
FTP.login(user='anonymous', passwd='', acct='')
:Метод FTP.login()
входит в систему как указанный пользователь user
.
Аргументы passwd
и acct
являются необязательными и по умолчанию содержат пустую строку. Если пользователь user
не указан, то по умолчанию используется 'anonymous'
. Если пользователь является 'anonymous'
, то пароль по умолчанию - 'anonymous@'
.
Метод FTP.login()
следует вызывать только один раз для каждого экземпляра после установления соединения. Метод вообще не следует вызывать, если хост и пользователь были заданы при создании экземпляра. Большинство команд FTP разрешены только после того, как клиент вошел в систему.
Аргумент acct
предоставляет информацию об аккаунте, если FTP-сервер реализуют это.
FTP.abort()
:Метод FTP.abort()
прерывает текущую передачу файла. Использование этого метода не всегда работает, но стоит попробовать.
FTP.sendcmd(cmd)
:Метод FTP.sendcmd()
отправляет простую строку с командой cmd
на сервер и возвращает строку с ответом.
Вызывает [событие аудитаsys.audit ftplib.sendcmd
с аргументами self
, cmd
.
FTP.voidcmd(cmd)
:Метод FTP.voidcmd()
отправляет простую строку с командой cmd
на сервер и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае возникает исключение ftplib.error_reply
.
Вызывает [событие аудитаsys.audit ftplib.sendcmd
с аргументами self
, cmd
.
FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
:Метод FTP.retrbinary()
получает файл в двоичном режиме передачи. Аргумент cmd
должен быть соответствующей командой RETR
: RETR имя файла
.
Аргумент callback
- функция обратного вызова, которая вызывается для каждого полученного блока данных с одним аргументом bytes
, задающим блок данных.
Необязательный аргумент blocksize
указывает максимальный размер фрагмента для чтения в низкоуровневом объекте сокета, созданном для фактической передачи (который также будет наибольшим размером блоков данных, передаваемых в обратный вызов). Выбирается разумное значение по умолчанию.
Аргумент rest
означает то же самое, что и в методе FTP.transfercmd()
.
FTP.retrlines(cmd, callback=None)
:Метод FTP.retrlines()
получает список файлов или каталогов в кодировке, заданной аргументом encoding
при инициализации.
Аргумент cmd
должен быть соответствующей командой RETR
(смотрите описание FTP.retrbinary()
) или такой командой, как LIST
или NLST
(обычно это просто строка 'LIST'
).
LIST
извлекает список файлов и информацию об этих файлах. NLST
извлекает список имен файлов. Аргумент callback
- функция обратного вызова которая вызывается для каждой строки с аргументом, содержащим эту строку с удаленным конечным CRLF
. Обратный вызов по умолчанию печатает строку в sys.stdout
.
FTP.set_pasv(val)
:Метод FTP.set_pasv()
включает "пассивный" режим, если val=True
, в противном случае отключает пассивный режим.
Пассивный режим включен по умолчанию
FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)
:Метод FTP.storbinary()
сохраняет файл в двоичном режиме передачи. Аргумент cmd
должен быть соответствующей командой STOR
: имя файла STOR
.
Аргумент fp
- это файловый объект (открытый в двоичном режиме), который считывается до завершения EOF
с использованием метода file.read()
в блоках размером blocksize
для сохранения. Аргумент blocksize
по умолчанию равен 8192.
Аргумент callback
- это необязательная функция обратного вызова, которая вызывается для каждого блока данных blocksize
после его отправки.
Аргумент rest
означает то же самое, что и в методе FTP.transfercmd()
.
FTP.storlines(cmd, fp, callback=None)
:Метод FTP.storlines()
сохраняет файл в построчном режиме. Аргумент cmd
должен быть соответствующей командой STOR
(смотрите описание FTP.storbinary()
).
Строки считываются до EOF
из файлового объекта fp
(открытого в двоичном режиме) с использованием его метода file.readline()
для сохранения.
Аргумент callback
- это необязательная функция обратного вызова, которая вызывается для каждой строки после её отправки.
FTP.transfercmd(cmd, rest=None)
:Метод FTP.transfercmd()
инициирует передачу через соединение для передачи данных. Если передача активна, то отправляет команду EPRT
или PORT
и команду передачи, указанную в cmd
, и принимает соединение. Если сервер пассивен, то отправляет команду EPSV
или PASV
, подключается к нему и запускает команду передачи. В любом случае возвращает сокет для соединения.
Если задан необязательный аргумент rest
, то на сервер отправляется команда REST
, передающая значение, указанное в rest
. Аргумент rest
обычно представляет собой смещение в байтах в запрошенном файле, сообщая серверу о необходимости перезапустить отправку байтов файла с запрошенным смещением, пропуская начальные байты.
Обратите внимание, что метод FTP.transfercmd()
преобразует rest
в строку с кодировкой, указанной при инициализации, но проверка содержимого строки не выполняется. Если сервер не распознает команду REST
, то будет возбуждено исключение исключение ftplib.error_reply
. Если это произойдет, то просто вызовите FTP.transfercmd()
без остаточного аргумента..
FTP.ntransfercmd(cmd, rest=None)
:Метод FTP.ntransfercmd()
делает то-же самое, что и FTP.transfercmd()
, но возвращает кортеж подключения к данным и ожидаемый размер данных. Если ожидаемый размер не может быть вычислен, то в качестве ожидаемого размера будет возвращен None
.
Аргументы cmd
и rest
означают то же самое, что и в FTP.transfercmd()
.
FTP.mlsd(path='', facts=[])
:Метод FTP.mlsd()
возвращает список каталогов как объекта-генератора в запрошенном формате facts
с помощью команды MLSD
(RFC 3659). Если путь path
не указан, то предполагается текущий каталог. Аргумент facts
- это список строк, представляющих тип желаемой информации (например, ["type", "size", "perm"]
).
Возвращает объекта-генератора, дающего кортеж из двух элементов для каждого файла, найденного в path
. Первый элемент - это имя файла, второй - словарь, содержащий facts
об имени файла. Содержание этого словаря может быть ограничено аргументом facts
, но сервер не гарантирует возврат всех запрошенных полей, указанных в facts
.
FTP.nlst(argument[, ...])
:Метод FTP.nlst()
возвращает список имен файлов, возвращаемый командой NLST
. Необязательный аргумент argument
- это каталог для списка (по умолчанию это текущий каталог сервера).
Можно использовать несколько аргументов для передачи нестандартных параметров команде NLST
.
Примечание. Если FTP-сервер поддерживает эту команду, то метод
FTP.mlsd()
предлагает лучший API.
FTP.dir(argument[, ...])
:Метод FTP.dir()
возвращает список каталогов, возвращенный командой LIST
, и печатает его в стандартный вывод. Необязательный аргумент argument
- это каталог для списка (по умолчанию это текущий каталог сервера).
Для передачи нестандартных параметров команде LIST
можно использовать несколько аргументов. Если последний аргумент является функцией, то он используется как функция обратного вызова, как и для метода FTP.retrlines()
. По умолчанию печатает в sys.stdout
.
Этот метод возвращает None
.
Примечание. Если FTP-сервер поддерживает эту команду, то метод
FTP.mlsd()
предлагает лучший API.
FTP.rename(fromname, toname)
:Метод FTP.rename()
переименовывает файл fromname
на FTP-сервере в toname
.
FTP.delete(filename)
:Метод FTP.delete()
удаляет файл с именем filename
с FTP-сервера. В случае успеха возвращает текст ответа, в противном случае поднимает ftplib.error_perm
при ошибках разрешения или ftplib.error_reply
при других ошибках.
FTP.cwd(pathname)
:Метод FTP.cwd()
устанавливает pathname
как текущий каталог на FTP-сервере.
FTP.mkd(pathname)
:Метод FTP.mkd()
создает новый каталог pathname
на FTP-сервере.
FTP.pwd()
:Метод FTP.pwd()
возвращает путь к текущему каталогу на FTP-сервере.
FTP.rmd(dirname)
:Метод FTP.rmd()
удаляет каталог с именем dirname
на FTP-сервере.
FTP.size(filename)
:Метод FTP.size()
запрашивает размер файла с именем filename
на FTP-сервере. В случае успеха, размер файла возвращается как целое число, в противном случае возвращается None
.
Обратите внимание, что команда SIZE
не стандартизирована, но поддерживается многими распространенными реализациями серверов.
FTP.quit()
:Метод FTP.quit()
отправляет на FTP-сервер команду QUIT
и закрывает соединение. Это "вежливый" способ закрыть соединение, но он может вызвать исключение, если сервер ответит ошибкой на команду QUIT
.
Метод FTP.quit()
подразумевает вызов метода FTP.close()
, который делает экземпляр FTP
бесполезным для последующих вызовов.
FTP.close()
:Метод FTP.close()
закрывает соединение в одностороннем порядке. Метод не должен применяться к уже закрытому соединению, например, после успешного вызова FTP.quit()
.
После этого вызова, экземпляр FTP
больше не должен использоваться (после вызова FTP.close()
или FTP.quit()
нельзя повторно открыть соединение, выполнив другой метод FTP.login()
.
ftplib.FTP
.>>> from ftplib import FTP # подключаемся к хосту, порт по умолчанию >>> ftp = FTP('ftp.us.debian.org') # пользователь `anonymous`, пароль `anonymous@` # (по умолчанию) >>> ftp.login() # '230 Login successful.' # выбираем каталог "debian" >>> ftp.cwd('debian') # '250 Directory successfully changed.' # список содержимого каталога >>> ftp.retrlines('LIST') # -rw-r--r-- 1 4024 4024 1328 Sep 10 10:42 README # ... # -rw-r--r-- 1 4024 4024 254664 Dec 10 08:25 extrafiles # drwxr-xr-x 3 4024 4024 4096 Dec 10 08:18 indices # -rw-r--r-- 1 4024 4024 17037473 Dec 10 02:35 ls-lR.gz # drwxr-xr-x 6 4024 4024 90 Oct 05 17:09 pool # drwxr-xr-x 4 4024 4024 67 Nov 17 2008 project # drwxr-xr-x 3 4024 4024 77 Oct 10 2012 tools # drwxr-xr-x 26 4024 4024 4096 Aug 14 2021 zzz-dists # '226 Directory send OK.' # сохраняем файл 'README' на диск >>> with open('README', 'wb') as fp: ... ftp.retrbinary('RETR README', fp.write) # '226 Transfer complete.' # отключаемся от FTP >>> ftp.quit() # '221 Goodbye.'