shutil – высокоуровневые операции с файлами¶shutil – High-level file operations

Операции с каталогами и файлами¶Directory and files operations

shutil.copyfileobj(fsrc, fdst[, length])¶

Копирует содержимое файлоподобного объекта fsrc в файлоподобный объект fdst. Целое число length, если задано, определяет размер буфера. В частности, отрицательное значение length означает копирование данных без разбиения исходных данных на части; по умолчанию данные читаются порциями, чтобы избежать неконтролируемого расхода памяти. Обратите внимание: если текущая позиция в файле объекта fsrc не равна 0, будут скопированы только данные от текущей позиции до конца файла.

shutil.copyfile(src, dst, *, follow_symlinks=True)¶

Копирует содержимое (без метаданных) файла с именем src в файл с именем dst и возвращает dst наиболее эффективным способом. src и dst являются путь-подобными объектами или именами путей, заданными в виде строк.

dst должно быть полным именем целевого файла; см. copy() для копирования, принимающего путь к целевому каталогу. Если src и dst указывают на один и тот же файл, возбуждается SameFileError.

Целевое расположение должно быть доступно для записи; в противном случае будет возбуждено исключение OSError. Если dst уже существует, оно будет заменено. Специальные файлы, такие как символьные или блочные устройства и каналы, не могут быть скопированы с помощью этой функции.

Если follow_symlinks имеет значение false и src является символической ссылкой, будет создана новая символическая ссылка вместо копирования файла, на который указывает src.

Возбуждает событие аудита shutil.copyfile с аргументами src, dst.

Изменено в версии 3.3: IOError ранее возбуждалось вместо OSError. Добавлен аргумент follow_symlinks. Теперь возвращает dst.

Изменено в версии 3.4: Возбуждается SameFileError вместо Error. Поскольку первое является подклассом второго, это изменение обратно совместимо.

Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел Платформенно-зависимые эффективные операции копирования.

exception shutil.SameFileError¶

Это исключение возбуждается, если источник и назначение в copyfile() являются одним и тем же файлом.

Новое в версии 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)¶

Копирует биты прав доступа из src в dst. Содержимое файла, владелец и группа не изменяются. src и dst являются путь-подобными объектами или именами путей, заданными в виде строк. Если follow_symlinks равен false и оба src и dst являются символическими ссылками, copymode() попытается изменить режим самой dst (а не файла, на который она указывает). Эта функциональность доступна не на всех платформах; подробнее см. copystat(). Если copymode() не может изменить символические ссылки на данной платформе, а запрос на это поступил, вызов ничего не делает и возвращает управление.

Возбуждает событие аудита shutil.copymode с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks.

shutil.copystat(src, dst, *, follow_symlinks=True)¶

Копирует биты прав доступа, время последнего доступа, время последнего изменения и флаги из src в dst. В Linux copystat() также копирует «расширенные атрибуты» там, где это возможно. Содержимое файла, владелец и группа не изменяются. src и dst являются путь-подобными объектами или именами путей, заданными в виде строк.

Если follow_symlinks имеет значение false и src и dst оба ссылаются на символические ссылки, copystat() будет работать с самими символическими ссылками, а не с файлами, на которые эти символические ссылки указывают – читая информацию из символической ссылки src и записывая информацию в символическую ссылку dst.

Примечание

Не все платформы предоставляют возможность просматривать и изменять символические ссылки. Python сам может сообщить, какая функциональность доступна локально.

• Если os.chmod in os.supports_follow_symlinks равен True, copystat() может изменять биты разрешений символической ссылки.

• Если os.utime in os.supports_follow_symlinks равен True, copystat() может изменять время последнего доступа и изменения символической ссылки.

• Если os.chflags in os.supports_follow_symlinks равно True, copystat() может изменять флаги символической ссылки. (os.chflags доступен не на всех платформах.)

На платформах, где часть или вся эта функциональность недоступна, при попытке изменить символическую ссылку copystat() скопирует всё, что сможет. copystat() никогда не возвращает ошибку.

Подробнее см. os.supports_follow_symlinks.

Возбуждает событие аудита shutil.copystat с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks и поддержка расширенных атрибутов Linux.

shutil.copy(src, dst, *, follow_symlinks=True)¶

Копирует файл src в файл или каталог dst. src и dst должны быть объектами, подобными пути или строками. Если dst указывает на каталог, файл будет скопирован в dst с использованием базового имени из src. Возвращает путь к только что созданному файлу.

Если follow_symlinks имеет значение false и src является символической ссылкой, dst будет создан как символическая ссылка. Если follow_symlinks имеет значение true и src является символической ссылкой, dst будет копией файла, на который указывает src.

copy() копирует данные файла и его режим доступа (см. os.chmod()). Другие метаданные, такие как время создания и изменения файла, не сохраняются. Чтобы сохранить все метаданные исходного файла, используйте copy2().

Возбуждает событие аудита shutil.copyfile с аргументами src, dst.

Возбуждает событие аудита shutil.copymode с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks. Теперь возвращает путь к созданному файлу.

Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел Платформенно-зависимые эффективные операции копирования.

shutil.copy2(src, dst, *, follow_symlinks=True)¶

Идентично copy(), за исключением того, что copy2() также пытается сохранить метаданные файла.

Когда follow_symlinks равен false, а src – символическая ссылка, copy2() пытается скопировать все метаданные из символической ссылки src в только что созданную символическую ссылку dst. Однако эта возможность доступна не на всех платформах. На платформах, где часть или вся эта функциональность недоступна, copy2() сохранит все метаданные, которые сможет; copy2() никогда не вызывает исключение, если не удаётся сохранить метаданные файла.

copy2() использует copystat() для копирования метаданных файла. Подробнее о поддержке платформами изменения метаданных символических ссылок см. copystat().

Возбуждает событие аудита shutil.copyfile с аргументами src, dst.

Возбуждает событие аудита shutil.copystat с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks, также предпринята попытка копировать расширенные атрибуты файловой системы (пока только Linux). Теперь возвращает путь к созданному файлу.

Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел Платформенно-зависимые эффективные операции копирования.

shutil.ignore_patterns(*patterns)¶

Эта фабричная функция создаёт функцию, которую можно использовать как вызываемый объект для аргумента ignore функции copytree(), игнорируя файлы и каталоги, соответствующие одному из предоставленных шаблонов в стиле glob. См. пример ниже.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)¶

Рекурсивно копирует всё дерево каталогов с корнем в src в каталог с именем dst и возвращает целевой каталог. Параметр dirs_exist_ok определяет, следует ли вызывать исключение, если dst или какой-либо отсутствующий родительский каталог уже существует.

Права доступа и временные метки каталогов копируются с помощью copystat(), отдельные файлы копируются с помощью copy2().

Если symlinks имеет значение true, символические ссылки в исходном дереве представляются как символические ссылки в новом дереве, и метаданные исходных ссылок будут скопированы насколько это позволяет платформа; если false или аргумент опущен, содержимое и метаданные файлов, на которые указывают ссылки, копируются в новое дерево.

Когда symlinks равен false, если файл, на который указывает символическая ссылка, не\ nсуществует, исключение будет добавлено в список ошибок, вызываемых в исключении Error в конце процесса копирования. Можно установить опциональный флаг ignore_dangling_symlinks в true, если требуется подавить это исключение. Обратите внимание, что эта опция не действует на платформах, не поддерживающих os.symlink().

Если задан ignore, это должен быть вызываемый объект, который будет получать в качестве аргументов каталог, обрабатываемый copytree(), и список его содержимого, возвращённый os.listdir(). Поскольку copytree() вызывается рекурсивно, вызываемый объект ignore будет вызываться один раз для каждого копируемого каталога. Вызываемый объект должен возвращать последовательность имён каталогов и файлов относительно текущего каталога (т.е. подмножество элементов из его второго аргумента); эти имена будут игнорироваться в процессе копирования. ignore_patterns() можно использовать для создания такого вызываемого объекта, который игнорирует имена на основе шаблонов в стиле glob.

Если возникают исключения, вызывается Error со списком причин.

Если задан copy_function, это должен быть вызываемый объект, который будет использоваться для копирования каждого файла. Он будет вызван с исходным и целевым путями в качестве аргументов. По умолчанию используется copy2(), но можно использовать любую функцию с той же сигнатурой (например, copy()).

Возбуждает событие аудита shutil.copytree с аргументами src, dst.

Изменено в версии 3.3: Копирует метаданные, когда symlinks имеет значение false. Теперь возвращает dst.

Изменено в версии 3.2: Добавлен аргумент copy_function, позволяющий указать собственную функцию копирования. Добавлен аргумент ignore_dangling_symlinks для подавления ошибок оборванных символических ссылок, когда symlinks имеет значение false.

Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел Платформенно-зависимые эффективные операции копирования.

Новое в версии 3.8: Параметр dirs_exist_ok.

shutil.rmtree(path, ignore_errors=False, onerror=None)¶

Удаляет целое дерево каталогов; path должен указывать на каталог (но не на символическую ссылку на каталог). Если ignore_errors равен true, ошибки, возникающие при неудачном удалении, игнорируются; если false или не указан, такие ошибки обрабатываются вызовом обработчика, заданного onerror, или, если он не указан, вызывается исключение.

Примечание

На платформах, поддерживающих необходимые функции на основе файловых дескрипторов, по умолчанию используется версия rmtree(), устойчивая к атакам через символические ссылки. На других платформах реализация rmtree() уязвима для такой атаки: при правильном выборе времени и обстоятельств злоумышленники могут манипулировать символическими ссылками в файловой системе, чтобы удалить файлы, к которым иначе у них не было бы доступа. Приложения могут использовать атрибут функции rmtree.avoids_symlink_attacks, чтобы определить применимый вариант.

Если onerror задан, он должен быть вызываемым объектом, принимающим три параметра: function, path и excinfo.

Первый параметр, function, – это функция, вызвавшая исключение; он зависит от платформы и реализации. Второй параметр, path, будет именем пути, переданным в function. Третий параметр, excinfo, будет информацией об исключении, возвращаемой sys.exc_info(). Исключения, вызванные onerror, не перехватываются.

Вызывает событие аудита shutil.rmtree с аргументом path.

Изменено в версии 3.3: Добавлена версия, устойчивая к атакам через символические ссылки, которая используется автоматически, если платформа поддерживает функции на основе файловых дескрипторов.

Изменено в версии 3.8: В Windows больше не удаляет содержимое точки соединения каталогов перед её удалением.

rmtree.avoids_symlink_attacks¶

Указывает, предоставляют ли текущая платформа и реализация версию rmtree(), устойчивую к атакам через символические ссылки. В настоящее время это верно только для платформ, поддерживающих функции доступа к каталогам на основе файловых дескрипторов.

Новое в версии 3.3.

shutil.move(src, dst, copy_function=copy2)¶

Рекурсивно перемещает файл или каталог (src) в другое место (dst) и возвращает путь назначения.

Если назначение – существующий каталог, то src перемещается внутрь этого каталога. Если назначение уже существует, но не является каталогом, оно может быть перезаписано в зависимости от семантики os.rename().

Если назначение находится в той же файловой системе, то используется os.rename(). В противном случае src копируется в dst с помощью copy_function и затем удаляется. В случае символических ссылок будет создана новая символическая ссылка, указывающая на цель src, в или как dst, а src будет удалён.

Если copy_function указан, он должен быть вызываемым объектом, принимающим два аргумента src и dst, и будет использоваться для копирования src в dst, если os.rename() не может быть использован. Если исходный объект – каталог, вызывается copytree() с передачей ему copy_function(). По умолчанию copy_function – copy2(). Использование copy() в качестве copy_function позволяет выполнить перемещение, когда невозможно также скопировать метаданные, ценой отсутствия копирования любых метаданных.

Возбуждает событие аудита shutil.move с аргументами src, dst.

Изменено в версии 3.3: Добавлена явная обработка символических ссылок для внешних файловых систем, что адаптирует поведение к GNU mv. Теперь возвращает dst.

Изменено в версии 3.5: Добавлен именованный аргумент copy_function.

Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел Платформенно-зависимые эффективные операции копирования.

shutil.disk_usage(path)¶

Возвращает статистику использования диска для указанного пути в виде именованного кортежа с атрибутами total, used и free, которые представляют общий, используемый и свободный объём в байтах. path может быть файлом или каталогом.

Новое в версии 3.3.

Изменено в версии 3.8: В Windows path теперь может быть файлом или каталогом.

Доступность: Unix, Windows.

shutil.chown(path, user=None, group=None)¶

Изменяет владельца user и/или группу group для указанного path.

user может быть системным именем пользователя или uid; то же самое относится к group. Требуется хотя бы один аргумент.

См. также os.chown() – базовую функцию.

Вызывает событие аудита shutil.chown с аргументами path, user, group.

Доступность: Unix.

Новое в версии 3.3.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)¶

Возвращает путь к исполняемому файлу, который был бы запущен, если бы была вызвана заданная команда cmd. Если команда cmd не будет вызвана, возвращает None.

mode – это маска разрешений, передаваемая в os.access(), по умолчанию определяющая, существует ли файл и является ли он исполняемым.

Если path не указан, используются результаты os.environ(), возвращающие либо значение «PATH», либо запасной вариант os.defpath.

В Windows текущий каталог всегда добавляется в начало path, независимо от того, используется значение по умолчанию или указано своё; такое же поведение применяет командная оболочка при поиске исполняемых файлов. Кроме того, при поиске cmd в path проверяется переменная окружения PATHEXT. Например, при вызове shutil.which("python") функция which() будет искать PATHEXT, чтобы узнать, что нужно искать python.exe в каталогах из path. Например, в Windows:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

Новое в версии 3.3.

Изменено в версии 3.8: Теперь принимается тип bytes. Если тип cmd – bytes, то тип результата также bytes.

exception shutil.Error¶

Это исключение собирает исключения, возникающие во время операции с несколькими файлами. Для copytree() аргумент исключения представляет собой список кортежей из трёх элементов (srcname, dstname, исключение).

def copytree(src, dst, symlinks=False):
    names = os.listdir(src)
    os.makedirs(dst)
    errors = []
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
            # XXX Что насчет устройств, сокетов и т.д.?
        except OSError as why:
            errors.append((srcname, dstname, str(why)))
        # перехватываем ошибку от рекурсивного copytree, чтобы мы могли
        # продолжить с другими файлами
        except Error as err:
            errors.extend(err.args[0])
    try:
        copystat(src, dst)
    except OSError as why:
        # не удается скопировать время доступа к файлам в Windows
        if why.winerror is None:
            errors.extend((src, dst, str(why)))
    if errors:
        raise Error(errors)

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # ничего не будет проигнорировано

copytree(source, destination, ignore=_logpath)

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onerror=remove_readonly)

Операции архивирования¶Archiving operations

Также предоставляются высокоуровневые утилиты для создания и чтения сжатых и архивных файлов. Они основаны на модулях zipfile и tarfile.

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])¶

Создаёт архивный файл (например, zip или tar) и возвращает его имя.

base_name – имя создаваемого файла, включая путь, без формато-специфического расширения. format – формат архива: один из «zip» (если доступен модуль zlib), «tar», «gztar» (если доступен модуль zlib), «bztar» (если доступен модуль bz2) или «xztar» (если доступен модуль lzma).

root_dir – это каталог, который будет корневым каталогом архива; все пути в архиве будут относительными по отношению к нему; например, перед созданием архива обычно выполняется chdir в root_dir.

base_dir – это каталог, из которого начинается архивация; т. е. base_dir будет общим префиксом для всех файлов и каталогов в архиве. base_dir должен быть указан относительно root_dir. См. Пример архивации с base_dir о том, как использовать base_dir и root_dir вместе.

root_dir и base_dir по умолчанию равны текущему каталогу.

Если dry_run равен true, архив не создаётся, но операции, которые были бы выполнены, записываются в журнал logger.

owner и group используются при создании tar-архива. По умолчанию используются текущий владелец и группа.

logger должен быть объектом, совместимым с PEP 282, обычно экземпляром logging.Logger.

Аргумент verbose не используется и является устаревшим.

Возбуждает событие аудита shutil.make_archive с аргументами base_name, format, root_dir, base_dir.

Примечание

Эта функция не является потокобезопасной.

Изменено в версии 3.8: Теперь используется современный формат pax (POSIX.1-2001) вместо устаревшего формата GNU для архивов, созданных с помощью format="tar".

shutil.get_archive_formats()¶

Возвращает список поддерживаемых форматов архивации. Каждый элемент возвращаемой последовательности – это кортеж (name, description).

По умолчанию shutil предоставляет следующие форматы:

• zip: ZIP-файл (если доступен модуль zlib).

• tar: Несжатый tar-файл. Использует формат pax (POSIX.1-2001) для новых архивов.

• gztar: tar-файл, сжатый gzip (если доступен модуль zlib).

• bztar: tar-файл, сжатый bzip2 (если доступен модуль bz2).

• xztar: tar-файл, сжатый xz (если доступен модуль lzma).

Можно зарегистрировать новые форматы или предоставить собственный архиватор для любого существующего формата, используя register_archive_format().

shutil.register_archive_format(name, function[, extra_args[, description]])¶

Регистрирует архиватор для формата name.

function – это вызываемый объект, который будет использоваться для распаковки архивов. Вызываемый объект получает base_name создаваемого файла, за которым следует base_dir (по умолчанию os.curdir), откуда начинается архивация. Дополнительные аргументы передаются как именованные: owner, group, dry_run и logger (как передано в make_archive()).

Если указан, extra_args – это последовательность пар (name, value), которые будут использоваться как дополнительные именованные аргументы при вызове архиватора.

description используется get_archive_formats(), который возвращает список архиваторов. По умолчанию – пустая строка.

shutil.unregister_archive_format(name)¶

Удалите имя формата архива name из списка поддерживаемых форматов.

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])¶

Распаковывает архив. filename – это полный путь к архиву.

extract_dir – имя целевой директории, в которую распаковывается архив. Если не указано, используется текущая рабочая директория.

format – это формат архива: один из «zip», «tar», «gztar», «bztar» или «xztar». Или любой другой формат, зарегистрированный с помощью register_unpack_format(). Если формат не указан, unpack_archive() будет использовать расширение имени файла архива и проверит, зарегистрирован ли распаковщик для этого расширения. Если ничего не найдено, вызывается ValueError.

Аргумент filter, передаваемый только по ключу, добавленный в Python 3.8.17, передаётся в нижележащую функцию распаковки. Для zip-файлов filter не принимается. Для tar-файлов рекомендуется устанавливать его в 'data', если не используются функции, специфичные для tar и UNIX-подобных файловых систем. (См. Фильтры извлечения для подробностей.) Фильтр 'data' станет фильтром по умолчанию для tar-файлов в Python 3.14.

Вызывает событие аудита shutil.unpack_archive с аргументами filename, extract_dir, format.

Предупреждение

Никогда не извлекайте архивы из ненадежных источников без предварительной проверки. Возможно, файлы будут созданы за пределами пути, указанного в аргументе extract_dir, например, файлы с абсолютными именами, начинающимися с «/», или именами с двумя точками «..».

Изменено в версии 3.7: Принимает объект, подобный пути для filename и extract_dir.

Изменено в версии 3.8.17: Добавлен аргумент filter.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])¶

Регистрирует формат распаковки. name – имя формата, а extensions – список расширений, соответствующих этому формату, например .zip для Zip-файлов.

function – вызываемый объект, который будет использоваться для распаковки архивов. Вызываемый объект получит:

• путь к архиву в качестве позиционного аргумента;

• каталог, в который необходимо извлечь архив, в качестве позиционного аргумента;

• возможно, ключевой аргумент filter, если он был передан в unpack_archive();

• дополнительные ключевые аргументы, заданные extra_args в виде последовательности кортежей (name, value).

description может быть указано для описания формата и будет возвращено функцией get_unpack_formats().

shutil.unregister_unpack_format(name)¶

Отменяет регистрацию формата распаковки. name – имя формата.

shutil.get_unpack_formats()¶

Возвращает список всех зарегистрированных форматов для распаковки. Каждый элемент возвращаемой последовательности является кортежем (name, extensions, description).

По умолчанию shutil предоставляет следующие форматы:

• zip: ZIP-файл (распаковка сжатых файлов работает, только если доступен соответствующий модуль).

• tar: несжатый tar-файл.

• gztar: tar-файл, сжатый gzip (если доступен модуль zlib).

• bztar: tar-файл, сжатый bzip2 (если доступен модуль bz2).

• xztar: tar-файл, сжатый xz (если доступен модуль lzma).

Вы можете зарегистрировать новые форматы или предоставить собственный распаковщик для любых существующих форматов, используя register_unpack_format().

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

Запрос размера выходного терминала¶Querying the size of the output terminal

shutil.get_terminal_size(fallback=(columns, lines))¶

Получить размер окна терминала.

Для каждого из двух измерений проверяется переменная окружения, соответственно COLUMNS и LINES. Если переменная определена и её значение – положительное целое число, оно используется.

Если COLUMNS или LINES не определена (что бывает чаще всего), терминал, подключённый к sys.__stdout__, опрашивается с помощью вызова os.get_terminal_size().

Если размер терминала не удаётся опросить – либо из-за того, что система не поддерживает опрос, либо потому, что нет подключения к терминалу, – используется значение, указанное в параметре fallback. fallback по умолчанию равно (80, 24), это размер, используемый по умолчанию многими эмуляторами терминала.

Возвращаемое значение – именованный кортеж типа os.terminal_size.

См. также: The Single UNIX Specification, Version 2, Другие переменные окружения.

Новое в версии 3.3.