ftplib — Клиент протокола FTP

Исходный код: Lib/ftplib.py

В этом модуле определен класс FTP и несколько связанных элементов. Класс FTP реализует клиентскую сторону протокола FTP. Его можно использовать для написания программ на Python, выполняющих различные автоматизированные задачи FTP, например, создание зеркал других серверов FTP. Он также используется модулем urllib.request для обработки URL-адресов, использующих FTP. Дополнительную информацию о протоколе FTP (File Transfer Protocol) см. в RFC 959.

Вот пример сеанса, использующего модуль ftplib:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org')     # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
>>> 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()

В модуле определены следующие элементы:

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None)

Возвращает новый экземпляр класса FTP. При указании параметра host вызывается метод connect(host). При указании параметра user дополнительно вызывается метод login(user, passwd, acct) (где passwd и acct по умолчанию являются пустыми строками, если не указаны). Необязательный параметр timeout задает время ожидания в секундах для блокирующих операций, таких как попытка подключения (если он не указан, используется глобальное значение по умолчанию). Параметр source_address представляет собой кортеж из 2 элементов (host, port) для привязки сокета в качестве адреса источника перед подключением.

Класс 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.

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)

Подкласс 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): Получить файл или список каталогов в режиме ASCII передачи. 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): Сохранить файл в ASCII режиме передачи. cmd должна быть соответствующей STOR командой (см. storbinary()). Строки считываются до EOF из объекта файла fp (открытого в бинарном режиме) с помощью метода readline() для предоставления данных для сохранения. callback — необязательная вызываемая функция с одним параметром, которая вызывается для каждой строки после её отправки.

FTP.transfercmd(cmd, rest=None)

Инициировать передачу по соединению данных. Если передача активна, отправьте команду EPRT или PORT и команду передачи, указанную в cmd, и примите соединение. Если сервер пассивный, отправьте команду EPSV или PASV, подключитесь к нему и запустите команду передачи. В любом случае верните сокет для соединения.

Если необязательный rest задан, отправляется команда REST на сервер, передавая rest в качестве аргумента. rest обычно представляет собой байтовый смещение в запрошенном файле, telling the server to restart sending the file’s bytes at the requested offset, skipping over the initial bytes. Однако следует учесть, что RFC 959 требует, чтобы rest был строкой, содержащей символы в печатном диапазоне от ASCII-кода 33 до ASCII-кода 126. Метод transfercmd() преобразует rest в строку, но никакой проверки содержимого строки не выполняется. Если сервер не распознаёт команду 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.

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(): Настроить текстовое соединение данных.