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

Объекты 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 — это кортеж из двух элементов (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 вызывается для каждой строки с строковым аргументом, содержащим строку с удалённым trailing CRLF. По умолчанию callback выводит строку в sys.stdout.

FTP.set_pasv(val): Включить «пассивный» режим, если val имеет значение true, иначе отключить пассивный режим. Пассивный режим включён по умолчанию.

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(): Настройка канала передачи данных в формате обычного текста.