`ftplib.md`

281 строк · 30.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/ftplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`ftplib`](https://python-all.ru/3.9/library/ftplib.html#module-ftplib) – клиент протокола FTP89**Исходный код:** [Lib/ftplib.py](https://python-all.ru/src/3.9/Lib/ftplib.py)1011---1213Этот модуль определяет класс [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) и несколько связанных с ним элементов. Класс [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) реализует клиентскую часть протокола FTP. Его можно использовать для написания программ на Python, которые выполняют различные автоматизированные задачи FTP, например зеркалирование других FTP-серверов. Он также используется модулем [`urllib.request`](https://python-all.ru/3.9/library/urllib.request.html#module-urllib.request) для обработки URL-адресов, использующих FTP. Дополнительную информацию о FTP (протокол передачи файлов) см. в Internet [**RFC 959**](https://python-all.ru/3.9/library/ftplib.html).1415По умолчанию используется кодировка UTF-8 в соответствии с [**RFC 2640**](https://python-all.ru/3.9/library/ftplib.html).1617Вот пример сеанса с использованием модуля [`ftplib`](https://python-all.ru/3.9/library/ftplib.html#module-ftplib):1819```python20>>> from ftplib import FTP21>>> ftp = FTP('ftp.us.debian.org')  # подключение к хосту, порт по умолчанию22>>> ftp.login()                     # пользователь anonymous, пароль anonymous@23'230 Login successful.'24>>> ftp.cwd('debian')               # перейти в каталог "debian"25'250 Directory successfully changed.'26>>> ftp.retrlines('LIST')           # список содержимого каталога27-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README28...29drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool30drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project31drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools32'226 Directory send OK.'33>>> with open('README', 'wb') as fp:34>>>     ftp.retrbinary('RETR README', fp.write)35'226 Transfer complete.'36>>> ftp.quit()37'221 Goodbye.'38```3940Модуль определяет следующие элементы:4142#### `class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')`4344Возвращает новый экземпляр класса [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP). Когда указан *host*, выполняется вызов метода `connect(host)`. Когда указан *user*, дополнительно выполняется вызов метода `login(user, passwd, acct)` (при этом *passwd* и *acct* по умолчанию равны пустой строке, если не заданы). Необязательный параметр *timeout* задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). *source\_address* – это кортеж из двух элементов `(host, port)`, к которому привязывается сокет в качестве исходного адреса перед подключением. Параметр *encoding* задаёт кодировку для каталогов и имён файлов.4546Класс [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) поддерживает оператор [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with), например:4748```python49>>> from ftplib import FTP50>>> with FTP("ftp1.at.proftpd.org") as ftp:51...     ftp.login()52...     ftp.dir()53... 54'230 Anonymous login ok, restrictions apply.'55dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .56dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..57dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS58dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora59>>>60```6162Изменено в версии 3.2: Добавлена поддержка оператора [`with`](https://python-all.ru/3.9/reference/compound_stmts.html#with).6364Изменено в версии 3.3: добавлен параметр *source\_address*.6566Изменено в версии 3.9: Если параметр *timeout* установлен в ноль, будет возбуждено [`ValueError`](https://python-all.ru/3.9/library/exceptions.html#ValueError) для предотвращения создания неблокирующего сокета. Добавлен параметр *encoding*, а значение по умолчанию изменено с Latin-1 на UTF-8 в соответствии с [**RFC 2640**](https://python-all.ru/3.9/library/ftplib.html).6768#### `class ftplib.FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None, *, encoding='utf-8')`6970Подкласс [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP), добавляющий поддержку TLS для FTP, как описано в [**RFC 4217**](https://python-all.ru/3.9/library/ftplib.html). Подключение выполняется как обычно к порту 21, неявно защищая управляющее соединение FTP перед аутентификацией. Для защиты соединения данных требуется явный вызов метода [`prot_p()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP_TLS.prot_p). *context* – это объект [`ssl.SSLContext`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLContext), который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну (потенциально долгоживущую) структуру. Ознакомьтесь с [рекомендациями по безопасности](https://python-all.ru/3.9/library/ssl.html#ssl-security) для получения лучших практик.7172*keyfile* и *certfile* – это устаревшая альтернатива *context* – они могут указывать на PEM-форматированные файлы закрытого ключа и цепочки сертификатов (соответственно) для SSL-соединения.7374Новое в версии 3.2.7576Изменено в версии 3.3: добавлен параметр *source\_address*.7778Изменено в версии 3.4: Теперь класс поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.9/library/ssl.html#ssl.HAS_SNI)).7980Устарело с версии 3.6: *keyfile* и *certfile* устарели в пользу *context*. Вместо них используйте [`ssl.SSLContext.load_cert_chain()`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLContext.load_cert_chain), или позвольте [`ssl.create_default_context()`](https://python-all.ru/3.9/library/ssl.html#ssl.create_default_context) выбрать доверенные сертификаты ЦС системы.8182Изменено в версии 3.9: Если параметр *timeout* установлен в ноль, будет возбуждено [`ValueError`](https://python-all.ru/3.9/library/exceptions.html#ValueError) для предотвращения создания неблокирующего сокета. Добавлен параметр *encoding*, а значение по умолчанию изменено с Latin-1 на UTF-8 в соответствии с [**RFC 2640**](https://python-all.ru/3.9/library/ftplib.html).8384Вот пример сеанса с использованием класса [`FTP_TLS`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP_TLS):8586```python87>>> ftps = FTP_TLS('ftp.pureftpd.org')88>>> ftps.login()89'230 Anonymous user logged in'90>>> ftps.prot_p()91'200 Data protection level set to "private"'92>>> ftps.nlst()93['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']94```9596#### `exception ftplib.error_reply`9798Исключение, возникающее при получении неожиданного ответа от сервера.99100#### `exception ftplib.error_temp`101102Исключение, возникающее при получении кода ошибки, указывающего на временную ошибку (коды ответов в диапазоне 400–499).103104#### `exception ftplib.error_perm`105106Исключение, возникающее при получении кода ошибки, указывающего на постоянную ошибку (коды ответов в диапазоне 500–599).107108#### `exception ftplib.error_proto`109110Исключение, возникающее при получении ответа от сервера, который не соответствует спецификациям ответов протокола передачи файлов (File Transfer Protocol), то есть начинается с цифры в диапазоне 1–5.111112#### `ftplib.all_errors`113114Набор всех исключений (в виде кортежа), которые могут возбуждать методы экземпляров [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) в результате проблем с FTP-соединением (в отличие от ошибок программирования со стороны вызывающего кода). В этот набор входят четыре исключения, перечисленные выше, а также [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError) и [`EOFError`](https://python-all.ru/3.9/library/exceptions.html#EOFError).115116> **См. также**117>118> **Модуль [`netrc`](https://python-all.ru/3.9/library/netrc.html#module-netrc)**119>120> Синтаксический анализатор для формата файлов `.netrc`. Файл `.netrc` обычно используется FTP-клиентами для загрузки информации аутентификации пользователя перед запросом к пользователю.121122## Объекты FTP123124Несколько методов доступны в двух вариантах: один для работы с текстовыми файлами, другой – для двоичных. Они названы по команде, за которой следует `lines` для текстовой версии или `binary` для двоичной.125126Экземпляры [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) имеют следующие методы:127128#### `FTP.set_debuglevel(level)`129130Устанавливает уровень отладки экземпляра. Это контролирует объём выводимой отладочной информации. Значение по умолчанию, `0`, не даёт отладочного вывода. Значение `1` даёт умеренный объём отладочного вывода, как правило, одну строку на запрос. Значение `2` или выше даёт максимальный объём отладочного вывода, с записью каждой строки, отправленной и полученной по управляющему соединению.131132#### `FTP.connect(host='', port=0, timeout=None, source_address=None)`133134Подключается к указанному хосту и порту. Номер порта по умолчанию равен `21`, как указано в спецификации протокола FTP. Редко возникает необходимость указывать другой номер порта. Эта функция должна вызываться только один раз для каждого экземпляра; её не следует вызывать вовсе, если хост был указан при создании экземпляра. Все остальные методы можно использовать только после установки соединения. Необязательный параметр *timeout* задаёт тайм-аут в секундах для попытки подключения. Если *timeout* не передан, будет использоваться глобальная настройка тайм-аута по умолчанию. *source\_address* – это кортеж из двух элементов `(host, port)`, к которому привязывается сокет в качестве исходного адреса перед подключением.135136Вызывает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `ftplib.connect` с аргументами `self`, `host`, `port`.137138Изменено в версии 3.3: добавлен параметр *source\_address*.139140#### `FTP.getwelcome()`141142Возвращает приветственное сообщение, отправленное сервером в ответ на начальное подключение. (Это сообщение иногда содержит отказ от ответственности или справочную информацию, которая может быть полезна пользователю.)143144#### `FTP.login(user='anonymous', passwd='', acct='')`145146Выполняет вход под указанным *user*. Параметры *passwd* и *acct* необязательны и по умолчанию равны пустой строке. Если *user* не указан, по умолчанию используется `'anonymous'`. Если *user* равен `'anonymous'`, пароль *passwd* по умолчанию – `'anonymous@'`. Эта функция должна вызываться только один раз для каждого экземпляра после установки соединения; её не следует вызывать, если хост и пользователь были указаны при создании экземпляра. Большинство команд FTP разрешены только после входа клиента. Параметр *acct* предоставляет «учётную информацию»; лишь немногие системы это реализуют.147148#### `FTP.abort()`149150Прерывает текущую передачу файла. Этот метод срабатывает не всегда, но попробовать стоит.151152#### `FTP.sendcmd(cmd)`153154Отправляет простую строку команды на сервер и возвращает строку ответа.155156Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `ftplib.sendcmd` с аргументами `self`, `cmd`.157158#### `FTP.voidcmd(cmd)`159160Отправляет простую командную строку серверу и обрабатывает ответ. Ничего не возвращает, если получен код ответа, соответствующий успеху (коды в диапазоне 200–299). В противном случае возбуждает [`error_reply`](https://python-all.ru/3.9/library/ftplib.html#ftplib.error_reply).161162Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `ftplib.sendcmd` с аргументами `self`, `cmd`.163164#### `FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)`165166Извлекает файл в двоичном режиме передачи. *cmd* должна быть соответствующей командой `RETR`: `'RETR filename'`. Функция *колбэк* вызывается для каждого полученного блока данных с единственным аргументом bytes, содержащим блок данных. Необязательный аргумент *blocksize* задаёт максимальный размер фрагмента для чтения из низкоуровневого объекта сокета, созданного для фактической передачи (он также будет максимальным размером блоков данных, передаваемых в *колбэк*). Выбирается разумное значение по умолчанию. *rest* означает то же, что и в методе [`transfercmd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.transfercmd).167168#### `FTP.retrlines(cmd, callback=None)`169170Загружает файл или список каталогов в кодировке, указанной параметром *encoding* при инициализации. *cmd* должна быть подходящей командой `RETR` (см. [`retrbinary()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.retrbinary)) или командой вроде `LIST` или `NLST` (обычно просто строка `'LIST'`). `LIST` загружает список файлов и информацию о них. `NLST` загружает список имён файлов. Функция *колбэк* вызывается для каждой строки с аргументом-строкой, содержащей строку без завершающего CRLF. По умолчанию *колбэк* выводит строку в `sys.stdout`.171172#### `FTP.set_pasv(val)`173174Включает «пассивный» режим, если *val* истинно, иначе отключает пассивный режим. Пассивный режим включён по умолчанию.175176#### `FTP.storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)`177178Сохраняет файл в двоичном режиме передачи. *cmd* должна быть соответствующей командой `STOR`: `"STOR filename"`. *fp* – это [файловый объект](https://python-all.ru/3.9/glossary.html#term-file-object) (открытый в двоичном режиме), который читается до конца файла с помощью его метода `read()` блоками размером *blocksize* для получения сохраняемых данных. Аргумент *blocksize* по умолчанию равен 8192. *колбэк* – это необязательная вызываемая функция с одним параметром, которая вызывается для каждого блока данных после его отправки. *rest* означает то же, что и в методе [`transfercmd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.transfercmd).179180Изменено в версии 3.2: *rest* добавлен параметр.181182#### `FTP.storlines(cmd, fp, callback=None)`183184Сохраняет файл в строчном режиме. *cmd* должна быть подходящей командой `STOR` (см. [`storbinary()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.storbinary)). Строки читаются до EOF из [файлового объекта](https://python-all.ru/3.9/glossary.html#term-file-object) *fp* (открытого в двоичном режиме) с помощью его метода [`readline()`](https://python-all.ru/3.9/library/io.html#io.IOBase.readline) для получения сохраняемых данных. *колбэк* – необязательный вызываемый объект с одним параметром, вызываемый для каждой строки после её отправки.185186#### `FTP.transfercmd(cmd, rest=None)`187188Инициирует передачу по соединению данных. Если передача активная, отправляет команду `EPRT` или `PORT` и команду передачи, указанную в *cmd*, и принимает соединение. Если сервер пассивный, отправляет команду `EPSV` или `PASV`, подключается к нему и запускает команду передачи. В любом случае возвращает сокет соединения.189190Если указан необязательный параметр *rest*, серверу отправляется команда `REST` с аргументом *rest*. Обычно *rest* – это смещение в байтах в запрашиваемом файле, указывающее серверу возобновить отправку байтов файла с указанного смещения, пропуская начальные байты. Однако обратите внимание, что метод [`transfercmd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.transfercmd) преобразует *rest* в строку с параметром *encoding*, указанным при инициализации, но содержимое строки не проверяется. Если сервер не распознаёт команду `REST`, будет возбуждено исключение [`error_reply`](https://python-all.ru/3.9/library/ftplib.html#ftplib.error_reply). Если это произошло, просто вызовите [`transfercmd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.transfercmd) без аргумента *rest*.191192#### `FTP.ntransfercmd(cmd, rest=None)`193194Как и [`transfercmd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.transfercmd), но возвращает кортеж из соединения данных и ожидаемого размера данных. Если ожидаемый размер не удалось вычислить, в качестве ожидаемого размера возвращается `None`. *cmd* и *rest* имеют тот же смысл, что и в [`transfercmd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.transfercmd).195196#### `FTP.mlsd(path="", facts=[])`197198List a directory in a standardized format by using `MLSD` command ([**RFC 3659**](https://python-all.ru/3.9/library/ftplib.html)). If *path* is omitted the current directory is assumed. *facts* is a list of strings representing the type of information desired (e.g. `["type", "size", "perm"]`). Return a generator object yielding a tuple of two elements for every file found in path. First element is the file name, the second one is a dictionary containing facts about the file name. Content of this dictionary might be limited by the *facts* argument but server is not guaranteed to return all requested facts.199200Новое в версии 3.3.201202#### `FTP.nlst(argument[, ...])`203204Возвращает список имён файлов, возвращаемый командой `NLST`. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `NLST`.205206> **Примечание**207>208> Если сервер поддерживает команду, [`mlsd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.mlsd) предоставляет более удобный API.209210#### `FTP.dir(argument[, ...])`211212Выводит список каталога, возвращаемый командой `LIST`, печатая его в стандартный вывод. Необязательный аргумент *argument* – это каталог для вывода списка (по умолчанию текущий каталог сервера). Можно использовать несколько аргументов для передачи нестандартных параметров команде `LIST`. Если последний аргумент является функцией, он используется как функция обратного вызова *колбэк*, как в [`retrlines()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.retrlines); по умолчанию вывод производится в `sys.stdout`. Этот метод возвращает `None`.213214> **Примечание**215>216> Если сервер поддерживает команду, [`mlsd()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.mlsd) предоставляет более удобный API.217218#### `FTP.rename(fromname, toname)`219220Переименовывает файл *fromname* на сервере в *toname*.221222#### `FTP.delete(filename)`223224Удаляет файл с именем *filename* с сервера. В случае успеха возвращает текст ответа, иначе возбуждает [`error_perm`](https://python-all.ru/3.9/library/ftplib.html#ftplib.error_perm) при ошибках прав доступа или [`error_reply`](https://python-all.ru/3.9/library/ftplib.html#ftplib.error_reply) при других ошибках.225226#### `FTP.cwd(pathname)`227228Устанавливает текущий каталог на сервере.229230#### `FTP.mkd(pathname)`231232Создаёт новый каталог на сервере.233234#### `FTP.pwd()`235236Возвращает путь к текущему каталогу на сервере.237238#### `FTP.rmd(dirname)`239240Удаляет каталог с именем *dirname* на сервере.241242#### `FTP.size(filename)`243244Запрашивает размер файла с именем *filename* на сервере. В случае успеха размер файла возвращается как целое число, иначе возвращается `None`. Обратите внимание, что команда `SIZE` не стандартизирована, но поддерживается многими распространёнными реализациями серверов.245246#### `FTP.quit()`247248Отправляет команду `QUIT` серверу и закрывает соединение. Это «вежливый» способ закрытия соединения, но он может возбудить исключение, если сервер отвечает ошибкой на команду `QUIT`. Это подразумевает вызов метода [`close()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.close), который делает экземпляр [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) бесполезным для последующих вызовов (см. ниже).249250#### `FTP.close()`251252Односторонне закрывает соединение. Не следует применять к уже закрытому соединению, например, после успешного вызова [`quit()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.quit). После этого вызова экземпляр [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP) больше не должен использоваться (после вызова [`close()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.close) или [`quit()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.quit) нельзя снова открыть соединение, вызвав метод [`login()`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP.login)).253254## Объекты FTP\_TLS255256[`FTP_TLS`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP_TLS) класс наследует от [`FTP`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP), определяя эти дополнительные объекты:257258#### `FTP_TLS.ssl_version`259260Версия SSL для использования (по умолчанию [`ssl.PROTOCOL_SSLv23`](https://python-all.ru/3.9/library/ssl.html#ssl.PROTOCOL_SSLv23)).261262#### `FTP_TLS.auth()`263264Устанавливает защищённое управляющее соединение с использованием TLS или SSL, в зависимости от того, что указано в атрибуте [`ssl_version`](https://python-all.ru/3.9/library/ftplib.html#ftplib.FTP_TLS.ssl_version).265266Изменено в версии 3.4: Теперь метод поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.9/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.9/library/ssl.html#ssl.HAS_SNI)).267268#### `FTP_TLS.ccc()`269270Возвращает управляющий канал обратно в открытый текст. Это может быть полезно для использования межсетевых экранов, которые умеют обрабатывать NAT с небезопасным FTP без открытия фиксированных портов.271272Новое в версии 3.3.273274#### `FTP_TLS.prot_p()`275276Устанавливает защищённое соединение данных.277278#### `FTP_TLS.prot_c()`279280Устанавливает незащищённое соединение данных.281