Сообщить об ошибке.

Класс FTP() модуля ftplib в Python.

Синтаксис:

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.

Объект FTP имеет следующие методы:

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


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.'