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.

Вот пример сеанса с использованием модуля 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 разрешены только после входа клиента.

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 истинно, иначе отключить пассивный режим. Пассивный режим включен по умолчанию.

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.

END_OF_DOCUMENT_MARKER

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(): Устанавливает открытое соединение для передачи данных.