os — Различные интерфейсы операционной системы

Имена файлов, аргументы командной строки и переменные среды

В Python имена файлов, аргументы командной строки и переменные среды представлены строковым типом. В некоторых системах перед передачей этих строк операционной системе необходимо преобразовать их в байты и обратно. Для этого преобразования Python использует кодировку файловой системы и обработчик ошибок (см. sys.getfilesystemencoding()).

Кодировка файловой системы и обработчик ошибок настраиваются при запуске Python функцией PyConfig_Read(): см. параметры filesystem_encoding и filesystem_errors структуры PyConfig.

Кодировка файловой системы должна гарантировать успешное декодирование всех байтов со значениями меньше 128. Если кодировка файловой системы не обеспечивает эту гарантию, функции API могут вызвать исключение UnicodeError.

См. также кодировку локали.

Режим UTF-8 в Python

Режим UTF-8 в Python игнорирует кодировку локали и принудительно использует кодировку UTF-8:

• Использовать UTF-8 в качестве кодировки файловой системы.
• sys.getfilesystemencoding() возвращает 'utf-8'.
• locale.getpreferredencoding() возвращает 'utf-8' (аргумент do_setlocale не влияет на результат).
• sys.stdin, sys.stdout и sys.stderr используют UTF-8 в качестве текстовой кодировки; для sys.stdin и sys.stdout включён обработчик ошибок surrogateescape (sys.stderr продолжает использовать backslashreplace, как и в обычном режиме с учётом локали)
• В Unix os.device_encoding() возвращает 'utf-8' вместо кодировки устройства.

Обратите внимание: настройки стандартных потоков в режиме UTF-8 можно переопределить с помощью PYTHONIOENCODING (как и в обычном режиме с учётом локали).

Изменения в этих низкоуровневых API приводят к тому, что в других высокоуровневых API также меняется поведение по умолчанию:

• Аргументы командной строки, переменные среды и имена файлов декодируются в текст с использованием кодировки UTF-8.
• os.fsdecode() и os.fsencode() используют кодировку UTF-8.
• open(), io.open() и codecs.open() по умолчанию используют кодировку UTF-8. Однако по умолчанию они по-прежнему используют строгий обработчик ошибок, поэтому попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не приведёт к получению бессмысленных данных.

Режим UTF-8 в Python включается, если при запуске Python локаль LC_CTYPE имеет значение C или POSIX (см. функцию PyConfig_Read()).

Режим можно включить или отключить с помощью параметра командной строки -X utf8 и переменной среды PYTHONUTF8.

Если переменная среды PYTHONUTF8 вообще не задана, интерпретатор по умолчанию использует текущие настройки локали, если только текущая локаль не распознана как устаревшая локаль на основе ASCII (как описано для PYTHONCOERCECLOCALE), а преобразование локали не отключено и не завершилось ошибкой. В таких устаревших локалях интерпретатор по умолчанию включает режим UTF-8, если явно не указано обратное.

Режим UTF-8 в Python можно включить только при запуске Python. Его значение можно получить из sys.flags.utf8_mode.

См. также режим UTF-8 в Windows и кодировку файловой системы и обработчик ошибок.

Параметры процесса

Эти функции и элементы данных предоставляют информацию о текущем процессе и пользователе и позволяют выполнять операции с ними.

os.ctermid()

Возвращает имя файла, соответствующее управляющему терминалу процесса.

Доступность: Unix, кроме Emscripten и WASI.

os.environ

Объект отображения, ключи и значения которого являются строками, представляющими окружение процесса. Например, environ['HOME'] — это путь к домашнему каталогу (на некоторых платформах), эквивалентный getenv("HOME") в C.

Это отображение создаётся при первом импорте модуля os, обычно при запуске Python в процессе обработки site.py. Изменения окружения, сделанные после этого момента, не отражаются в os.environ, за исключением изменений, внесённых непосредственным изменением os.environ.

Это отображение можно использовать как для изменения окружения, так и для получения сведений о нём. При изменении отображения автоматически вызывается putenv().

В Unix для ключей и значений используются sys.getfilesystemencoding() и обработчик ошибок 'surrogateescape'. Используйте environb, если хотите использовать другую кодировку.

В Windows ключи преобразуются в верхний регистр. Это также относится к получению, установке и удалению элементов. Например, environ['monty'] = 'python' сопоставляет ключу 'MONTY' значение 'python'.

Примечание

Непосредственный вызов putenv() не изменяет os.environ, поэтому лучше изменять os.environ.

Примечание

На некоторых платформах, включая FreeBSD и macOS, установка environ может привести к утечкам памяти. См. системную документацию по putenv().

Чтобы удалить переменные окружения, можно удалять элементы из этого отображения. При удалении элемента из os.environ, а также при вызове одного из методов pop() или clear() автоматически вызывается unsetenv().

Изменено в версии 3.9: Добавлена поддержка операторов объединения (|) и обновления (|=) из PEP 584.

os.environb

Байтовая версия environ: объект отображения, ключи и значения которого являются объектами bytes, представляющими окружение процесса. environ и environb синхронизированы (изменение environb обновляет environ, и наоборот).

environb доступно только в том случае, если supports_bytes_environ имеет значение True.

Добавлено в версии 3.2.

Изменено в версии 3.9: Добавлена поддержка операторов объединения (|) и обновления (|=) из PEP 584.

os.chdir(path)

os.fchdir(fd)

os.getcwd()

Описание этих функций приведено в разделе Файлы и каталоги.

os.fsencode(filename)

Кодирует имя файла, допускающее использование в качестве пути, с помощью кодировки файловой системы и обработчика ошибок; объект bytes возвращает без изменений.

fsdecode() — обратная функция.

Добавлено в версии 3.2.

Изменено в версии 3.6: Добавлена поддержка объектов, реализующих интерфейс os.PathLike.

os.fsdecode(filename)

Декодирует имя файла, допускающее использование в качестве пути, с помощью кодировки файловой системы и обработчика ошибок; объект str возвращает без изменений.

fsencode() — обратная функция.

Добавлено в версии 3.2.

Изменено в версии 3.6: Добавлена поддержка объектов, реализующих интерфейс os.PathLike.

os.fspath(path)

Возвращает представление пути в файловой системе.

Если передан объект str или bytes, он возвращается без изменений. В противном случае вызывается __fspath__(), и возвращается его значение, если оно является объектом str или bytes. Во всех остальных случаях вызывается исключение TypeError.

Добавлено в версии 3.6.

class os.PathLike

Абстрактный базовый класс для объектов, представляющих путь в файловой системе, например pathlib.PurePath.

Добавлено в версии 3.6.

abstractmethod __fspath__()

Возвращает представление объекта в виде пути файловой системы.

Метод должен возвращать только объект str или bytes, предпочтительно str.

os.getenv(key, default=None)

Возвращает значение переменной окружения key в виде строки, если она существует, или default, если она не существует. key — строка. Поскольку getenv() использует os.environ, отображение для getenv() также создаётся при импорте, и функция может не отражать последующие изменения окружения.

В Unix ключи и значения декодируются с помощью sys.getfilesystemencoding() и обработчика ошибок 'surrogateescape'. Используйте os.getenvb(), если хотите использовать другую кодировку.

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

os.getenvb(key, default=None)

Возвращает значение переменной окружения key в виде байтов, если она существует, или default, если она не существует. key должен быть объектом bytes. Поскольку getenvb() использует os.environb, отображение для getenvb() также создаётся при импорте, и функция может не отражать последующие изменения окружения.

getenvb() доступна только в том случае, если supports_bytes_environ имеет значение True.

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

Добавлено в версии 3.2.

os.get_exec_path(env=None)

Возвращает список каталогов, в которых будет выполняться поиск указанного исполняемого файла при запуске процесса, подобно тому, как это делает командная оболочка. Если указан параметр env, он должен быть словарём переменных окружения, из которого будет извлечён PATH. По умолчанию, если env имеет значение None, используется environ.

Добавлено в версии 3.2.

os.getegid()

Возвращает эффективный идентификатор группы текущего процесса. Он соответствует биту «set id» файла, выполняемого текущим процессом.

Доступность: Unix, кроме Emscripten и WASI.

os.geteuid()

Возвращает эффективный идентификатор пользователя текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

os.getgid()

Возвращает реальный идентификатор группы текущего процесса.

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

В Emscripten и WASI функция является заглушкой; дополнительную информацию см. в разделе Платформы WebAssembly.

os.getgrouplist(user, group, /)

Возвращает список идентификаторов групп, к которым принадлежит user. Если group отсутствует в списке, он включается в него; обычно group указывается как поле идентификатора группы в записи пароля для user, поскольку в противном случае этот идентификатор группы может быть пропущен.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.3.

os.getgroups()

Возвращает список дополнительных идентификаторов групп, связанных с текущим процессом.

Доступность: Unix, кроме Emscripten и WASI.

Примечание

В macOS поведение getgroups() несколько отличается от поведения на других платформах Unix. Если интерпретатор Python собран с целевой версией развёртывания 10.5 или более ранней, getgroups() возвращает список эффективных идентификаторов групп, связанных с текущим пользовательским процессом; этот список ограничен заданным системой числом элементов, обычно 16, и может быть изменён вызовами setgroups() при наличии соответствующих привилегий. Если интерпретатор собран с целевой версией развёртывания выше 10.5, getgroups() возвращает текущий список группового доступа пользователя, связанного с эффективным идентификатором пользователя процесса; список группового доступа может изменяться в течение жизни процесса, на него не влияют вызовы setgroups(), и его длина не ограничена 16 элементами. Значение целевой версии развёртывания, MACOSX_DEPLOYMENT_TARGET, можно получить с помощью sysconfig.get_config_var().

os.getlogin()

Возвращает имя пользователя, вошедшего в систему через управляющий терминал процесса. В большинстве случаев удобнее использовать getpass.getuser(), поскольку последняя проверяет переменные окружения LOGNAME или USERNAME, чтобы определить имя пользователя, а если они не заданы, обращается к pwd.getpwuid(os.getuid())[0] для получения имени входа текущего реального идентификатора пользователя.

Доступность: Unix, Windows, кроме Emscripten и WASI.

os.getpgid(pid)

Возвращает идентификатор группы процессов процесса с идентификатором процесса pid. Если pid равен 0, возвращается идентификатор группы процессов текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

os.getpgrp()

Возвращает идентификатор текущей группы процессов.

Доступность: Unix, кроме Emscripten и WASI.

os.getpid()

Возвращает идентификатор текущего процесса.

В Emscripten и WASI функция является заглушкой; дополнительную информацию см. в разделе Платформы WebAssembly.

os.getppid()

Возвращает идентификатор родительского процесса. Если родительский процесс завершился, в Unix возвращается идентификатор процесса init (1), а в Windows возвращается тот же идентификатор, который к этому моменту уже может быть повторно использован другим процессом.

Доступность: Unix, Windows, кроме Emscripten и WASI.

Изменено в версии 3.2: Добавлена поддержка Windows.

os.getpriority(which, who)

Получает приоритет планирования программы. Значение which должно быть одним из следующих: PRIO_PROCESS, PRIO_PGRP или PRIO_USER; значение who интерпретируется относительно which (идентификатор процесса для PRIO_PROCESS, идентификатор группы процессов для PRIO_PGRP и идентификатор пользователя для PRIO_USER). Нулевое значение who обозначает (соответственно) вызывающий процесс, группу процессов вызывающего процесса или реальный идентификатор пользователя вызывающего процесса.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.3.

os.PRIO_PROCESS

os.PRIO_PGRP

os.PRIO_USER

Параметры для функций getpriority() и setpriority().

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.3.

os.getresuid()

Возвращает кортеж (ruid, euid, suid), содержащий реальные, эффективные и сохранённые идентификаторы пользователя текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.2.

os.getresgid()

Возвращает кортеж (rgid, egid, sgid), содержащий реальные, эффективные и сохранённые идентификаторы группы текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.2.

os.getuid()

Возвращает реальный идентификатор пользователя текущего процесса.

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

В Emscripten и WASI функция является заглушкой; дополнительную информацию см. в разделе Платформы WebAssembly.

os.initgroups(username, gid, /)

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

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.2.

os.putenv(key, value, /)

Устанавливает для переменной окружения с именем key строковое значение value. Такие изменения окружения влияют на подпроцессы, запущенные с помощью os.system(), popen() или fork() и execv().

Присваивание значений элементам os.environ автоматически преобразуется в соответствующие вызовы putenv(); однако вызовы putenv() не обновляют os.environ, поэтому предпочтительнее присваивать значения элементам os.environ. Это также относится к getenv() и getenvb(), которые в своих реализациях используют соответственно os.environ и os.environb.

Примечание

На некоторых платформах, включая FreeBSD и macOS, установка environ может привести к утечкам памяти. См. системную документацию по putenv().

Вызывает событие аудита os.putenv с аргументами key, value.

Изменено в версии 3.9: Теперь функция доступна всегда.

os.setegid(egid, /)

Устанавливает эффективный идентификатор группы текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

os.seteuid(euid, /)

Устанавливает эффективный идентификатор пользователя текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

os.setgid(gid, /)

Устанавливает идентификатор группы текущего процесса.

Доступность: Unix, кроме Emscripten и WASI.

os.setgroups(groups, /)

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

Доступность: Unix, кроме Emscripten и WASI.

Примечание

В macOS длина groups не может превышать заданное системой максимальное число эффективных идентификаторов групп, обычно равное 16. О случаях, когда список групп, возвращаемый функцией getgroups(), может отличаться от списка, заданного вызовом setgroups(), см. документацию этой функции.

os.setpgrp()

Вызывает системный вызов setpgrp() или setpgrp(0, 0) — в зависимости от того, какая версия реализована (если реализована). Описание семантики см. в руководстве Unix.

Доступность: Unix, кроме Emscripten и WASI.

os.setpgid(pid, pgrp, /)

Вызов системного вызова setpgid() для установки идентификатора группы процессов процесса с идентификатором pid в группу процессов с идентификатором pgrp. Описание семантики см. в руководстве Unix.

Доступность: Unix, не Emscripten, не WASI.

os.setpriority(which, who, priority)

Установить приоритет планирования программы. Значение which — одно из PRIO_PROCESS, PRIO_PGRP или PRIO_USER, а значение who интерпретируется относительно which (идентификатор процесса для PRIO_PROCESS, идентификатор группы процессов для PRIO_PGRP и идентификатор пользователя для PRIO_USER). Нулевое значение who обозначает соответственно вызывающий процесс, группу процессов вызывающего процесса или реальный идентификатор пользователя вызывающего процесса. priority — значение в диапазоне от -20 до 19. Приоритет по умолчанию равен 0; более низкие значения приоритета обеспечивают более благоприятное планирование.

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.3.

os.setregid(rgid, egid, /)

Установить реальные и эффективные идентификаторы группы текущего процесса.

Доступность: Unix, не Emscripten, не WASI.

os.setresgid(rgid, egid, sgid, /)

Установить реальные, эффективные и сохранённые идентификаторы группы текущего процесса.

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.2.

os.setresuid(ruid, euid, suid, /)

Установить реальные, эффективные и сохранённые идентификаторы пользователя текущего процесса.

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.2.

os.setreuid(ruid, euid, /)

Установить реальные и эффективные идентификаторы пользователя текущего процесса.

Доступность: Unix, не Emscripten, не WASI.

os.getsid(pid, /)

Вызов системного вызова getsid(). Описание семантики см. в руководстве Unix.

Доступность: Unix, не Emscripten, не WASI.

os.setsid()

Вызов системного вызова setsid(). Описание семантики см. в руководстве Unix.

Доступность: Unix, не Emscripten, не WASI.

os.setuid(uid, /)

Установить идентификатор пользователя текущего процесса.

Доступность: Unix, не Emscripten, не WASI.

os.strerror(code, /)

Возвращает сообщение об ошибке, соответствующее коду ошибки code. На платформах, где strerror() возвращает NULL при передаче неизвестного номера ошибки, возбуждается исключение ValueError.

os.supports_bytes_environ

True, если тип среды окружения в родной ОС — bytes (например, False в Windows).

Добавлено в версии 3.2.

os.umask(mask, /)

Установить текущую числовую маску umask и вернуть предыдущую маску.

В Emscripten и WASI эта функция является заглушкой. Дополнительную информацию см. в разделе Платформы WebAssembly.

os.uname()

Возвращает сведения, идентифицирующие текущую операционную систему. Возвращаемое значение — объект с пятью атрибутами:

• sysname — название операционной системы
• nodename — имя компьютера в сети (определяется реализацией)
• release — выпуск операционной системы
• version — версия операционной системы
• machine — идентификатор оборудования

Для обратной совместимости этот объект также является итерируемым и ведёт себя как кортеж из пяти элементов, содержащий sysname, nodename, release, version и machine в указанном порядке.

Некоторые системы обрезают nodename до 8 символов или до первого компонента; лучший способ получить имя хоста — использовать socket.gethostname() или даже socket.gethostbyaddr(socket.gethostname()).

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

Изменено в версии 3.3: Тип возвращаемого значения изменён с кортежа на объект, подобный кортежу, с именованными атрибутами.

os.unsetenv(key, /)

Сбросить (удалить) переменную окружения с именем key. Такие изменения среды окружения влияют на подпроцессы, запущенные с помощью os.system(), popen() или fork() и execv().

Удаление элементов из os.environ автоматически преобразуется в соответствующий вызов unsetenv(); однако вызовы unsetenv() не обновляют os.environ, поэтому на самом деле предпочтительнее удалять элементы из os.environ.

Вызывает событие аудита os.unsetenv с аргументом key.

Изменено в версии 3.9: Теперь функция всегда доступна, в том числе в Windows.

Создание файловых объектов

Эти функции создают новые файловые объекты. (См. также open(), предназначенную для открытия файловых дескрипторов.)

os.fdopen(fd, *args, **kwargs)

Возвращает открытый файловый объект, связанный с файловым дескриптором fd. Это псевдоним встроенной функции open(), принимающий те же аргументы. Единственное отличие состоит в том, что первый аргумент fdopen() всегда должен быть целым числом.

Операции с файловыми дескрипторами

Эти функции выполняют операции с потоками ввода-вывода, на которые ссылаются с помощью файловых дескрипторов.

Файловые дескрипторы — это небольшие целые числа, соответствующие файлам, открытым текущим процессом. Например, стандартный ввод обычно имеет файловый дескриптор 0, стандартный вывод — 1, а стандартный поток ошибок — 2. Следующим файлам, открытым процессом, будут назначены дескрипторы 3, 4, 5 и так далее. Название «файловый дескриптор» несколько вводит в заблуждение: на платформах Unix на файловые дескрипторы также ссылаются сокеты и каналы.

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

os.close(fd)

Закрыть файловый дескриптор fd.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода и должна применяться к файловому дескриптору, полученному с помощью os.open() или pipe(). Чтобы закрыть «файловый объект», возвращённый встроенной функцией open() либо функцией popen() или fdopen(), используйте его метод close().

os.closerange(fd_low, fd_high, /)

Закрыть все файловые дескрипторы от fd_low (включительно) до fd_high (не включая), игнорируя ошибки. Эквивалентно следующему (но работает намного быстрее):

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass

os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)

Скопировать count байт из файлового дескриптора src, начиная со смещения offset_src, в файловый дескриптор dst, начиная со смещения offset_dst. Если offset_src равен None, данные читаются из src начиная с текущей позиции; аналогично для offset_dst. Файлы, на которые указывают src и dst, должны находиться в одной файловой системе, иначе возникает исключение OSError со значением errno, равным errno.EXDEV.

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

Возвращаемое значение — количество скопированных байт. Оно может быть меньше запрошенного.

Доступность: Linux >= 4.5 с glibc >= 2.27.

Добавлено в версии 3.8.

os.device_encoding(fd)

Если файловый дескриптор fd подключён к терминалу, вернуть строку с описанием кодировки связанного с ним устройства; в противном случае вернуть None.

В Unix, если включён режим UTF-8 Python, вместо кодировки устройства возвращается 'UTF-8'.

Изменено в версии 3.10: В Unix функция теперь реализует режим UTF-8 Python.

os.dup(fd, /)

Вернуть дубликат файлового дескриптора fd. Новый файловый дескриптор не наследуется.

В Windows при дублировании стандартного потока (0: stdin, 1: stdout, 2: stderr) новый файловый дескриптор наследуется.

Доступность: не WASI.

Изменено в версии 3.4: Теперь новый файловый дескриптор не наследуется.

os.dup2(fd, fd2, inheritable=True)

Дублировать файловый дескриптор fd в fd2, предварительно закрыв последний, если необходимо. Вернуть fd2. По умолчанию новый файловый дескриптор наследуется; он не наследуется, если inheritable равен False.

Доступность: не WASI.

Изменено в версии 3.4: Добавлен необязательный параметр inheritable.

Изменено в версии 3.7: При успешном выполнении возвращается fd2. Ранее всегда возвращалось None.

os.fchmod(fd, mode)

Изменить режим файла, заданного дескриптором fd, на числовой режим mode. Возможные значения mode см. в документации к chmod(). Начиная с Python 3.3, эта функция эквивалентна os.chmod(fd, mode).

Вызывает событие аудита os.chmod с аргументами path, mode, dir_fd.

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

В Emscripten и WASI возможности функции ограничены; дополнительную информацию см. в разделе Платформы WebAssembly.

os.fchown(fd, uid, gid)

Изменить идентификаторы владельца и группы файла, заданного дескриптором fd, на числовые значения uid и gid. Чтобы оставить один из идентификаторов без изменений, задайте для него значение -1. См. chown(). Начиная с Python 3.3, эта функция эквивалентна os.chown(fd, uid, gid).

Вызывает событие аудита os.chown с аргументами path, uid, gid, dir_fd.

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

В Emscripten и WASI возможности функции ограничены; дополнительную информацию см. в разделе Платформы WebAssembly.

os.fdatasync(fd)

Принудительно записать файл с файловым дескриптором fd на диск. Обновление метаданных не выполняется принудительно.

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

Примечание

Эта функция недоступна в MacOS.

os.fpathconf(fd, name, /)

Вернуть сведения о конфигурации системы, относящиеся к открытому файлу. Параметр name задаёт конфигурационное значение для получения; это может быть строка с именем определённого системного значения. Такие имена указаны в ряде стандартов (POSIX.1, Unix 95, Unix 98 и других). Некоторые платформы определяют также дополнительные имена. Имена, известные операционной системе узла, указаны в словаре pathconf_names. Для переменных конфигурации, не включённых в это соответствие, в качестве name также можно передать целое число.

Если name — строка с неизвестным именем, возникает исключение ValueError. Если указанное значение name не поддерживается системой узла, даже если оно включено в pathconf_names, возникает исключение OSError, а номер ошибки задаётся значением errno.EINVAL.

Начиная с Python 3.3, эта функция эквивалентна os.pathconf(fd, name).

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

os.fstat(fd)

Получить состояние файлового дескриптора fd. Вернуть объект stat_result.

Начиная с Python 3.3, эта функция эквивалентна os.stat(fd).

См. также

Функцию stat().

os.fstatvfs(fd, /)

Вернуть сведения о файловой системе, содержащей файл, связанный с файловым дескриптором fd, как и statvfs(). Начиная с Python 3.3, эта функция эквивалентна os.statvfs(fd).

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

os.fsync(fd)

Принудительно записать файл с файловым дескриптором fd на диск. В Unix вызывается встроенная функция fsync(); в Windows — функция MS _commit().

Если вы начинаете с буферизованного Python файлового объекта f, сначала выполните f.flush(), а затем os.fsync(f.fileno()), чтобы гарантировать запись на диск всех внутренних буферов, связанных с f.

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

os.ftruncate(fd, length, /)

Усечь файл, соответствующий файловому дескриптору fd, до размера не более length байт. Начиная с Python 3.3, эта функция эквивалентна os.truncate(fd, length).

Вызывает событие аудита os.truncate с аргументами fd, length.

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

Изменено в версии 3.5: Добавлена поддержка Windows

os.get_blocking(fd, /)

Получить режим блокировки файлового дескриптора: False, если установлен флаг O_NONBLOCK, и True, если флаг сброшен.

См. также set_blocking() и socket.socket.setblocking().

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

В Emscripten и WASI возможности функции ограничены; дополнительную информацию см. в разделе Платформы WebAssembly.

Добавлено в версии 3.5.

os.isatty(fd, /)

Вернуть True, если файловый дескриптор fd открыт и подключён к устройству tty (или подобному), и False в противном случае.

os.lockf(fd, cmd, len, /)

Установить, проверить или снять блокировку POSIX для открытого файлового дескриптора. fd — открытый файловый дескриптор. cmd задаёт команду — одну из F_LOCK, F_TLOCK, F_ULOCK или F_TEST. len задаёт участок файла, который нужно заблокировать.

Вызывает событие аудита os.lockf с аргументами fd, cmd, len.

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

Добавлено в версии 3.3.

os.F_LOCK

os.F_TLOCK

os.F_ULOCK

os.F_TEST

Флаги, задающие действие, которое выполнит lockf().

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

Добавлено в версии 3.3.

os.login_tty(fd, /)

Подготовить tty, файловым дескриптором которого является fd, к новому сеансу входа в систему. Сделать вызывающий процесс лидером сеанса; назначить tty управляющим терминалом, stdin, stdout и stderr вызывающего процесса; закрыть fd.

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.11.

os.lseek(fd, pos, whence, /)

Установить текущую позицию файлового дескриптора fd в позицию pos с поправкой на whence и вернуть новую позицию в байтах относительно начала файла. Допустимые значения whence:

• SEEK_SET или 0 — установить pos относительно начала файла
• SEEK_CUR или 1 — установить pos относительно текущей позиции в файле
• SEEK_END или 2 — установить pos относительно конца файла
• SEEK_HOLE — установить pos на следующее местоположение данных относительно pos
• SEEK_DATA — установить pos на следующую файловую дыру относительно pos

Изменено в версии 3.3: Добавлена поддержка SEEK_HOLE и SEEK_DATA.

os.SEEK_SET

os.SEEK_CUR

os.SEEK_END

Параметры функции lseek() и метода seek() файловых объектов, задающие смещение указателя позиции в файле.

SEEK_SET

Скорректировать позицию в файле относительно его начала.

SEEK_CUR

Скорректировать позицию в файле относительно текущей позиции.

SEEK_END

Скорректировать позицию в файле относительно его конца.

Их значения соответственно равны 0, 1 и 2.

os.SEEK_HOLE

os.SEEK_DATA

Параметры функции lseek() и метода seek() файловых объектов, предназначенные для поиска данных и дыр в файлах с разреженным выделением места.

SEEK_DATA

Скорректировать смещение файла до следующего местоположения, содержащего данные, относительно позиции поиска.

SEEK_HOLE

Скорректировать смещение файла до следующего местоположения, содержащего дыру, относительно позиции поиска. Дыра определяется как последовательность нулей.

Примечание

Эти операции имеют смысл только для файловых систем, которые их поддерживают.

Доступность: Linux >= 3.1, macOS, Unix

Добавлено в версии 3.3.

os.open(path, flags, mode=0o777, *, dir_fd=None)

Открыть файл path и установить различные флаги согласно flags, а при необходимости — его режим согласно mode. При вычислении mode сначала исключается текущее значение umask. Вернуть файловый дескриптор только что открытого файла. Новый файловый дескриптор не наследуется.

Описание значений флагов и режима см. в документации среды выполнения C; константы флагов (например, O_RDONLY и O_WRONLY) определены в модуле os. В частности, в Windows для открытия файлов в двоичном режиме необходимо добавить O_BINARY.

Эта функция поддерживает пути относительно файловых дескрипторов каталогов с помощью параметра dir_fd.

Вызывает событие аудита open с аргументами path, mode, flags.

Изменено в версии 3.4: Теперь новый файловый дескриптор не наследуется.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода. Для обычного использования воспользуйтесь встроенной функцией open(), которая возвращает файловый объект с методами read() и write() (и многими другими). Чтобы обернуть файловый дескриптор в файловый объект, используйте fdopen().

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, функция теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (обоснование см. в PEP 475).

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

Следующие константы являются допустимыми значениями параметра flags функции open(). Их можно объединять с помощью побитового оператора ИЛИ |. Некоторые из них доступны не на всех платформах. Сведения об их доступности и использовании см. на странице руководства open(2) для Unix или в MSDN для Windows.

os.O_RDONLY

os.O_WRONLY

os.O_RDWR

os.O_APPEND

os.O_CREAT

os.O_EXCL

os.O_TRUNC

Указанные выше константы доступны в Unix и Windows.

os.O_DSYNC

os.O_RSYNC

os.O_SYNC

os.O_NDELAY

os.O_NONBLOCK

os.O_NOCTTY

os.O_CLOEXEC

Указанные выше константы доступны только в Unix.

Изменено в версии 3.3: Добавлена константа O_CLOEXEC.

os.O_BINARY

os.O_NOINHERIT

os.O_SHORT_LIVED

os.O_TEMPORARY

os.O_RANDOM

os.O_SEQUENTIAL

os.O_TEXT

Указанные выше константы доступны только в Windows.

os.O_EVTONLY

os.O_FSYNC

os.O_SYMLINK

os.O_NOFOLLOW_ANY

Указанные выше константы доступны только в macOS.

Изменено в версии 3.10: Добавлены константы O_EVTONLY, O_FSYNC, O_SYMLINK и O_NOFOLLOW_ANY.

os.O_ASYNC

os.O_DIRECT

os.O_DIRECTORY

os.O_NOFOLLOW

os.O_NOATIME

os.O_PATH

os.O_TMPFILE

os.O_SHLOCK

os.O_EXLOCK

Указанные выше константы являются расширениями и отсутствуют, если они не определены библиотекой C.

Изменено в версии 3.4: Добавлена O_PATH в системах, которые её поддерживают. Добавлена O_TMPFILE, доступная только в ядре Linux версии 3.11 или новее.

os.openpty()

Открывает новую пару псевдотерминалов. Возвращает пару файловых дескрипторов (master, slave) для pty и tty соответственно. Новые файловые дескрипторы не наследуются. Для (несколько) более переносимого подхода используйте модуль pty.

Доступность: Unix, кроме Emscripten и WASI.

Изменено в версии 3.4: Теперь новые файловые дескрипторы не наследуются.

os.pipe()

Создаёт канал. Возвращает пару файловых дескрипторов (r, w), предназначенных соответственно для чтения и записи. Новый файловый дескриптор не наследуется.

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

Изменено в версии 3.4: Теперь новые файловые дескрипторы не наследуются.

os.pipe2(flags, /)

Создаёт канал, атомарно устанавливая flags. Значение flags можно получить, объединив операцией OR один или несколько следующих флагов: O_NONBLOCK, O_CLOEXEC. Возвращает пару файловых дескрипторов (r, w), предназначенных соответственно для чтения и записи.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.3.

os.posix_fallocate(fd, offset, len, /)

Гарантирует выделение достаточного места на диске для файла, указанного в fd, начиная с offset и на протяжении len байт.

Доступность: Unix, кроме Emscripten.

Добавлено в версии 3.3.

os.posix_fadvise(fd, offset, len, advice, /)

Сообщает о предполагаемом шаблоне доступа к данным, позволяя ядру выполнить оптимизацию. Рекомендация применяется к области файла, указанной в fd, начиная с offset и на протяжении len байт. advice — одно из значений POSIX_FADV_NORMAL, POSIX_FADV_SEQUENTIAL, POSIX_FADV_RANDOM, POSIX_FADV_NOREUSE, POSIX_FADV_WILLNEED или POSIX_FADV_DONTNEED.

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

Добавлено в версии 3.3.

os.POSIX_FADV_NORMAL

os.POSIX_FADV_SEQUENTIAL

os.POSIX_FADV_RANDOM

os.POSIX_FADV_NOREUSE

os.POSIX_FADV_WILLNEED

os.POSIX_FADV_DONTNEED

Флаги, которые можно использовать в качестве advice в posix_fadvise() для указания предполагаемого шаблона доступа.

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

Добавлено в версии 3.3.

os.pread(fd, n, offset, /)

Считывает не более n байт из файлового дескриптора fd с позиции offset, не изменяя смещение файла.

Возвращает байтовую строку, содержащую прочитанные байты. Если достигнут конец файла, на который ссылается fd, возвращается пустой объект bytes.

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

Добавлено в версии 3.3.

os.preadv(fd, buffers, offset, flags=0, /)

Считывает данные из файлового дескриптора fd с позиции offset в изменяемые объекты, подобные байтам buffers, не изменяя смещение файла. Данные считываются в каждый буфер до его заполнения, после чего для сохранения оставшихся данных используется следующий буфер в последовательности.

Аргумент flags содержит побитовое ИЛИ нуля или более следующих флагов:

• RWF_HIPRI
• RWF_NOWAIT

Возвращает общее количество фактически прочитанных байт, которое может быть меньше суммарной ёмкости всех объектов.

Операционная система может установить ограничение (sysconf(), значение 'SC_IOV_MAX') на количество используемых буферов.

Объединяет функциональность os.readv() и os.pread().

Доступность: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Для использования флагов требуется Linux >= 4.6.

Добавлено в версии 3.7.

os.RWF_NOWAIT

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

Если удалось прочитать какие-либо данные, будет возвращено количество прочитанных байт. Если байты прочитать не удалось, будет возвращено -1, а errno будет установлено в errno.EAGAIN.

Доступность: Linux >= 4.14.

Добавлено в версии 3.7.

os.RWF_HIPRI

Чтение/запись с высоким приоритетом. Позволяет файловым системам, работающим с блочными устройствами, использовать опрос устройства, что снижает задержку, но может потребовать дополнительных ресурсов.

В настоящее время в Linux эта возможность применима только к файловому дескриптору, открытому с флагом O_DIRECT.

Доступность: Linux >= 4.6.

Добавлено в версии 3.7.

os.pwrite(fd, str, offset, /)

Записывает байтовую строку из str в файловый дескриптор fd с позиции offset, не изменяя смещение файла.

Возвращает количество фактически записанных байт.

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

Добавлено в версии 3.3.

os.pwritev(fd, buffers, offset, flags=0, /)

Записывает содержимое buffers в файловый дескриптор fd со смещения offset, не изменяя смещение файла. buffers должен быть последовательностью объектов, подобных байтам. Буферы обрабатываются в порядке следования в массиве. Сначала записывается всё содержимое первого буфера, затем второго и так далее.

Аргумент flags содержит побитовое ИЛИ нуля или более следующих флагов:

• RWF_DSYNC
• RWF_SYNC
• RWF_APPEND

Возвращает общее количество фактически записанных байт.

Операционная система может установить ограничение (sysconf(), значение 'SC_IOV_MAX') на количество используемых буферов.

Объединяет функциональность os.writev() и os.pwrite().

Доступность: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Для использования флагов требуется Linux >= 4.6.

Добавлено в версии 3.7.

os.RWF_DSYNC

Обеспечивает эквивалент флага O_DSYNC функции os.open() для отдельной операции записи. Действие этого флага распространяется только на диапазон данных, записываемый системным вызовом.

Доступность: Linux >= 4.7.

Добавлено в версии 3.7.

os.RWF_SYNC

Обеспечивает эквивалент флага O_SYNC функции os.open() для отдельной операции записи. Действие этого флага распространяется только на диапазон данных, записываемый системным вызовом.

Доступность: Linux >= 4.7.

Добавлено в версии 3.7.

os.RWF_APPEND

Обеспечивает эквивалент флага O_APPEND функции os.open() для отдельной операции записи. Этот флаг имеет смысл только для os.pwritev(), и его действие распространяется только на диапазон данных, записываемый системным вызовом. Аргумент offset не влияет на операцию записи: данные всегда добавляются в конец файла. Однако если аргумент offset равен -1, текущее смещение файла offset обновляется.

Доступность: Linux >= 4.16.

Добавлено в версии 3.10.

os.read(fd, n, /)

Считывает не более n байт из файлового дескриптора fd.

Возвращает байтовую строку, содержащую прочитанные байты. Если достигнут конец файла, на который ссылается fd, возвращается пустой объект bytes.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода и должна применяться к файловому дескриптору, возвращённому функцией os.open() или pipe(). Чтобы прочитать «файловый объект», возвращённый встроенной функцией open(), функцией popen() или fdopen(), либо sys.stdin, используйте его методы read() или readline().

Изменено в версии 3.5: Если системный вызов прерван, а обработчик сигнала не вызывает исключение, функция теперь повторяет системный вызов вместо вызова исключения InterruptedError (обоснование см. в PEP 475).

os.sendfile(out_fd, in_fd, offset, count)

os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

Копирует count байт из файлового дескриптора in_fd в файловый дескриптор out_fd, начиная с offset. Возвращает количество отправленных байт. При достижении конца файла возвращает 0.

Первая форма вызова поддерживается всеми платформами, на которых определена функция sendfile().

В Linux, если для offset задано значение None, байты считываются с текущей позиции in_fd, а позиция in_fd обновляется.

Вторую форму можно использовать в macOS и FreeBSD, где headers и trailers — произвольные последовательности буферов, записываемые до и после данных из in_fd. Она возвращает то же значение, что и первая форма.

В macOS и FreeBSD значение 0 для count означает, что передача будет продолжаться до достижения конца in_fd.

Все платформы поддерживают сокеты в качестве файлового дескриптора out_fd, а некоторые платформы также допускают другие типы (например, обычный файл или канал).

Кроссплатформенным приложениям не следует использовать аргументы headers, trailers и flags.

Доступность: Unix, кроме Emscripten и WASI.

Примечание

Обёртку более высокого уровня для sendfile() см. в socket.socket.sendfile().

Добавлено в версии 3.3.

Изменено в версии 3.9: Параметры out и in переименованы в out_fd и in_fd.

os.SF_NODISKIO

os.SF_MNOWAIT

os.SF_SYNC

Параметры функции sendfile(), если реализация поддерживает их.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.3.

os.SF_NOCACHE

Параметр функции sendfile(), если реализация поддерживает его. Данные не будут кэшироваться в виртуальной памяти и будут освобождены после использования.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.11.

os.set_blocking(fd, blocking, /)

Устанавливает режим блокировки указанного файлового дескриптора. Устанавливает флаг O_NONBLOCK, если блокирующий режим равен False, и снимает этот флаг в противном случае.

См. также get_blocking() и socket.socket.setblocking().

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

Возможности функции ограничены в Emscripten и WASI. Подробнее см. в разделе Платформы WebAssembly.

Добавлено в версии 3.5.

os.splice(src, dst, count, offset_src=None, offset_dst=None)

Передаёт count байт из файлового дескриптора src, начиная со смещения offset_src, в файловый дескриптор dst, начиная со смещения offset_dst. По крайней мере один из файловых дескрипторов должен ссылаться на канал. Если offset_src равен None, чтение из src выполняется с текущей позиции; то же относится к offset_dst. Смещение, связанное с файловым дескриптором, который ссылается на канал, должно быть равно None. Файлы, на которые указывают src и dst, должны находиться в одной файловой системе, иначе возникает исключение OSError, а errno устанавливается в errno.EXDEV.

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

При успешном выполнении возвращает количество байт, переданных в канал или из него. Возвращаемое значение 0 означает конец входных данных. Если src ссылается на канал, это означает, что данных для передачи нет и блокировка не имеет смысла, поскольку к концу канала для записи не подключено ни одного процесса.

Доступность: Linux >= 2.6.17 с glibc >= 2.5

Добавлено в версии 3.10.

os.SPLICE_F_MOVE

os.SPLICE_F_NONBLOCK

os.SPLICE_F_MORE

Добавлено в версии 3.10.

os.readv(fd, buffers, /)

Считывает данные из файлового дескриптора fd в несколько изменяемых объектов, подобных байтам buffers. Данные считываются в каждый буфер до его заполнения, после чего для сохранения оставшихся данных используется следующий буфер в последовательности.

Возвращает общее количество фактически прочитанных байт, которое может быть меньше суммарной ёмкости всех объектов.

Операционная система может установить ограничение (sysconf(), значение 'SC_IOV_MAX') на количество используемых буферов.

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

Добавлено в версии 3.3.

os.tcgetpgrp(fd, /)

Возвращает группу процессов, связанную с терминалом, указанным в fd (открытый файловый дескриптор, возвращённый функцией os.open()).

Доступность: Unix, кроме WASI.

os.tcsetpgrp(fd, pg, /)

Устанавливает группу процессов, связанную с терминалом, указанным в fd (открытый файловый дескриптор, возвращённый функцией os.open()), в значение pg.

Доступность: Unix, кроме WASI.

os.ttyname(fd, /)

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

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

os.write(fd, str, /)

Записывает байтовую строку из str в файловый дескриптор fd.

Возвращает количество фактически записанных байт.

Примечание

Эта функция предназначена для низкоуровневого ввода-вывода и должна применяться к файловому дескриптору, возвращённому функцией os.open() или pipe(). Чтобы записать данные в «файловый объект», возвращённый встроенной функцией open(), функцией popen() или fdopen(), либо sys.stdout или sys.stderr, используйте его метод write().

Изменено в версии 3.5: Если системный вызов прерван, а обработчик сигнала не вызывает исключение, функция теперь повторяет системный вызов вместо вызова исключения InterruptedError (обоснование см. в PEP 475).

os.writev(fd, buffers, /)

Записывает содержимое buffers в файловый дескриптор fd. buffers должен быть последовательностью объектов, подобных байтам. Буферы обрабатываются в порядке следования в массиве. Сначала записывается всё содержимое первого буфера, затем второго и так далее.

Возвращает общее количество фактически записанных байт.

Операционная система может установить ограничение (sysconf(), значение 'SC_IOV_MAX') на количество используемых буферов.

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

Добавлено в версии 3.3.

Файлы и каталоги

На некоторых платформах Unix многие из этих функций поддерживают одну или несколько следующих возможностей:

• указание файлового дескриптора: Обычно аргумент path, передаваемый функциям модуля os, должен быть строкой, указывающей путь к файлу. Однако некоторые функции теперь также принимают в качестве аргумента path открытый файловый дескриптор. В этом случае функция работает с файлом, на который указывает дескриптор. (В системах POSIX Python вызовет вариант функции с префиксом f (например, вызовет fchdir вместо chdir).)

  Проверить, можно ли на вашей платформе задать path как файловый дескриптор для конкретной функции, можно с помощью os.supports_fd. Если эта возможность недоступна, ее использование вызовет исключение NotImplementedError.

  Если функция также поддерживает аргументы dir_fd или follow_symlinks, указывать один из них при передаче path в качестве файлового дескриптора нельзя.

• пути относительно дескрипторов каталогов: Если dir_fd не равен None, он должен быть файловым дескриптором, указывающим на каталог, а путь, с которым нужно выполнить операцию, должен быть относительным; в этом случае путь будет отсчитываться от этого каталога. Если путь абсолютный, dir_fd игнорируется. (В системах POSIX Python вызовет вариант функции с суффиксом at и, возможно, префиксом f (например, вызовет faccessat вместо access).

  Проверить, поддерживается ли dir_fd для конкретной функции на вашей платформе, можно с помощью os.supports_dir_fd. Если эта возможность недоступна, ее использование вызовет исключение NotImplementedError.

• без перехода по символическим ссылкам: Если follow_symlinks равен False и последний элемент пути, с которым нужно выполнить операцию, является символической ссылкой, функция будет работать с самой символической ссылкой, а не с файлом, на который она указывает. (В системах POSIX Python вызовет вариант функции l....)

  Проверить, поддерживается ли follow_symlinks для конкретной функции на вашей платформе, можно с помощью os.supports_follow_symlinks. Если эта возможность недоступна, ее использование вызовет исключение NotImplementedError.

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

Проверяет доступ к path с использованием реальных uid/gid. Обратите внимание: большинство операций используют эффективные uid/gid, поэтому эту функцию можно применять в среде suid/sgid, чтобы проверить, имеет ли вызывающий пользователь указанный доступ к path. Для проверки существования path параметр mode должен быть равен F_OK; для проверки прав доступа ему можно присвоить побитовое ИЛИ одной или нескольких констант: R_OK, W_OK и X_OK. Возвращает True, если доступ разрешен, и False в противном случае. Дополнительные сведения см. на странице руководства Unix access(2).

Эта функция может поддерживать пути относительно дескрипторов каталогов и работу без перехода по символическим ссылкам.

Если effective_ids равен True, access() будет выполнять проверки доступа с использованием эффективных uid/gid вместо реальных uid/gid. Параметр effective_ids может не поддерживаться на вашей платформе; проверить его доступность можно с помощью os.supports_effective_ids. Если эта возможность недоступна, ее использование вызовет исключение NotImplementedError.

Примечание

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

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

лучше записать так:

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

Примечание

Операции ввода-вывода могут завершиться ошибкой, даже если access() сообщает, что они должны пройти успешно. Это особенно касается операций с сетевыми файловыми системами, семантика прав доступа в которых может выходить за рамки стандартной модели битов разрешений POSIX.

Изменено в версии 3.3: Добавлены параметры dir_fd, effective_ids и follow_symlinks.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.F_OK

os.R_OK

os.W_OK

os.X_OK

Значения, передаваемые как параметр mode функции access() для проверки существования, доступности для чтения, записи и выполнения path соответственно.

os.chdir(path)

Изменяет текущий рабочий каталог на path.

Эта функция может поддерживать указание файлового дескриптора. Дескриптор должен указывать на открытый каталог, а не на открытый файл.

Эта функция может вызывать OSError и его подклассы, такие как FileNotFoundError, PermissionError и NotADirectoryError.

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

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

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.chflags(path, flags, *, follow_symlinks=True)

Устанавливает для path флаги, заданные числовым значением flags. Параметр flags может представлять собой комбинацию (побитовое ИЛИ) следующих значений (определенных в модуле stat):

• stat.UF_NODUMP
• stat.UF_IMMUTABLE
• stat.UF_APPEND
• stat.UF_OPAQUE
• stat.UF_NOUNLINK
• stat.UF_COMPRESSED
• stat.UF_HIDDEN
• stat.SF_ARCHIVED
• stat.SF_IMMUTABLE
• stat.SF_APPEND
• stat.SF_NOUNLINK
• stat.SF_SNAPSHOT

Эта функция может поддерживать работу без перехода по символическим ссылкам.

Вызывает событие аудита os.chflags с аргументами path, flags.

Доступность: Unix, кроме Emscripten и WASI.

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

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)

Изменяет режим доступа к path, задавая его числовым значением mode. Параметр mode может принимать одно из следующих значений (определенных в модуле stat) или их побитовую комбинацию:

• stat.S_ISUID
• stat.S_ISGID
• stat.S_ENFMT
• stat.S_ISVTX
• stat.S_IREAD
• stat.S_IWRITE
• stat.S_IEXEC
• stat.S_IRWXU
• stat.S_IRUSR
• stat.S_IWUSR
• stat.S_IXUSR
• stat.S_IRWXG
• stat.S_IRGRP
• stat.S_IWGRP
• stat.S_IXGRP
• stat.S_IRWXO
• stat.S_IROTH
• stat.S_IWOTH
• stat.S_IXOTH

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

Примечание

Хотя Windows поддерживает chmod(), с ее помощью можно установить только флаг файла «только для чтения» (с помощью констант stat.S_IWRITE и stat.S_IREAD или соответствующего целочисленного значения). Все остальные биты игнорируются.

Возможности функции в Emscripten и WASI ограничены. Дополнительные сведения см. в разделе Платформы WebAssembly.

Вызывает событие аудита os.chmod с аргументами path, mode, dir_fd.

Добавлено в версии 3.3: Добавлена поддержка указания path в качестве открытого файлового дескриптора, а также аргументов dir_fd и follow_symlinks.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)

Изменяет идентификаторы владельца и группы для path, задавая их числовыми значениями uid и gid. Чтобы не изменять один из идентификаторов, задайте для него значение -1.

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

Функция более высокого уровня, принимающая имена, а также числовые идентификаторы, описана в shutil.chown().

Вызывает событие аудита os.chown с аргументами path, uid, gid, dir_fd.

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

Возможности функции в Emscripten и WASI ограничены. Дополнительные сведения см. в разделе Платформы WebAssembly.

Добавлено в версии 3.3: Добавлена поддержка указания path в качестве открытого файлового дескриптора, а также аргументов dir_fd и follow_symlinks.

Изменено в версии 3.6: Поддерживает объект, поддерживающий интерфейс путей.

os.chroot(path)

Изменяет корневой каталог текущего процесса на path.

Доступность: Unix, кроме Emscripten и WASI.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.fchdir(fd)

Изменяет текущий рабочий каталог на каталог, представленный файловым дескриптором fd. Дескриптор должен указывать на открытый каталог, а не на открытый файл. Начиная с Python 3.3 эта функция эквивалентна os.chdir(fd).

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

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

os.getcwd()

Возвращает строку, представляющую текущий рабочий каталог.

os.getcwdb()

Возвращает байтовую строку, представляющую текущий рабочий каталог.

Изменено в версии 3.8: В Windows функция теперь использует кодировку UTF-8 вместо кодовой страницы ANSI. Обоснование см. в PEP 529. Функция больше не является устаревшей в Windows.

os.lchflags(path, flags)

Устанавливает для path флаги, заданные числовым значением flags, как и chflags(), но не переходит по символическим ссылкам. Начиная с Python 3.3 эта функция эквивалентна os.chflags(path, flags, follow_symlinks=False).

Вызывает событие аудита os.chflags с аргументами path, flags.

Доступность: Unix, кроме Emscripten и WASI.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.lchmod(path, mode)

Изменяет режим доступа к path, задавая его числовым значением mode. Если path является символической ссылкой, изменяется сама ссылка, а не целевой объект. Возможные значения mode см. в документации к chmod(). Начиная с Python 3.3 эта функция эквивалентна os.chmod(path, mode, follow_symlinks=False).

lchmod() не входит в POSIX, но может поддерживаться реализациями Unix, если они позволяют изменять режим доступа к символическим ссылкам.

Вызывает событие аудита os.chmod с аргументами path, mode, dir_fd.

Доступность: Unix, кроме Linux, FreeBSD >= 1.3, NetBSD >= 1.3 и OpenBSD

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.lchown(path, uid, gid)

Изменяет идентификаторы владельца и группы для path, задавая их числовыми значениями uid и gid. Эта функция не переходит по символическим ссылкам. Начиная с Python 3.3 эта функция эквивалентна os.chown(path, uid, gid, follow_symlinks=False).

Вызывает событие аудита os.chown с аргументами path, uid, gid, dir_fd.

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

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)

Создает жесткую ссылку с именем dst, указывающую на src.

Эта функция может поддерживать параметры src_dir_fd и/или dst_dir_fd для задания путей относительно дескрипторов каталогов, а также работу без перехода по символическим ссылкам.

Вызывает событие аудита os.link с аргументами src, dst, src_dir_fd, dst_dir_fd.

Доступность: Unix, Windows, кроме Emscripten.

Изменено в версии 3.2: Добавлена поддержка Windows.

Изменено в версии 3.3: Добавлены параметры src_dir_fd, dst_dir_fd и follow_symlinks.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей для параметров src и dst.

os.listdir(path='.')

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

path может быть объектом, поддерживающим интерфейс путей. Если path имеет тип bytes (непосредственно или косвенно через интерфейс PathLike), возвращаемые имена файлов также будут иметь тип bytes; во всех остальных случаях они будут иметь тип str.

Эта функция также может поддерживать указание файлового дескриптора; файловый дескриптор должен указывать на каталог.

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

Примечание

Для кодирования имен файлов str в bytes используйте fsencode().

См. также

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

Изменено в версии 3.2: Параметр path стал необязательным.

Добавлено в версии 3.3: Добавлена поддержка указания path в качестве открытого файлового дескриптора.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

os.lstat(path, *, dir_fd=None)

Выполняет эквивалент системного вызова lstat() для указанного пути. Подобно stat(), но не переходит по символическим ссылкам. Возвращает объект stat_result.

На платформах, не поддерживающих символические ссылки, эта функция является псевдонимом stat().

Начиная с Python 3.3 эта функция эквивалентна os.stat(path, dir_fd=dir_fd, follow_symlinks=False).

Эта функция также может поддерживать пути относительно дескрипторов каталогов.

См. также

Функция stat().

Изменено в версии 3.2: Добавлена поддержка символических ссылок Windows 6.0 (Vista).

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: Принимает объект, поддерживающий интерфейс путей.

Изменено в версии 3.8: В Windows функция теперь открывает точки повторной обработки, представляющие другой путь (подстановки имен), в том числе символические ссылки и соединения каталогов. Другие типы точек повторной обработки обрабатываются операционной системой так же, как и в случае stat().

os.mkdir(path, mode=0o777, *, dir_fd=None)

Создаёт каталог с именем path и числовым режимом mode.

Если каталог уже существует, возникает исключение FileExistsError. Если родительский каталог в пути не существует, возникает исключение FileNotFoundError.

В некоторых системах параметр mode игнорируется. Там, где он используется, сначала из него исключается текущее значение umask. Если установлены биты, отличные от последних 9 (то есть последних 3 цифр восьмеричного представления mode), их значение зависит от платформы. На некоторых платформах они игнорируются, и для их явной установки следует вызвать chmod().

В Windows значение mode 0o700 обрабатывается особым образом: для нового каталога применяются ограничения доступа, позволяющие доступ только текущему пользователю и администраторам. Другие значения mode игнорируются.

Эта функция также может поддерживать пути относительно дескрипторов каталогов.

Также можно создавать временные каталоги; см. функцию tempfile.mkdtemp() модуля tempfile.

Вызывает событие аудита os.mkdir с аргументами path, mode, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

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

Изменено в версии 3.11.10: В Windows теперь обрабатывается значение mode 0o700.

os.makedirs(name, mode=0o777, exist_ok=False)

Функция рекурсивного создания каталогов. Подобно mkdir(), но создаёт все промежуточные каталоги, необходимые для размещения конечного каталога.

Параметр mode передаётся в mkdir() для создания конечного каталога; см. описание mkdir(), где объясняется его интерпретация. Чтобы задать биты разрешений для файлов во вновь созданных родительских каталогах, перед вызовом makedirs() можно установить umask. Биты разрешений для файлов в существующих родительских каталогах не изменяются.

Если exist_ok имеет значение False (по умолчанию), возникает исключение FileExistsError, если целевой каталог уже существует.

Примечание

makedirs() может работать некорректно, если элементы пути, которые нужно создать, содержат pardir (например, «..» в системах UNIX).

Эта функция корректно обрабатывает пути UNC.

Вызывает событие аудита os.mkdir с аргументами path, mode, dir_fd.

Изменено в версии 3.2: Добавлен параметр exist_ok.

Изменено в версии 3.4.1: До Python 3.4.1, если exist_ok имел значение True и каталог существовал, makedirs() всё равно вызывала ошибку, если значение mode не совпадало с режимом существующего каталога. Поскольку безопасно реализовать такое поведение было невозможно, в Python 3.4.1 его убрали. См. bpo-21082.

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

Изменено в версии 3.7: Аргумент mode больше не влияет на биты разрешений для файлов во вновь созданных промежуточных каталогах.

os.mkfifo(path, mode=0o666, *, dir_fd=None)

Создаёт FIFO (именованный канал) с именем path и числовым режимом mode. Сначала из режима исключается текущее значение umask.

Эта функция также может поддерживать пути относительно дескрипторов каталогов.

FIFO — это каналы, к которым можно обращаться как к обычным файлам. FIFO существуют, пока их не удалят (например, с помощью os.unlink()). Обычно FIFO используются для организации взаимодействия между процессами типа «клиент» и «сервер»: сервер открывает FIFO для чтения, а клиент — для записи. Обратите внимание, что mkfifo() не открывает FIFO — она лишь создаёт точку взаимодействия.

Доступность: Unix, не Emscripten, не WASI.

Изменено в версии 3.3: Добавлен параметр dir_fd.

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

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)

Создаёт узел файловой системы (файл, специальный файл устройства или именованный канал) с именем path. Параметр mode задаёт и разрешения, и тип создаваемого узла, объединяя их (побитовым ИЛИ) с одним из значений stat.S_IFREG, stat.S_IFCHR, stat.S_IFBLK и stat.S_IFIFO (эти константы доступны в stat). Для stat.S_IFCHR и stat.S_IFBLK параметр device задаёт создаваемый специальный файл устройства (вероятно, с использованием os.makedev()), в противном случае он игнорируется.

Эта функция также может поддерживать пути относительно дескрипторов каталогов.

Доступность: Unix, не Emscripten, не WASI.

Изменено в версии 3.3: Добавлен параметр dir_fd.

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

os.major(device, /)

Извлекает старший номер устройства из необработанного номера устройства (обычно поля st_dev или st_rdev из stat).

os.minor(device, /)

Извлекает младший номер устройства из необработанного номера устройства (обычно поля st_dev или st_rdev из stat).

os.makedev(major, minor, /)

Составляет необработанный номер устройства из старшего и младшего номеров устройства.

os.pathconf(path, name)

Возвращает сведения о конфигурации системы, относящиеся к файлу с заданным именем. Параметр name задаёт извлекаемое значение конфигурации; это может быть строка с именем определённого системного значения. Эти имена указаны в ряде стандартов (POSIX.1, Unix 95, Unix 98 и других). Некоторые платформы определяют также дополнительные имена. Имена, известные операционной системе узла, указаны в словаре pathconf_names. Для переменных конфигурации, не включённых в это отображение, в качестве name также можно передать целое число.

Если name — строка с неизвестным именем, возникает исключение ValueError. Если определённое значение name не поддерживается системой узла, даже если оно включено в pathconf_names, возникает исключение OSError, а в качестве номера ошибки указывается errno.EINVAL.

Эта функция может поддерживать указание файлового дескриптора.

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

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

os.pathconf_names

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

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

os.readlink(path, *, dir_fd=None)

Возвращает строку, представляющую путь, на который указывает символическая ссылка. Результатом может быть абсолютный или относительный путь; если путь относительный, его можно преобразовать в абсолютный с помощью os.path.join(os.path.dirname(path), result).

Если path — строковый объект (непосредственно или косвенно через интерфейс PathLike), результат также будет строковым объектом, а вызов может вызвать UnicodeDecodeError. Если path — объект bytes (непосредственно или косвенно), результатом будет объект bytes.

Эта функция также может поддерживать пути относительно дескрипторов каталогов.

Для разрешения пути, который может содержать ссылки, используйте realpath(), чтобы корректно обрабатывать рекурсию и различия между платформами.

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

Изменено в версии 3.2: Добавлена поддержка символических ссылок Windows 6.0 (Vista).

Изменено в версии 3.3: Добавлен параметр dir_fd.

Изменено в версии 3.6: В Unix принимает объект, подобный пути.

Изменено в версии 3.8: В Windows принимает объект, подобный пути и объект bytes.

Добавлена поддержка точек соединения каталогов; теперь возвращается путь подстановки (обычно содержащий префикс \\?\), а не необязательное поле «отображаемого имени», возвращавшееся ранее.

os.remove(path, *, dir_fd=None)

Удаляет файл path. Если path — каталог, возникает исключение OSError. Для удаления каталогов используйте rmdir(). Если файл не существует, возникает исключение FileNotFoundError.

Эта функция может поддерживать пути относительно дескрипторов каталогов.

В Windows попытка удалить используемый файл приводит к исключению; в Unix запись каталога удаляется, но выделенное файлу пространство не освобождается, пока файл используется.

Эта функция семантически идентична unlink().

Вызывает событие аудита os.remove с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

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

os.removedirs(name)

Рекурсивно удаляет каталоги. Работает как rmdir(), но после успешного удаления конечного каталога функция removedirs() пытается последовательно удалить все родительские каталоги, указанные в path, до возникновения ошибки (которая игнорируется, поскольку обычно означает, что родительский каталог не пуст). Например, os.removedirs('foo/bar/baz') сначала удалит каталог 'foo/bar/baz', а затем удалит 'foo/bar' и 'foo', если они пусты. Если конечный каталог не удалось удалить, возникает исключение OSError.

Вызывает событие аудита os.remove с аргументами path, dir_fd.

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

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Переименовывает файл или каталог src в dst. Если dst существует, во многих случаях операция завершится ошибкой — возникнет исключение, являющееся подклассом OSError:

В Windows, если dst существует, всегда возникает исключение FileExistsError. Операция может завершиться ошибкой, если src и dst находятся в разных файловых системах. Для перемещения в другую файловую систему используйте shutil.move().

В Unix, если src — файл, а dst — каталог, или наоборот, возникнет соответственно исключение IsADirectoryError или NotADirectoryError. Если оба объекта — каталоги и dst пуст, он будет заменён без уведомления. Если dst — непустой каталог, возникает исключение OSError. Если оба объекта — файлы, dst будет заменён без уведомления, если у пользователя есть соответствующие разрешения. В некоторых вариантах Unix операция может завершиться ошибкой, если src и dst находятся в разных файловых системах. В случае успеха переименование будет атомарной операцией (это требование POSIX).

Эта функция поддерживает указание src_dir_fd и/или dst_dir_fd для передачи путей относительно дескрипторов каталогов.

Для перезаписи целевого объекта на всех платформах используйте replace().

Вызывает событие аудита os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

Изменено в версии 3.3: Добавлены параметры src_dir_fd и dst_dir_fd.

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

os.renames(old, new)

Функция рекурсивного переименования каталогов или файлов. Работает как rename(), но сначала пытается создать все промежуточные каталоги, необходимые для корректного нового пути. После переименования каталоги, соответствующие крайним правым сегментам старого имени, удаляются с помощью removedirs().

Примечание

Эта функция может завершиться ошибкой, оставив новую структуру каталогов, если у вас нет разрешений, необходимых для удаления конечного каталога или файла.

Вызывает событие аудита os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

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

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Переименовывает файл или каталог src в dst. Если dst — непустой каталог, возникает исключение OSError. Если dst существует и является файлом, он будет заменён без уведомления, если у пользователя есть соответствующие разрешения. Операция может завершиться ошибкой, если src и dst находятся в разных файловых системах. В случае успеха переименование будет атомарной операцией (это требование POSIX).

Эта функция поддерживает указание src_dir_fd и/или dst_dir_fd для передачи путей относительно дескрипторов каталогов.

Вызывает событие аудита os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

Добавлено в версии 3.3.

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

os.rmdir(path, *, dir_fd=None)

Удаляет каталог path. Если каталог не существует или не пуст, возникает соответственно исключение FileNotFoundError или OSError. Для удаления деревьев каталогов можно использовать shutil.rmtree().

Эта функция может поддерживать пути относительно дескрипторов каталогов.

Вызывает событие аудита os.rmdir с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

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

os.scandir(path='.')

Возвращает итератор объектов os.DirEntry, соответствующих элементам каталога, заданного параметром path. Элементы выдаются в произвольном порядке; специальные элементы '.' и '..' не включаются. Если после создания итератора файл удалён из каталога или добавлен в него, наличие записи для этого файла не определено.

Использование scandir() вместо listdir() может значительно повысить производительность кода, которому также нужны сведения о типе файла или его атрибутах: объекты os.DirEntry предоставляют эти сведения, если операционная система возвращает их при сканировании каталога. Все методы os.DirEntry могут выполнять системный вызов, однако is_dir() и is_file() обычно требуют системного вызова только для символических ссылок; os.DirEntry.stat() всегда требует системного вызова в Unix, но в Windows — только для символических ссылок.

path может быть объектом, подобным пути. Если тип path — bytes (непосредственно или косвенно через интерфейс PathLike), тип атрибутов name и path каждого объекта os.DirEntry будет bytes; во всех остальных случаях их типом будет str.

Эта функция также может поддерживать указание файлового дескриптора; файловый дескриптор должен относиться к каталогу.

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

Итератор scandir() поддерживает протокол менеджера контекста и имеет следующий метод:

scandir.close()

Закрывает итератор и освобождает полученные ресурсы.

Этот метод вызывается автоматически, когда итератор исчерпан или удалён сборщиком мусора, а также при возникновении ошибки во время итерации. Тем не менее рекомендуется вызывать его явно или использовать инструкцию with.

Добавлено в версии 3.6.

В следующем примере показано простое использование scandir() для вывода всех файлов (за исключением каталогов) в заданном path, имена которых не начинаются с '.'. Вызов entry.is_file() обычно не приводит к дополнительному системному вызову:

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

Примечание

В Unix-подобных системах scandir() использует системные функции opendir() и readdir(). В Windows используются функции Win32 FindFirstFileW и FindNextFileW.

Добавлено в версии 3.5.

Изменено в версии 3.6: Добавлена поддержка протокола менеджера контекста и метода close(). Если итератор scandir() не исчерпан и явно не закрыт, при его уничтожении будет выдано предупреждение ResourceWarning.

Функция принимает объект, подобный пути.

Изменено в версии 3.7: В Unix добавлена поддержка файловых дескрипторов.

class os.DirEntry

Объект, возвращаемый scandir(), чтобы предоставить путь к файлу и другие атрибуты файловой записи каталога.

scandir() предоставит как можно больше этой информации, не выполняя дополнительных системных вызовов. При выполнении системного вызова stat() или lstat() объект os.DirEntry кэширует результат.

Экземпляры os.DirEntry не предназначены для хранения в долгоживущих структурах данных; если вы знаете, что метаданные файла изменились, или с момента вызова scandir() прошло много времени, вызовите os.stat(entry.path), чтобы получить актуальную информацию.

Поскольку методы os.DirEntry могут вызывать операционную систему, они также могут возбуждать исключение OSError. Если вам нужен очень точный контроль над ошибками, вы можете перехватить OSError при вызове одного из методов os.DirEntry и обработать его соответствующим образом.

Чтобы объект os.DirEntry можно было непосредственно использовать как объект, подобный пути, он реализует интерфейс PathLike.

Экземпляр os.DirEntry имеет следующие атрибуты и методы:

name

Имя файла записи без пути относительно аргумента path функции scandir().

Атрибут name будет иметь тип bytes, если аргумент path функции scandir() имеет тип bytes, и тип str в противном случае. Используйте fsdecode(), чтобы декодировать имена файлов в байтовом представлении.

path

Полный путь к записи: эквивалентен os.path.join(scandir_path, entry.name), где scandir_path — аргумент path функции scandir(). Путь является абсолютным, только если аргумент path функции scandir() был абсолютным. Если аргумент path функции scandir() был файловым дескриптором, атрибут path совпадает с атрибутом name.

Атрибут path будет иметь тип bytes, если аргумент path функции scandir() имеет тип bytes, и тип str в противном случае. Используйте fsdecode(), чтобы декодировать имена файлов в байтовом представлении.

inode()

Возвращает номер индексного дескриптора записи.

Результат кэшируется в объекте os.DirEntry. Используйте os.stat(entry.path, follow_symlinks=False).st_ino, чтобы получить актуальную информацию.

При первом вызове, когда результат ещё не кэширован, в Windows требуется системный вызов, а в Unix — нет.

is_dir(*, follow_symlinks=True)

Возвращает True, если эта запись является каталогом или символической ссылкой на каталог; возвращает False, если запись является файлом другого типа или указывает на такой файл либо если она больше не существует.

Если follow_symlinks имеет значение False, возвращает True, только если эта запись является каталогом (без перехода по символическим ссылкам); возвращает False, если запись является файлом любого другого типа или больше не существует.

Результат кэшируется в объекте os.DirEntry; для значений follow_symlinks True и False используются отдельные кэши. Вызовите os.stat() вместе с stat.S_ISDIR(), чтобы получить актуальную информацию.

При первом вызове, когда результат ещё не кэширован, в большинстве случаев системный вызов не требуется. В частности, для объектов, не являющихся символическими ссылками, системный вызов не требуется ни в Windows, ни в Unix, за исключением некоторых файловых систем Unix, например сетевых, которые возвращают dirent.d_type == DT_UNKNOWN. Если запись является символической ссылкой, для перехода по ней потребуется системный вызов, если только follow_symlinks не имеет значения False.

Этот метод может возбуждать исключение OSError, например PermissionError, однако исключение FileNotFoundError перехватывается и не возбуждается.

is_file(*, follow_symlinks=True)

Возвращает True, если эта запись является файлом или символической ссылкой на файл; возвращает False, если запись является каталогом или другим объектом, не являющимся файлом, либо указывает на такой объект или если она больше не существует.

Если follow_symlinks имеет значение False, возвращает True, только если эта запись является файлом (без перехода по символическим ссылкам); возвращает False, если запись является каталогом или другим объектом, не являющимся файлом, либо если она больше не существует.

Результат кэшируется в объекте os.DirEntry. Кэширование, выполняемые системные вызовы и возбуждаемые исключения соответствуют описанию is_dir().

is_symlink()

Возвращает True, если эта запись является символической ссылкой (даже если она недействительна); возвращает False, если запись указывает на каталог или файл любого типа либо если она больше не существует.

Результат кэшируется в объекте os.DirEntry. Вызовите os.path.islink(), чтобы получить актуальную информацию.

При первом вызове, когда результат ещё не кэширован, в большинстве случаев системный вызов не требуется. В частности, системный вызов не требуется ни в Windows, ни в Unix, за исключением некоторых файловых систем Unix, например сетевых, которые возвращают dirent.d_type == DT_UNKNOWN.

Этот метод может возбуждать исключение OSError, например PermissionError, однако исключение FileNotFoundError перехватывается и не возбуждается.

stat(*, follow_symlinks=True)

Возвращает объект stat_result для этой записи. По умолчанию этот метод переходит по символическим ссылкам; чтобы получить данные о самой символической ссылке, добавьте аргумент follow_symlinks=False.

В Unix этот метод всегда требует системного вызова. В Windows системный вызов требуется, только если follow_symlinks имеет значение True и запись является точкой повторной обработки (например, символической ссылкой или соединением каталогов).

В Windows атрибуты st_ino, st_dev и st_nlink объекта stat_result всегда равны нулю. Чтобы получить эти атрибуты, вызовите os.stat().

Результат кэшируется в объекте os.DirEntry; для значений follow_symlinks True и False используются отдельные кэши. Вызовите os.stat(), чтобы получить актуальную информацию.

Обратите внимание, что несколько атрибутов и методов os.DirEntry хорошо соответствуют атрибутам и методам pathlib.Path. В частности, атрибут name имеет то же значение, что и методы is_dir(), is_file(), is_symlink() и stat().

Добавлено в версии 3.5.

Изменено в версии 3.6: Добавлена поддержка интерфейса PathLike. Добавлена поддержка путей типа bytes в Windows.

os.stat(path, *, dir_fd=None, follow_symlinks=True)

Получает сведения о файле или файловом дескрипторе. Выполняет эквивалент системного вызова stat() для указанного пути. path можно указать как строку или байты — непосредственно или косвенно через интерфейс PathLike — либо как открытый файловый дескриптор. Возвращает объект stat_result.

Обычно эта функция переходит по символическим ссылкам; чтобы получить сведения о самой символической ссылке, добавьте аргумент follow_symlinks=False или используйте lstat().

Эта функция поддерживает указание файлового дескриптора и отказ от перехода по символическим ссылкам.

В Windows передача follow_symlinks=False отключает переход по всем точкам повторной обработки, замещающим имена, включая символические ссылки и соединения каталогов. Другие типы точек повторной обработки, которые не являются ссылками или которые операционная система не может пройти, открываются непосредственно. При переходе по цепочке из нескольких ссылок это может привести к возврату исходной ссылки вместо объекта, не являющегося ссылкой, который помешал завершить переход. Чтобы в этом случае получить сведения о конечном пути, используйте функцию os.path.realpath(), чтобы разрешить имя пути настолько, насколько это возможно, а затем вызовите lstat() для результата. Это не относится к висячим символическим ссылкам и точкам соединения, которые приводят к обычным исключениям.

Пример:

>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264

См. также

Функции fstat() и lstat().

Изменено в версии 3.3: Добавлены параметры dir_fd и follow_symlinks, позволяющие указывать файловый дескриптор вместо пути.

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

Изменено в версии 3.8: В Windows теперь выполняется переход по всем точкам повторной обработки, которые может разрешить операционная система; передача follow_symlinks=False отключает переход по всем точкам повторной обработки, замещающим имена. Если операционная система достигает точки повторной обработки, по которой не может перейти, stat теперь возвращает сведения об исходном пути, как если бы вместо этого было указано follow_symlinks=False, а не возбуждает ошибку.

class os.stat_result

Объект, атрибуты которого примерно соответствуют элементам структуры stat. Используется как результат функций os.stat(), os.fstat() и os.lstat().

Атрибуты:

st_mode

Режим файла: тип файла и биты режима файла (права доступа).

st_ino

Зависит от платформы, но если значение отлично от нуля, однозначно идентифицирует файл для заданного значения st_dev. Обычно это:

• номер индексного дескриптора в Unix,
• индекс файла в Windows

st_dev

Идентификатор устройства, на котором находится файл.

st_nlink

Количество жёстких ссылок.

st_uid

Идентификатор пользователя — владельца файла.

st_gid

Идентификатор группы владельца файла.

st_size

Размер файла в байтах, если это обычный файл или символическая ссылка. Размер символической ссылки равен длине содержащегося в ней имени пути без завершающего нулевого байта.

Временные метки:

st_atime

Время последнего доступа, выраженное в секундах.

st_mtime

Время последнего изменения содержимого, выраженное в секундах.

st_ctime

Зависит от платформы:

• время последнего изменения метаданных в Unix;
• время создания в Windows, выраженное в секундах.

st_atime_ns

Время последнего доступа, выраженное целым числом наносекунд.

Добавлено в версии 3.3.

st_mtime_ns

Время последнего изменения содержимого, выраженное целым числом наносекунд.

Добавлено в версии 3.3.

st_ctime_ns

Зависит от платформы:

• время последнего изменения метаданных в Unix;
• время создания в Windows, выраженное целым числом наносекунд.

Добавлено в версии 3.3.

Примечание

Точное значение и разрешение атрибутов st_atime, st_mtime и st_ctime зависят от операционной системы и файловой системы. Например, в системах Windows с файловыми системами FAT или FAT32 разрешение st_mtime составляет 2 секунды, а st_atime — только 1 день. Подробности см. в документации операционной системы.

Аналогично, хотя значения st_atime_ns, st_mtime_ns и st_ctime_ns всегда выражены в наносекундах, многие системы не обеспечивают наносекундную точность. В системах, которые обеспечивают такую точность, объект с плавающей запятой, используемый для хранения st_atime, st_mtime и st_ctime, не может сохранить её полностью, поэтому значения будут немного неточными. Если вам нужны точные временные метки, всегда используйте st_atime_ns, st_mtime_ns и st_ctime_ns.

В некоторых системах Unix (например, Linux) также могут быть доступны следующие атрибуты:

st_blocks

Количество выделенных для файла блоков размером 512 байт. Если в файле есть разреженные области, это значение может быть меньше, чем st_size/512.

st_blksize

«Предпочтительный» размер блока для эффективного ввода-вывода в файловой системе. Запись в файл небольшими фрагментами может привести к неэффективной последовательности чтения, изменения и повторной записи.

st_rdev

Тип устройства, если индексный дескриптор относится к устройству.

st_flags

Определяемые пользователем флаги файла.

В других системах Unix (например, FreeBSD) могут быть доступны следующие атрибуты (однако их значения могут заполняться только при обращении к ним от имени суперпользователя):

st_gen

Номер генерации файла.

st_birthtime

Время создания файла.

В Solaris и производных системах также могут быть доступны следующие атрибуты:

st_fstype

Строка, однозначно определяющая тип файловой системы, в которой находится файл.

В системах macOS также могут быть доступны следующие атрибуты:

st_rsize

Фактический размер файла.

st_creator

Создатель файла.

st_type

Тип файла.

В системах Windows также доступны следующие атрибуты:

st_file_attributes

Атрибуты файла Windows: элемент dwFileAttributes структуры BY_HANDLE_FILE_INFORMATION, возвращаемой функцией GetFileInformationByHandle(). См. константы FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE> в модуле stat.

Добавлено в версии 3.5.

st_reparse_tag

Если для st_file_attributes установлен флаг FILE_ATTRIBUTE_REPARSE_POINT, это поле содержит тег, определяющий тип точки повторной обработки. См. константы IO_REPARSE_TAG_* в модуле stat.

Стандартный модуль stat определяет функции и константы, полезные для извлечения информации из структуры stat. (В Windows некоторые элементы заполняются фиктивными значениями.)

Для обеспечения обратной совместимости к экземпляру stat_result также можно обращаться как к кортежу, содержащему не менее 10 целых чисел с наиболее важными (и переносимыми) элементами структуры stat в следующем порядке: st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime. Некоторые реализации могут добавлять дополнительные элементы в конец. Для совместимости с более старыми версиями Python при обращении к stat_result как к кортежу всегда возвращаются целые числа.

Изменено в версии 3.5: Теперь в Windows, если индекс файла доступен, он возвращается как st_ino.

Изменено в версии 3.7: Для Solaris и производных систем добавлен элемент st_fstype.

Изменено в версии 3.8: В Windows добавлен элемент st_reparse_tag.

Изменено в версии 3.8: В Windows элемент st_mode теперь при необходимости определяет специальные файлы как S_IFCHR, S_IFIFO или S_IFBLK.

os.statvfs(path)

Выполняет системный вызов statvfs() для указанного пути. Возвращаемое значение — объект, атрибуты которого описывают файловую систему по указанному пути и соответствуют элементам структуры statvfs, а именно: f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax, f_fsid.

Для битовых флагов атрибута f_flag определены две константы уровня модуля: если установлен ST_RDONLY, файловая система смонтирована только для чтения; если установлен ST_NOSUID, семантика битов setuid/setgid отключена или не поддерживается.

Для систем на основе GNU/glibc определены дополнительные константы уровня модуля: ST_NODEV (запретить доступ к специальным файлам устройств), ST_NOEXEC (запретить выполнение программ), ST_SYNCHRONOUS (немедленно синхронизировать записи), ST_MANDLOCK (разрешить обязательные блокировки в файловой системе), ST_WRITE (запись в файл/каталог/символическую ссылку), ST_APPEND (файл только для добавления), ST_IMMUTABLE (неизменяемый файл), ST_NOATIME (не обновлять время доступа), ST_NODIRATIME (не обновлять время доступа к каталогу), ST_RELATIME (обновлять atime относительно mtime/ctime).

Эта функция поддерживает указание файлового дескриптора.

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

Изменено в версии 3.2: Добавлены константы ST_RDONLY и ST_NOSUID.

Изменено в версии 3.3: Добавлена поддержка указания path в виде открытого файлового дескриптора.

Изменено в версии 3.4: Добавлены константы ST_NODEV, ST_NOEXEC, ST_SYNCHRONOUS, ST_MANDLOCK, ST_WRITE, ST_APPEND, ST_IMMUTABLE, ST_NOATIME, ST_NODIRATIME и ST_RELATIME.

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

Изменено в версии 3.7: Добавлен атрибут f_fsid.

os.supports_dir_fd

Объект set, указывающий, какие функции модуля os принимают открытый файловый дескриптор в качестве параметра dir_fd. На разных платформах доступны разные возможности, и лежащая в основе функциональность, которую Python использует для реализации параметра dir_fd, доступна не на всех поддерживаемых Python платформах. Для согласованности функции, которые могут поддерживать dir_fd, всегда позволяют указывать этот параметр, но вызывают исключение, если функциональность используется там, где она недоступна. (Указание None для dir_fd всегда поддерживается на всех платформах.)

Чтобы проверить, принимает ли определённая функция открытый файловый дескриптор в качестве параметра dir_fd, используйте оператор in для supports_dir_fd. Например, это выражение возвращает True, если os.stat() принимает открытые файловые дескрипторы для dir_fd на локальной платформе:

os.stat in os.supports_dir_fd

В настоящее время параметры dir_fd работают только на платформах Unix; ни один из них не работает в Windows.

Добавлено в версии 3.3.

os.supports_effective_ids

Объект set, указывающий, позволяет ли os.access() указывать True для параметра effective_ids на локальной платформе. (Указание False для effective_ids всегда поддерживается на всех платформах.) Если локальная платформа поддерживает эту возможность, коллекция будет содержать os.access(); в противном случае она будет пустой.

Это выражение возвращает True, если os.access() поддерживает effective_ids=True на локальной платформе:

os.access in os.supports_effective_ids

В настоящее время effective_ids поддерживается только на платформах Unix; в Windows он не работает.

Добавлено в версии 3.3.

os.supports_fd

Объект set, указывающий, какие функции модуля os позволяют указывать параметр path в виде открытого файлового дескриптора на локальной платформе. На разных платформах доступны разные возможности, и лежащая в основе функциональность, которую Python использует для приёма открытых файловых дескрипторов в качестве аргументов path, доступна не на всех поддерживаемых Python платформах.

Чтобы определить, позволяет ли определённая функция указывать открытый файловый дескриптор для параметра path, используйте оператор in для supports_fd. Например, это выражение возвращает True, если os.chdir() принимает открытые файловые дескрипторы для path на вашей локальной платформе:

os.chdir in os.supports_fd

Добавлено в версии 3.3.

os.supports_follow_symlinks

Объект set, указывающий, какие функции модуля os принимают False для параметра follow_symlinks на локальной платформе. На разных платформах доступны разные возможности, и лежащая в основе функциональность, которую Python использует для реализации follow_symlinks, доступна не на всех поддерживаемых Python платформах. Для согласованности функции, которые могут поддерживать follow_symlinks, всегда позволяют указывать этот параметр, но вызывают исключение, если функциональность используется там, где она недоступна. (Указание True для follow_symlinks всегда поддерживается на всех платформах.)

Чтобы проверить, принимает ли определённая функция False для параметра follow_symlinks, используйте оператор in для supports_follow_symlinks. Например, это выражение возвращает True, если при вызове os.stat() на локальной платформе можно указать follow_symlinks=False:

os.stat in os.supports_follow_symlinks

Добавлено в версии 3.3.

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)

Создаёт символическую ссылку с именем dst, указывающую на src.

В Windows символическая ссылка представляет собой либо файл, либо каталог и не меняет свой тип динамически вслед за целью. Если цель существует, тип создаваемой символической ссылки будет соответствовать её типу. В противном случае символическая ссылка будет создана как каталог, если target_is_directory равно True, а иначе — как ссылка на файл (по умолчанию). На платформах, отличных от Windows, параметр target_is_directory игнорируется.

Эта функция может поддерживать пути относительно дескрипторов каталогов.

Примечание

В новых версиях Windows 10 непривилегированные учётные записи могут создавать символические ссылки, если включён режим разработчика. Если режим разработчика недоступен или не включён, требуется привилегия SeCreateSymbolicLinkPrivilege либо запуск процесса от имени администратора.

OSError возбуждается, если функция вызвана непривилегированным пользователем.

Вызывает событие аудита os.symlink с аргументами src, dst, dir_fd.

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

Функция имеет ограничения в Emscripten и WASI; дополнительную информацию см. в разделе Платформы WebAssembly.

Изменено в версии 3.2: Добавлена поддержка символических ссылок в Windows 6.0 (Vista).

Изменено в версии 3.3: Добавлен параметр dir_fd, а также разрешено использование target_is_directory на платформах, отличных от Windows.

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

Изменено в версии 3.8: Добавлена поддержка создания символических ссылок без повышения привилегий в Windows с включённым режимом разработчика.

os.sync()

Принудительно записывает все данные на диск.

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

Добавлено в версии 3.3.

os.truncate(path, length)

Усекает файл, соответствующий path, так, чтобы его размер не превышал length байт.

Эта функция может поддерживать указание файлового дескриптора.

Вызывает событие аудита os.truncate с аргументами path, length.

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

Добавлено в версии 3.3.

Изменено в версии 3.5: Добавлена поддержка Windows

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

os.unlink(path, *, dir_fd=None)

Удаляет файл path. Эта функция семантически идентична remove(); имя unlink — её традиционное название в Unix. Дополнительную информацию см. в документации для remove().

Вызывает событие аудита os.remove с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлен параметр dir_fd.

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

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

Устанавливает время доступа и время изменения файла, указанного в path.

utime() принимает два необязательных параметра: times и ns. Они задают времена, устанавливаемые для path, и используются следующим образом:

• Если указан ns, это должен быть 2-кортеж вида (atime_ns, mtime_ns), где каждый элемент — целое число, выражающее время в наносекундах.
• Если times не равен None, это должен быть 2-кортеж вида (atime, mtime), где каждый элемент — целое число или число с плавающей точкой, выражающее время в секундах.
• Если times равен None и ns не указан, это равносильно указанию ns=(atime_ns, mtime_ns), где оба значения времени соответствуют текущему времени.

Одновременное указание кортежей для times и ns является ошибкой.

Обратите внимание, что точные значения времени, установленные здесь, могут не возвращаться при последующем вызове stat(): это зависит от точности, с которой операционная система записывает время доступа и изменения; см. stat(). Чтобы сохранить точные значения времени, лучше всего использовать поля st_atime_ns и st_mtime_ns объекта результата os.stat() в параметре ns функции utime().

Эта функция может поддерживать указание файлового дескриптора, пути относительно дескрипторов каталогов и отказ от следования по символическим ссылкам.

Вызывает событие аудита os.utime с аргументами path, times, ns, dir_fd.

Изменено в версии 3.3: Добавлена поддержка указания path в виде открытого файлового дескриптора, а также параметров dir_fd, follow_symlinks и ns.

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

os.walk(top, topdown=True, onerror=None, followlinks=False)

Формирует имена файлов в дереве каталогов, обходя его сверху вниз или снизу вверх. Для каждого каталога в дереве, корнем которого является каталог top (включая сам top), функция выдаёт 3-кортеж (dirpath, dirnames, filenames).

dirpath — строка с путём к каталогу. dirnames — список имён подкаталогов в dirpath (включая символические ссылки на каталоги, но исключая '.' и '..'). filenames — список имён файлов в dirpath, не являющихся каталогами. Обратите внимание, что имена в этих списках не содержат компонентов пути. Чтобы получить полный путь (начинающийся с top) к файлу или каталогу в dirpath, используйте os.path.join(dirpath, name). Сортировка списков зависит от файловой системы. Если во время формирования списков файл удаляется из каталога dirpath или добавляется в него, неизвестно, будет ли имя этого файла включено в список.

Если необязательный аргумент topdown равен True или не указан, кортеж для каталога формируется до кортежей для его подкаталогов (каталоги обходятся сверху вниз). Если topdown равен False, кортеж для каталога формируется после кортежей для всех его подкаталогов (каталоги обходятся снизу вверх). Независимо от значения topdown, список подкаталогов извлекается до формирования кортежей для каталога и его подкаталогов.

Если topdown равен True, вызывающий код может изменить список dirnames на месте (например, с помощью del или присваивания срезу), и walk() будет рекурсивно обходить только те подкаталоги, имена которых остались в dirnames. Это можно использовать, чтобы ограничить поиск, задать определённый порядок обхода или сообщить walk() о каталогах, созданных или переименованных вызывающим кодом до возобновления работы walk(). Изменение dirnames, когда topdown равен False, не влияет на обход, поскольку в режиме снизу вверх каталоги из dirnames формируются до самого dirpath.

По умолчанию ошибки вызова scandir() игнорируются. Если указан необязательный аргумент onerror, он должен быть функцией; она будет вызвана с одним аргументом — экземпляром OSError. Функция может сообщить об ошибке и продолжить обход либо возбудить исключение, чтобы прервать его. Обратите внимание, что имя файла доступно в атрибуте filename объекта исключения.

По умолчанию walk() не спускается в каталоги, на которые указывают символические ссылки. Установите followlinks в True, чтобы посещать каталоги, на которые указывают символические ссылки, в системах, поддерживающих эту возможность.

Примечание

Имейте в виду, что установка followlinks в True может привести к бесконечной рекурсии, если ссылка указывает на родительский каталог. walk() не отслеживает, какие каталоги уже были посещены.

Примечание

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

В этом примере отображается количество байтов, занимаемых файлами, не являющимися каталогами, в каждом каталоге под начальным каталогом; при этом подкаталоги CVS не обходятся:

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

В следующем примере (простая реализация shutil.rmtree()) необходимо обходить дерево снизу вверх: rmdir() не позволяет удалить каталог, пока он не пуст:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))

Вызывает событие аудита os.walk с аргументами top, topdown, onerror, followlinks.

Изменено в версии 3.5: Теперь эта функция вызывает os.scandir() вместо os.listdir(), что повышает скорость за счёт сокращения числа вызовов os.stat().

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

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

Функция работает точно так же, как walk(), но выдаёт 4-кортеж (dirpath, dirnames, filenames, dirfd) и поддерживает dir_fd.

dirpath, dirnames и filenames соответствуют выходным данным walk(), а dirfd — это файловый дескриптор, ссылающийся на каталог dirpath.

Эта функция всегда поддерживает пути относительно дескрипторов каталогов и отказ от следования по символическим ссылкам. Однако обратите внимание, что значение follow_symlinks по умолчанию для fwalk(), в отличие от других функций, равно False.

Примечание

Поскольку fwalk() выдаёт файловые дескрипторы, они действительны только до следующего шага итерации. Поэтому, если вы хотите сохранить их дольше, следует создать их копии (например, с помощью dup()).

В этом примере отображается количество байтов, занимаемых файлами, не являющимися каталогами, в каждом каталоге под начальным каталогом; при этом подкаталоги CVS не обходятся:

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

В следующем примере необходимо обходить дерево снизу вверх: rmdir() не позволяет удалить каталог, пока он не пуст:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

Вызывает событие аудита os.fwalk с аргументами top, topdown, onerror, follow_symlinks, dir_fd.

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

Добавлено в версии 3.3.

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

Изменено в версии 3.7: Добавлена поддержка путей типа bytes.

os.memfd_create(name[, flags=os.MFD_CLOEXEC])

Создаёт анонимный файл и возвращает файловый дескриптор, ссылающийся на него. Значение flags должно быть одной из констант os.MFD_*, доступных в системе (или их побитовой комбинацией). По умолчанию новый файловый дескриптор является не наследуемым.

Имя, заданное в name, используется в качестве имени файла и отображается как цель соответствующей символической ссылки в каталоге /proc/self/fd/. Отображаемое имя всегда начинается с memfd: и служит только для отладки. Имена не влияют на поведение файлового дескриптора, поэтому несколько файлов могут иметь одно и то же имя без каких-либо побочных эффектов.

Доступность: Linux >= 3.17 с glibc >= 2.27.

Добавлено в версии 3.8.

os.MFD_CLOEXEC

os.MFD_ALLOW_SEALING

os.MFD_HUGETLB

os.MFD_HUGE_SHIFT

os.MFD_HUGE_MASK

os.MFD_HUGE_64KB

os.MFD_HUGE_512KB

os.MFD_HUGE_1MB

os.MFD_HUGE_2MB

os.MFD_HUGE_8MB

os.MFD_HUGE_16MB

os.MFD_HUGE_32MB

os.MFD_HUGE_256MB

os.MFD_HUGE_512MB

os.MFD_HUGE_1GB

os.MFD_HUGE_2GB

os.MFD_HUGE_16GB

Эти флаги можно передавать в memfd_create().

Доступность: Linux >= 3.17 с glibc >= 2.27

Флаги MFD_HUGE* доступны только начиная с Linux 4.14.

Добавлено в версии 3.8.

os.eventfd(initval[, flags=os.EFD_CLOEXEC])

Создаёт и возвращает файловый дескриптор события. С этим файловым дескриптором поддерживаются прямые вызовы read() и write() с буфером размером 8, а также select(), poll() и аналогичные функции. Дополнительную информацию см. на странице руководства eventfd(2). По умолчанию новый файловый дескриптор является не наследуемым.

initval — начальное значение счётчика событий. Начальное значение должно быть 32-разрядным беззнаковым целым числом. Обратите внимание, что начальное значение ограничено 32-разрядным беззнаковым целым числом, хотя счётчик событий является 64-разрядным беззнаковым целым числом с максимальным значением 2⁶⁴-2.

flags может быть сформирован из EFD_CLOEXEC, EFD_NONBLOCK и EFD_SEMAPHORE.

Если указан EFD_SEMAPHORE и счётчик событий не равен нулю, eventfd_read() возвращает 1 и уменьшает значение счётчика на единицу.

Если EFD_SEMAPHORE не указан и счётчик событий не равен нулю, eventfd_read() возвращает текущее значение счётчика событий и сбрасывает счётчик в ноль.

Если счётчик событий равен нулю и EFD_NONBLOCK не указан, eventfd_read() блокируется.

eventfd_write() увеличивает счётчик событий. Запись блокируется, если в результате операции значение счётчика превысит 2⁶⁴-2.

Пример:

import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)

Доступность: Linux >= 2.6.27 с glibc >= 2.8

Добавлено в версии 3.10.

os.eventfd_read(fd)

Считывает значение из файлового дескриптора eventfd() и возвращает 64-разрядное беззнаковое целое число. Функция не проверяет, является ли fd файловым дескриптором eventfd().

Доступность: Linux >= 2.6.27

Добавлено в версии 3.10.

os.eventfd_write(fd, value)

Добавляет значение в файловый дескриптор eventfd(). value должно быть 64-битным беззнаковым целым числом. Функция не проверяет, является ли fd файловым дескриптором eventfd().

Доступность: Linux >= 2.6.27

Добавлено в версии 3.10.

os.EFD_CLOEXEC

Устанавливает флаг close-on-exec для нового файлового дескриптора eventfd().

Доступность: Linux >= 2.6.27

Добавлено в версии 3.10.

os.EFD_NONBLOCK

Устанавливает флаг состояния O_NONBLOCK для нового файлового дескриптора eventfd().

Доступность: Linux >= 2.6.27

Добавлено в версии 3.10.

os.EFD_SEMAPHORE

Обеспечивает семантику, аналогичную семафору, при чтении из файлового дескриптора eventfd(). При чтении внутренний счётчик уменьшается на единицу.

Доступность: Linux >= 2.6.30

Добавлено в версии 3.10.

Управление процессами

Эти функции можно использовать для создания процессов и управления ими.

Различные функции exec* принимают список аргументов для новой программы, загружаемой в процесс. В каждом случае первый из этих аргументов передаётся новой программе как её собственное имя, а не как аргумент, который пользователь мог бы ввести в командной строке. Для программиста на C это argv[0], передаваемый программе в её main(). Например, os.execv('/bin/echo', ['foo', 'bar']) выведет в стандартный поток вывода только bar; foo будет проигнорирован.

os.abort()

Посылает текущему процессу сигнал SIGABRT. В Unix по умолчанию создаётся дамп памяти; в Windows процесс немедленно завершается с кодом выхода 3. Обратите внимание: вызов этой функции не вызовет обработчик сигналов Python, зарегистрированный для SIGABRT с помощью signal.signal().

os.add_dll_directory(path)

Добавляет путь в список поиска DLL.

Этот список поиска используется при разрешении зависимостей импортируемых модулей расширений (сам модуль ищется через sys.path), а также модулем ctypes.

Чтобы удалить каталог, вызовите close() у возвращённого объекта или используйте его в инструкции with.

Дополнительные сведения о загрузке DLL см. в документации Microsoft.

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

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

Добавлено в версии 3.8: В предыдущих версиях CPython поиск DLL выполнялся с использованием поведения по умолчанию для текущего процесса. Это приводило к несогласованности: например, иногда поиск выполнялся в PATH или текущем рабочем каталоге, а функции ОС, такие как AddDllDirectory, не оказывали никакого эффекта.

Начиная с версии 3.8 два основных способа загрузки DLL явно переопределяют поведение на уровне всего процесса, обеспечивая согласованность. Информацию об обновлении библиотек см. в заметках по переносу.

os.execl(path, arg0, arg1, ...)

os.execle(path, arg0, arg1, ..., env)

os.execlp(file, arg0, arg1, ...)

os.execlpe(file, arg0, arg1, ..., env)

os.execv(path, args)

os.execve(path, args, env)

os.execvp(file, args)

os.execvpe(file, args, env)

Все эти функции выполняют новую программу, заменяя текущий процесс; они не возвращают управление. В Unix новый исполняемый файл загружается в текущий процесс и получает тот же идентификатор процесса, что и вызвавший процесс. Об ошибках сообщается с помощью исключений OSError.

Текущий процесс заменяется немедленно. Открытые файловые объекты и дескрипторы не сбрасываются, поэтому, если в этих открытых файлах могут находиться буферизованные данные, перед вызовом функции exec* их следует сбросить с помощью sys.stdout.flush() или os.fsync().

Варианты функций exec* с буквами «l» и «v» различаются способом передачи аргументов командной строки. Варианты с «l», возможно, проще использовать, если количество параметров задано при написании кода: отдельные параметры просто становятся дополнительными параметрами функций execl*(). Варианты с «v» подходят, когда число параметров меняется; аргументы передаются в виде списка или кортежа в параметре args. В обоих случаях аргументы дочернего процесса должны начинаться с имени запускаемой команды, однако это требование не проверяется.

Варианты, в названии которых ближе к концу стоит буква «p» (execlp(), execlpe(), execvp() и execvpe()), используют переменную окружения PATH для поиска файла программы file. При замене окружения (с помощью одного из вариантов exec*e, рассмотренных в следующем абзаце) источником переменной PATH служит новое окружение. Остальные варианты — execl(), execle(), execv() и execve() — не используют переменную PATH для поиска исполняемого файла; параметр path должен содержать соответствующий абсолютный или относительный путь.

Для функций execle(), execlpe(), execve() и execvpe() (обратите внимание, что все они оканчиваются на «e») параметр env должен быть отображением, используемым для определения переменных окружения нового процесса (они используются вместо окружения текущего процесса). Функции execl(), execlp(), execv() и execvp() заставляют новый процесс наследовать окружение текущего процесса.

В некоторых платформах для execve() параметр path также можно указать как открытый файловый дескриптор. Эта возможность может не поддерживаться на вашей платформе; проверить её доступность можно с помощью os.supports_fd. Если она недоступна, при её использовании будет вызвано исключение NotImplementedError.

Вызывает событие аудита os.exec с аргументами path, args, env.

Доступность: Unix, Windows, кроме Emscripten и WASI.

Изменено в версии 3.3: Добавлена поддержка указания path в виде открытого файлового дескриптора для execve().

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

os._exit(n)

Завершает процесс со статусом n, не вызывая обработчики очистки, не сбрасывая буферы stdio и т. д.

Примечание

Стандартный способ завершения — sys.exit(n). Обычно _exit() следует использовать только в дочернем процессе после вызова fork().

Определены следующие коды выхода, которые можно использовать с _exit(), хотя это и не обязательно. Обычно они используются в системных программах, написанных на Python, например во внешней программе доставки команд почтового сервера.

os.EX_OK

Код выхода, означающий, что ошибок не произошло. На некоторых платформах может принимать определённое значение EXIT_SUCCESS. Обычно равен нулю.

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

os.EX_USAGE

Код выхода, означающий, что команда использована неверно, например указано неправильное число аргументов.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_DATAERR

Код выхода, означающий, что входные данные были неверными.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_NOINPUT

Код выхода, означающий, что входной файл не существует или недоступен для чтения.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_NOUSER

Код выхода, означающий, что указанный пользователь не существует.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_NOHOST

Код выхода, означающий, что указанный хост не существует.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_UNAVAILABLE

Код выхода, означающий, что необходимая служба недоступна.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_SOFTWARE

Код выхода, означающий, что обнаружена внутренняя программная ошибка.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_OSERR

Код выхода, означающий, что обнаружена ошибка операционной системы, например невозможность создать ответвление процесса или канал.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_OSFILE

Код выхода, означающий, что некоторый системный файл не существует, не может быть открыт или возникла ошибка другого типа.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_CANTCREAT

Код выхода, означающий, что указанный пользователем выходной файл не удалось создать.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_IOERR

Код выхода, означающий, что при выполнении операций ввода-вывода с некоторым файлом произошла ошибка.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_TEMPFAIL

Код выхода, означающий, что произошёл временный сбой. Он указывает на ситуацию, которая не обязательно является ошибкой, например на невозможность установить сетевое соединение во время операции, которую можно повторить.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_PROTOCOL

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

Доступность: Unix, кроме Emscripten и WASI.

os.EX_NOPERM

Код выхода, означающий, что для выполнения операции недостаточно прав (не предназначен для проблем с файловой системой).

Доступность: Unix, кроме Emscripten и WASI.

os.EX_CONFIG

Код выхода, означающий, что произошла ошибка конфигурации.

Доступность: Unix, кроме Emscripten и WASI.

os.EX_NOTFOUND

Код выхода, означающий, что нечто вроде «запись не найдена».

Доступность: Unix, кроме Emscripten и WASI.

os.fork()

Создаёт дочерний процесс. В дочернем процессе возвращает 0, а в родительском — идентификатор дочернего процесса. При возникновении ошибки вызывается исключение OSError.

Обратите внимание: на некоторых платформах, включая FreeBSD <= 6.3 и Cygwin, известны проблемы при вызове fork() из потока.

Вызывает событие аудита os.fork без аргументов.

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

В macOS использование этой функции небезопасно в сочетании с высокоуровневыми системными API, в том числе с urllib.request.

Изменено в версии 3.8: Вызов fork() в субинтерпретаторе больше не поддерживается (вызывается исключение RuntimeError).

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

См. ssl для приложений, использующих модуль SSL вместе с fork().

Доступность: Unix, кроме Emscripten и WASI.

os.forkpty()

Создаёт дочерний процесс, используя новый псевдотерминал в качестве управляющего терминала дочернего процесса. Возвращает пару (pid, fd), где pid — это 0 в дочернем процессе и идентификатор нового дочернего процесса в родительском, а fd — файловый дескриптор главного конца псевдотерминала. Для более переносимого подхода используйте модуль pty. При возникновении ошибки вызывается исключение OSError.

Вызывает событие аудита os.forkpty без аргументов.

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

В macOS использование этой функции небезопасно в сочетании с высокоуровневыми системными API, в том числе с urllib.request.

Изменено в версии 3.8: Вызов forkpty() в субинтерпретаторе больше не поддерживается (вызывается исключение RuntimeError).

Доступность: Unix, кроме Emscripten и WASI.

os.kill(pid, sig, /)

Посылает сигнал sig процессу pid. Константы для конкретных сигналов, доступных на хост-платформе, определены в модуле signal.

Windows: сигналы signal.CTRL_C_EVENT и signal.CTRL_BREAK_EVENT являются специальными сигналами, которые можно посылать только консольным процессам с общим окном консоли, например некоторым подпроцессам. Любое другое значение sig приведёт к безусловному завершению процесса с помощью API TerminateProcess, а код выхода будет установлен в sig. Версия kill() для Windows также принимает дескрипторы завершаемых процессов.

См. также signal.pthread_kill().

Вызывает событие аудита os.kill с аргументами pid, sig.

Доступность: Unix, Windows, кроме Emscripten и WASI.

Изменено в версии 3.2: Добавлена поддержка Windows.

os.killpg(pgid, sig, /)

Посылает сигнал sig группе процессов pgid.

Вызывает событие аудита os.killpg с аргументами pgid, sig.

Доступность: Unix, кроме Emscripten и WASI.

os.nice(increment, /)

Увеличивает «вежливость» процесса на increment. Возвращает новое значение вежливости.

Доступность: Unix, кроме Emscripten и WASI.

os.pidfd_open(pid, flags=0)

Возвращает файловый дескриптор, ссылающийся на процесс pid. Этот дескриптор можно использовать для управления процессами без гонок и сигналов. Аргумент flags предусмотрен для будущих расширений; значения флагов пока не определены.

Подробнее см. справочную страницу pidfd_open(2).

Доступность: Linux >= 5.3

Добавлено в версии 3.9.

os.plock(op, /)

Блокирует сегменты программы в памяти. Значение op (определённое в <sys/lock.h>) определяет, какие сегменты блокируются.

Доступность: Unix, кроме Emscripten и WASI.

os.popen(cmd, mode='r', buffering=-1)

Открывает канал к команде cmd или от неё. Возвращаемое значение — открытый файловый объект, подключённый к каналу; из него можно читать или в него можно записывать в зависимости от того, равно ли значение mode 'r' (по умолчанию) или 'w'. Аргумент buffering имеет то же значение, что и соответствующий аргумент встроенной функции open(). Возвращённый файловый объект читает и записывает текстовые строки, а не байты.

Метод close возвращает None, если подпроцесс завершился успешно, или код возврата подпроцесса, если произошла ошибка. В системах POSIX положительный код возврата представляет собой значение возврата процесса, сдвинутое влево на один байт. Если код возврата отрицательный, процесс был завершён сигналом, равным коду возврата, взятому с противоположным знаком. (Например, возвращаемое значение может быть - signal.SIGKILL, если подпроцесс был принудительно завершён.) В системах Windows возвращаемое значение содержит знаковый целочисленный код возврата дочернего процесса.

В Unix функцию waitstatus_to_exitcode() можно использовать для преобразования результата метода close (статуса завершения) в код выхода, если он не равен None. В Windows результат метода close непосредственно является кодом выхода (или None).

Эта функция реализована с помощью subprocess.Popen; более широкие возможности управления подпроцессами и взаимодействия с ними описаны в документации этого класса.

Доступность: кроме Emscripten и WASI.

Примечание

Режим UTF-8 в Python влияет на кодировки, используемые для cmd и содержимого канала.

popen() — это простая обёртка над subprocess.Popen. Чтобы управлять такими параметрами, как кодировки, используйте subprocess.Popen или subprocess.run().

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Обёртка над API библиотеки C posix_spawn() для использования из Python.

Большинству пользователей следует использовать subprocess.run() вместо posix_spawn().

Позиционные аргументы, которые можно передавать только по позиции, path, args и env, аналогичны аргументам execve().

Параметр path — это путь к исполняемому файлу. Параметр path должен содержать каталог. Используйте posix_spawnp(), чтобы передать исполняемый файл без каталога.

Аргумент file_actions может быть последовательностью кортежей, описывающих действия над определёнными файловыми дескрипторами в дочернем процессе между этапами fork() и exec() реализации библиотеки C. Первый элемент каждого кортежа должен быть одним из трёх перечисленных ниже индикаторов типа, описывающих оставшиеся элементы кортежа:

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

Выполняет os.dup2(os.open(path, flags, mode), fd).

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

Выполняет os.close(fd).

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

Выполняет os.dup2(fd, new_fd).

Эти кортежи соответствуют вызовам API библиотеки C posix_spawn_file_actions_addopen(), posix_spawn_file_actions_addclose() и posix_spawn_file_actions_adddup2(), используемым для подготовки к самому вызову posix_spawn().

Аргумент setpgroup задаёт группу процессов дочернего процесса указанным значением. Если указано значение 0, идентификатор группы процессов дочернего процесса будет совпадать с его идентификатором процесса. Если значение setpgroup не задано, дочерний процесс наследует идентификатор группы процессов родительского процесса. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETPGROUP.

Если аргумент resetids имеет значение True, эффективные UID и GID дочернего процесса будут сброшены до реальных UID и GID родительского процесса. Если аргумент имеет значение False, дочерний процесс сохраняет эффективные UID и GID родительского процесса. В обоих случаях, если для исполняемого файла включены биты разрешений set-user-ID и set-group-ID, их действие переопределит настройки эффективных UID и GID. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_RESETIDS.

Если аргумент setsid имеет значение True, для posix_spawn будет создан новый идентификатор сеанса. Для setsid требуется флаг POSIX_SPAWN_SETSID или POSIX_SPAWN_SETSID_NP. В противном случае возбуждается исключение NotImplementedError.

Аргумент setsigmask задаёт маску сигналов указанным набором сигналов. Если параметр не используется, дочерний процесс наследует маску сигналов родительского процесса. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETSIGMASK.

Аргумент sigdef сбрасывает обработчики всех сигналов в указанном наборе. Этот аргумент соответствует флагу библиотеки C POSIX_SPAWN_SETSIGDEF.

Аргумент scheduler должен быть кортежем, содержащим (необязательную) политику планировщика и экземпляр sched_param с параметрами планировщика. Значение None вместо политики планировщика указывает, что она не предоставлена. Этот аргумент объединяет флаги библиотеки C POSIX_SPAWN_SETSCHEDPARAM и POSIX_SPAWN_SETSCHEDULER.

Возбуждает событие аудита os.posix_spawn с аргументами path, argv, env.

Добавлено в версии 3.8.

Доступность: Unix, кроме Emscripten и WASI.

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

Обёртка над API библиотеки C posix_spawnp() для использования из Python.

Аналогична posix_spawn(), за исключением того, что система ищет исполняемый файл executable в списке каталогов, указанном в переменной окружения PATH (так же, как для execvp(3)).

Возбуждает событие аудита os.posix_spawn с аргументами path, argv, env.

Добавлено в версии 3.8.

Доступность: POSIX, кроме Emscripten и WASI.

См. документацию posix_spawn().

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)

Зарегистрировать вызываемые объекты, которые будут выполнены при создании нового дочернего процесса с помощью os.fork() или аналогичных API клонирования процессов. Параметры необязательны и могут передаваться только по ключевому слову. Каждый параметр задаёт отдельный момент вызова.

• before — функция, вызываемая перед созданием дочернего процесса.
• after_in_parent — функция, вызываемая в родительском процессе после создания дочернего процесса.
• after_in_child — функция, вызываемая в дочернем процессе.

Эти вызовы выполняются только в том случае, если ожидается, что управление вернётся интерпретатору Python. Обычный запуск subprocess не вызовет их, поскольку дочерний процесс не будет повторно входить в интерпретатор.

Функции, зарегистрированные для выполнения до создания дочернего процесса, вызываются в обратном порядке регистрации. Функции, зарегистрированные для выполнения после создания дочернего процесса (в родительском или дочернем процессе), вызываются в порядке регистрации.

Обратите внимание, что вызовы fork(), выполняемые сторонним кодом на C, могут не вызывать эти функции, если явно не вызывают PyOS_BeforeFork(), PyOS_AfterFork_Parent() и PyOS_AfterFork_Child().

Отменить регистрацию функции невозможно.

Доступность: Unix, кроме Emscripten и WASI.

Добавлено в версии 3.7.

os.spawnl(mode, path, ...)

os.spawnle(mode, path, ..., env)

os.spawnlp(mode, file, ...)

os.spawnlpe(mode, file, ..., env)

os.spawnv(mode, path, args)

os.spawnve(mode, path, args, env)

os.spawnvp(mode, file, args)

os.spawnvpe(mode, file, args, env)

Выполнить программу path в новом процессе.

(Обратите внимание, что модуль subprocess предоставляет более мощные средства для запуска новых процессов и получения их результатов; предпочтительнее использовать этот модуль, а не данные функции. См. раздел Замена старых функций модулем subprocess.)

Если mode равен P_NOWAIT, эта функция возвращает идентификатор нового процесса; если mode равен P_WAIT, возвращается код завершения процесса, если он завершился нормально, или -signal, где signal — сигнал, завершивший процесс. В Windows идентификатором процесса фактически будет дескриптор процесса, поэтому его можно использовать с функцией waitpid().

Обратите внимание: в VxWorks эта функция не возвращает -signal, если новый процесс завершён. Вместо этого возбуждается исключение OSError.

Варианты функций spawn* с «l» и «v» различаются способом передачи аргументов командной строки. Варианты с «l» удобнее, если количество параметров известно при написании кода: отдельные параметры просто становятся дополнительными аргументами функций spawnl*(). Варианты с «v» удобны, когда количество параметров меняется: аргументы передаются в виде списка или кортежа в параметре args. В обоих случаях аргументы дочернего процесса должны начинаться с имени запускаемой команды.

Варианты со второй «p» ближе к концу имени (spawnlp(), spawnlpe(), spawnvp() и spawnvpe()) используют переменную окружения PATH для поиска файла программы file. Если окружение заменяется (с помощью одного из вариантов spawn*e, рассмотренных в следующем абзаце), новая среда используется в качестве источника переменной PATH. Другие варианты — spawnl(), spawnle(), spawnv() и spawnve() — не используют переменную PATH для поиска исполняемого файла; параметр path должен содержать подходящий абсолютный или относительный путь.

Для функций spawnle(), spawnlpe(), spawnve() и spawnvpe() (обратите внимание, что все они заканчиваются на «e») параметр env должен быть отображением, задающим переменные окружения нового процесса (они используются вместо окружения текущего процесса); функции spawnl(), spawnlp(), spawnv() и spawnvp() заставляют новый процесс наследовать окружение текущего процесса. Обратите внимание: ключи и значения в словаре env должны быть строками; недопустимые ключи или значения приведут к сбою функции с возвращаемым значением 127.

Например, следующие вызовы spawnlp() и spawnvpe() эквивалентны:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

Возбуждает событие аудита os.spawn с аргументами mode, path, args, env.

Доступность: Unix, Windows, кроме Emscripten и WASI.

spawnlp(), spawnlpe(), spawnvp() и spawnvpe() недоступны в Windows. spawnle() и spawnve() не являются потокобезопасными в Windows; рекомендуем использовать вместо них модуль subprocess.

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

os.P_NOWAIT

os.P_NOWAITO

Возможные значения параметра mode для семейства функций spawn*. Если указано одно из этих значений, функции spawn* возвращают управление сразу после создания нового процесса, возвращая его идентификатор.

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

os.P_WAIT

Возможное значение параметра mode для семейства функций spawn*. Если оно указано в качестве mode, функции spawn* не возвращают управление, пока новый процесс не завершится, и возвращают код завершения процесса в случае успешного выполнения или -signal, если процесс завершён сигналом.

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

os.P_DETACH

os.P_OVERLAY

Возможные значения параметра mode для семейства функций spawn*. Они менее переносимы, чем перечисленные выше. P_DETACH аналогично P_NOWAIT, но новый процесс отсоединяется от консоли вызывающего процесса. Если используется P_OVERLAY, текущий процесс будет заменён; функция spawn* не вернёт управление.

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

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])

Запустить файл с помощью связанного с ним приложения.

Если operation не указан или равен 'open', это аналогично двойному щелчку по файлу в Проводнике Windows или передаче имени файла в качестве аргумента команде start в интерактивной командной оболочке: файл открывается в приложении, с которым связано его расширение (если такое приложение есть).

Если указано другое значение operation, оно должно быть «глаголом команды», задающим действие над файлом. В документации Microsoft описаны распространённые глаголы 'print' и 'edit' (для файлов), а также 'explore' и 'find' (для каталогов).

При запуске приложения укажите arguments в виде одной строки, которая будет ему передана. При использовании этой функции для запуска документа этот аргумент может не иметь эффекта.

По умолчанию рабочий каталог наследуется, но его можно переопределить аргументом cwd. Это должен быть абсолютный путь. Относительный путь path будет разрешён относительно этого аргумента.

Используйте show_cmd, чтобы переопределить стиль окна по умолчанию. Наличие эффекта зависит от запускаемого приложения. Значения представляют собой целые числа, поддерживаемые функцией Win32 ShellExecute().

startfile() возвращает управление сразу после запуска связанного приложения. Дождаться закрытия приложения нельзя, как и получить код его завершения. Параметр path задаётся относительно текущего каталога или cwd. Если нужен абсолютный путь, убедитесь, что его первый символ не является косой чертой ('/'). Используйте pathlib или функцию os.path.normpath(), чтобы пути были правильно закодированы для Win32.

Чтобы сократить время запуска интерпретатора, функция Win32 ShellExecute() разрешается только при первом вызове этой функции. Если разрешить функцию не удастся, будет возбуждено исключение NotImplementedError.

Возбуждает событие аудита os.startfile с аргументами path, operation.

Возбуждает событие аудита os.startfile/2 с аргументами path, operation, arguments, cwd, show_cmd.

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

Изменено в версии 3.10: Добавлены аргументы arguments, cwd и show_cmd, а также событие аудита os.startfile/2.

os.system(command)

Выполнить команду (строку) во вложенной оболочке. Реализация вызывает стандартную функцию C system() и имеет те же ограничения. Изменения sys.stdin и т. д. не отражаются на окружении выполняемой команды. Если command выдаёт какие-либо данные, они отправляются в стандартный поток вывода интерпретатора. Стандарт C не определяет значение возвращаемого функцией C результата, поэтому возвращаемое значение функции Python зависит от системы.

В Unix возвращаемое значение — это код состояния процесса, закодированный в формате, определённом для wait().

В Windows возвращается значение, выданное системной оболочкой после выполнения command. Оболочка задаётся переменной окружения Windows COMSPEC: обычно это cmd.exe, возвращающая код завершения выполненной команды; если используется оболочка, отличная от системной, обратитесь к её документации.

Модуль subprocess предоставляет более мощные средства для запуска новых процессов и получения их результатов; предпочтительнее использовать этот модуль, а не данную функцию. Полезные примеры приведены в разделе Замена старых функций модулем subprocess документации модуля subprocess.

В Unix для преобразования результата (кода состояния) в код завершения можно использовать waitstatus_to_exitcode(). В Windows результатом непосредственно является код завершения.

Возбуждает событие аудита os.system с аргументом command.

Доступность: Unix, Windows, кроме Emscripten и WASI.

os.times()

Возвращает текущее общее процессорное время процессов. Возвращаемое значение — объект с пятью атрибутами:

• user — пользовательское время
• system — системное время
• children_user — пользовательское время всех дочерних процессов
• children_system — системное время всех дочерних процессов
• elapsed — реальное время, прошедшее с фиксированного момента в прошлом

Для обратной совместимости этот объект также ведёт себя как кортеж из пяти элементов, содержащий user, system, children_user, children_system и elapsed в указанном порядке.

См. страницу руководства Unix times(2) и страницу руководства times(3) в Unix или документацию GetProcessTimes в MSDN для Windows. В Windows известны только user и system; остальные атрибуты равны нулю.

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

Изменено в версии 3.3: Тип возвращаемого значения изменён с кортежа на объект, подобный кортежу, с именованными атрибутами.

os.wait()

Дождаться завершения дочернего процесса и вернуть кортеж, содержащий его PID и признак состояния завершения: 16-битное число, младший байт которого содержит номер сигнала, завершившего процесс, а старший байт — код завершения (если номер сигнала равен нулю); старший бит младшего байта устанавливается, если был создан файл core.

Если нет дочерних процессов, завершения которых можно дождаться, возбуждается исключение ChildProcessError.

Для преобразования кода состояния завершения в код завершения можно использовать waitstatus_to_exitcode().

Доступность: Unix, кроме Emscripten и WASI.

См. также

Другие функции wait*(), описанные ниже, позволяют ожидать завершения определённого дочернего процесса и предоставляют больше возможностей. Только waitpid() также доступна в Windows.

os.waitid(idtype, id, options, /)

Дождаться завершения дочернего процесса.

idtype может быть равен P_PID, P_PGID, P_ALL или (в Linux) P_PIDFD. Интерпретация id зависит от этого значения; см. соответствующие описания.

options — это побитовое ИЛИ флагов. Требуется указать хотя бы один из флагов WEXITED, WSTOPPED или WCONTINUED; WNOHANG и WNOWAIT — дополнительные необязательные флаги.

Возвращаемое значение — объект, представляющий данные структуры siginfo_t со следующими атрибутами:

• si_pid (идентификатор процесса)
• si_uid (реальный идентификатор пользователя дочернего процесса)
• si_signo (всегда SIGCHLD)
• si_status (код завершения или номер сигнала, в зависимости от si_code)
• si_code (возможные значения см. в CLD_EXITED)

Если указан WNOHANG и нет соответствующих дочерних процессов в запрошенном состоянии, возвращается None. В противном случае, если нет соответствующих дочерних процессов, завершения которых можно дождаться, возбуждается исключение ChildProcessError.

Доступность: Unix, кроме Emscripten и WASI.

Примечание

Эта функция недоступна в macOS.

Добавлено в версии 3.3.

os.waitpid(pid, options, /)

Подробности работы этой функции различаются в Unix и Windows.

В Unix: ожидает завершения дочернего процесса с идентификатором процесса pid и возвращает кортеж, содержащий идентификатор процесса и признак его статуса завершения (закодированный так же, как для wait()). Семантика вызова зависит от значения целого числа options, которое для обычной работы должно быть 0.

Если pid больше 0, waitpid() запрашивает сведения о состоянии именно этого процесса. Если pid равен 0, запрашивается состояние любого дочернего процесса в группе процессов текущего процесса. Если pid равен -1, запрашивается состояние любого дочернего процесса текущего процесса. Если pid меньше -1, запрашивается состояние любого процесса в группе процессов -pid (абсолютное значение pid).

options — это комбинация флагов, объединённых оператором OR. Если она содержит WNOHANG и нет дочерних процессов, соответствующих запрошенному состоянию, возвращается (0, 0). В противном случае, если нет соответствующих дочерних процессов, ожидания которых можно дождаться, возникает исключение ChildProcessError. Можно использовать и другие параметры: WUNTRACED и WCONTINUED.

В Windows: ожидает завершения процесса, заданного дескриптором процесса pid, и возвращает кортеж, содержащий pid и статус завершения, сдвинутый влево на 8 бит (сдвиг упрощает кроссплатформенное использование функции). Значение pid, меньшее или равное 0, не имеет в Windows особого значения и вызывает исключение. Значение целого числа options не оказывает влияния. pid может ссылаться на любой процесс, идентификатор которого известен, а не только на дочерний процесс. Функции spawn*, вызванные с параметром P_NOWAIT, возвращают подходящие дескрипторы процессов.

waitstatus_to_exitcode() можно использовать для преобразования статуса завершения в код завершения.

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

Изменено в версии 3.5: Если системный вызов прерывается, а обработчик сигнала не вызывает исключение, теперь функция повторяет системный вызов вместо возникновения исключения InterruptedError (обоснование см. в PEP 475).

os.wait3(options)

Похожа на waitpid(), но идентификатор процесса не задаётся, а возвращается кортеж из 3 элементов, содержащий идентификатор дочернего процесса, признак его статуса завершения и сведения об использовании ресурсов. Подробные сведения об использовании ресурсов см. в resource.getrusage(). Аргумент options имеет то же значение, что и у waitpid() и wait4().

waitstatus_to_exitcode() можно использовать для преобразования статуса завершения в код завершения.

Доступность: Unix, не Emscripten, не WASI.

os.wait4(pid, options)

Похожа на waitpid(), но возвращается кортеж из 3 элементов, содержащий идентификатор дочернего процесса, признак его статуса завершения и сведения об использовании ресурсов. Подробные сведения об использовании ресурсов см. в resource.getrusage(). Аргументы wait4() совпадают с аргументами waitpid().

waitstatus_to_exitcode() можно использовать для преобразования статуса завершения в код завершения.

Доступность: Unix, не Emscripten, не WASI.

os.P_PID

os.P_PGID

os.P_ALL

os.P_PIDFD

Это возможные значения idtype в waitid(). Они определяют способ интерпретации id:

• P_PID — ожидать дочерний процесс с PID, равным id.
• P_PGID — ожидать любой дочерний процесс с идентификатором группы процессов, равным id.
• P_ALL — ожидать любой дочерний процесс; id игнорируется.
• P_PIDFD — ожидать дочерний процесс, идентифицируемый файловым дескриптором id (файловый дескриптор процесса, созданный с помощью pidfd_open()).

Доступность: Unix, не Emscripten, не WASI.

Примечание

P_PIDFD доступна только в Linux версии 5.4 и выше.

Добавлено в версии 3.3.

Добавлено в версии 3.9: константа P_PIDFD.

os.WCONTINUED

Этот флаг options для waitpid(), wait3(), wait4() и waitid() приводит к тому, что дочерние процессы сообщаются, если после последнего сообщения они были возобновлены после остановки управления заданиями.

Доступность: Unix, не Emscripten, не WASI.

os.WEXITED

Этот флаг options для waitid() приводит к тому, что сообщается о завершившихся дочерних процессах.

Другие функции wait* всегда сообщают о завершившихся дочерних процессах, поэтому для них этот параметр недоступен.

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.3.

os.WSTOPPED

Этот флаг options для waitid() приводит к тому, что сообщается о дочерних процессах, остановленных доставкой сигнала.

Этот параметр недоступен для других функций wait*.

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.3.

os.WUNTRACED

Этот флаг options для waitpid(), wait3() и wait4() приводит к тому, что также сообщается о дочерних процессах, если они были остановлены, но сведения об их текущем состоянии после остановки ещё не сообщались.

Этот параметр недоступен для waitid().

Доступность: Unix, не Emscripten, не WASI.

os.WNOHANG

Этот флаг options заставляет waitpid(), wait3(), wait4() и waitid() немедленно возвращать управление, если сведения о состоянии дочернего процесса недоступны.

Доступность: Unix, не Emscripten, не WASI.

os.WNOWAIT

Этот флаг options заставляет waitid() оставить дочерний процесс в состоянии, допускающем ожидание, чтобы последующий вызов wait*() мог повторно получить сведения о состоянии дочернего процесса.

Этот параметр недоступен для других функций wait*.

Доступность: Unix, не Emscripten, не WASI.

os.CLD_EXITED

os.CLD_KILLED

os.CLD_DUMPED

os.CLD_TRAPPED

os.CLD_STOPPED

os.CLD_CONTINUED

Это возможные значения si_code в результате, возвращаемом waitid().

Доступность: Unix, не Emscripten, не WASI.

Добавлено в версии 3.3.

Изменено в версии 3.9: Добавлены значения CLD_KILLED и CLD_STOPPED.

os.waitstatus_to_exitcode(status)

Преобразует статус ожидания в код завершения.

В Unix:

• Если процесс завершился нормально (если WIFEXITED(status) истинно), возвращает статус завершения процесса (возвращает WEXITSTATUS(status)): результат больше или равен 0.
• Если процесс был завершён сигналом (если WIFSIGNALED(status) истинно), возвращает -signum, где signum — номер сигнала, вызвавшего завершение процесса (возвращает -WTERMSIG(status)): результат меньше 0.
• В противном случае вызывает исключение ValueError.

В Windows возвращает status, сдвинутый вправо на 8 бит.

В Unix, если процесс трассируется или если waitpid() вызвана с параметром WUNTRACED, вызывающий код должен сначала проверить, истинно ли WIFSTOPPED(status). Эту функцию нельзя вызывать, если WIFSTOPPED(status) истинно.

См. также

Функции WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED(), WSTOPSIG().

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

Добавлено в версии 3.9.

Следующие функции принимают в качестве параметра код состояния процесса, возвращаемый функцией system(), wait() или waitpid(). Их можно использовать для определения состояния процесса.

os.WCOREDUMP(status, /)

Возвращает True, если для процесса был создан дамп памяти, иначе возвращает False.

Эту функцию следует использовать только в том случае, если WIFSIGNALED() истинно.

Доступность: Unix, не Emscripten, не WASI.

os.WIFCONTINUED(status)

Возвращает True, если остановленный дочерний процесс был возобновлён доставкой SIGCONT (если процесс продолжил работу после остановки управления заданиями), иначе возвращает False.

См. параметр WCONTINUED.

Доступность: Unix, не Emscripten, не WASI.

os.WIFSTOPPED(status)

Возвращает True, если процесс был остановлен доставкой сигнала, иначе возвращает False.

WIFSTOPPED() возвращает True только в том случае, если вызов waitpid() был выполнен с параметром WUNTRACED или когда процесс трассируется (см. ptrace(2)).

Доступность: Unix, не Emscripten, не WASI.

os.WIFSIGNALED(status)

Возвращает True, если процесс был завершён сигналом, иначе возвращает False.

Доступность: Unix, не Emscripten, не WASI.

os.WIFEXITED(status)

Возвращает True, если процесс завершился нормально, то есть вызвав exit() или _exit() либо вернувшись из main(); иначе возвращает False.

Доступность: Unix, не Emscripten, не WASI.

os.WEXITSTATUS(status)

Возвращает статус завершения процесса.

Эту функцию следует использовать только в том случае, если WIFEXITED() истинно.

Доступность: Unix, не Emscripten, не WASI.

os.WSTOPSIG(status)

Возвращает сигнал, вызвавший остановку процесса.

Эту функцию следует использовать только в том случае, если WIFSTOPPED() истинно.

Доступность: Unix, не Emscripten, не WASI.

os.WTERMSIG(status)

Возвращает номер сигнала, вызвавшего завершение процесса.

Эту функцию следует использовать только в том случае, если WIFSIGNALED() истинно.

Доступность: Unix, не Emscripten, не WASI.

Интерфейс планировщика

Эти функции управляют тем, как операционная система выделяет процессу процессорное время. Они доступны только на некоторых платформах Unix. Более подробные сведения см. на справочных страницах Unix.

Следующие политики планирования доступны, если они поддерживаются операционной системой.

os.SCHED_OTHER

Политика планирования по умолчанию.

os.SCHED_BATCH

Политика планирования для процессов с интенсивной нагрузкой на ЦП, старающаяся сохранить интерактивность остальных задач компьютера.

os.SCHED_IDLE

Политика планирования для фоновых задач с крайне низким приоритетом.

os.SCHED_SPORADIC

Политика планирования для программ спорадического сервера.

os.SCHED_FIFO

Политика планирования «первым пришёл — первым обслужен» (FIFO).

os.SCHED_RR

Циклическая политика планирования (round-robin).

os.SCHED_RESET_ON_FORK

Этот флаг можно объединить оператором OR с любой другой политикой планирования. Если процесс с установленным флагом создаёт дочерний процесс, политика планирования и приоритет дочернего процесса сбрасываются до значений по умолчанию.

class os.sched_param(sched_priority)

Этот класс представляет настраиваемые параметры планирования, используемые в sched_setparam(), sched_setscheduler() и sched_getparam(). Он неизменяемый.

В настоящее время возможен только один параметр:

sched_priority

Приоритет планирования для политики планирования.

os.sched_get_priority_min(policy)

Возвращает минимальное значение приоритета для policy. policy — одна из перечисленных выше констант политики планирования.

os.sched_get_priority_max(policy)

Возвращает максимальное значение приоритета для policy. policy — одна из перечисленных выше констант политики планирования.

os.sched_setscheduler(pid, policy, param, /)

Устанавливает политику планирования для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс. policy — одна из перечисленных выше констант политики планирования. param — экземпляр sched_param.

os.sched_getscheduler(pid, /)

Возвращает политику планирования для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс. Результат — одна из перечисленных выше констант политики планирования.

os.sched_setparam(pid, param, /)

Устанавливает параметры планирования для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс. param — экземпляр sched_param.

os.sched_getparam(pid, /)

Возвращает параметры планирования в виде экземпляра sched_param для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс.

os.sched_rr_get_interval(pid, /)

Возвращает квант времени циклического планирования в секундах для процесса с PID pid. Значение pid, равное 0, обозначает вызывающий процесс.

os.sched_yield()

Добровольно освобождает ЦП.

os.sched_setaffinity(pid, mask, /)

Ограничивает процесс с PID pid (или текущий процесс, если значение равно нулю) набором ЦП. mask — итерируемый объект с целыми числами, представляющими набор ЦП, которыми должен быть ограничен процесс.

os.sched_getaffinity(pid, /)

Возвращает набор ЦП, которым ограничен процесс с PID pid.

Если pid равен нулю, возвращает набор ЦП, которым ограничен вызывающий поток текущего процесса.

Разная системная информация

os.confstr(name, /)

Возвращает строковые значения параметров конфигурации системы. name задаёт параметр конфигурации, который требуется получить; это может быть строка с именем определённого системного параметра. Такие имена определяются рядом стандартов (POSIX, Unix 95, Unix 98 и другими). Некоторые платформы также определяют дополнительные имена. Имена, известные операционной системе узла, представлены в качестве ключей словаря confstr_names. Для переменных конфигурации, не включённых в это соответствие, в качестве name также можно передать целое число.

Если параметр конфигурации, указанный в name, не определён, возвращается None.

Если name — строка, но она неизвестна, возникает исключение ValueError. Если конкретное значение name не поддерживается операционной системой узла, даже если оно включено в confstr_names, возникает исключение OSError, а номер ошибки равен errno.EINVAL.

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

os.confstr_names

Словарь, сопоставляющий имена, принимаемые confstr(), целочисленным значениям, определённым для этих имён операционной системой узла. Его можно использовать, чтобы определить набор имён, известных системе.

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

os.cpu_count()

Возвращает количество логических процессоров в системе. Если определить его не удалось, возвращается None.

Это число не обязательно совпадает с количеством логических процессоров, которые может использовать текущий процесс. len(os.sched_getaffinity(0)) возвращает количество логических процессоров, доступных вызывающему потоку текущего процесса

Добавлено в версии 3.4.

os.getloadavg()

Возвращает среднее количество процессов в очереди на выполнение в системе за последние 1, 5 и 15 минут или вызывает исключение OSError, если получить среднюю нагрузку не удалось.

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

os.sysconf(name, /)

Возвращает целочисленные значения параметров конфигурации системы. Если параметр конфигурации, указанный в name, не определён, возвращается -1. Замечания о параметре name для confstr() применимы и здесь; словарь со сведениями об известных именах — sysconf_names.

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

os.sysconf_names

Словарь, сопоставляющий имена, принимаемые sysconf(), целочисленным значениям, определённым для этих имён операционной системой узла. Его можно использовать, чтобы определить набор имён, известных системе.

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

Изменено в версии 3.11: Добавлено имя 'SC_MINSIGSTKSZ'.

Следующие значения данных используются для поддержки операций с путями. Они определены для всех платформ.

Операции более высокого уровня для работы с путями определены в модуле os.path.

os.curdir

Строковая константа, используемая операционной системой для обозначения текущего каталога. Для Windows и POSIX это '.'. Также доступна через os.path.

os.pardir

Строковая константа, используемая операционной системой для обозначения родительского каталога. Для Windows и POSIX это '..'. Также доступна через os.path.

os.sep

Символ, используемый операционной системой для разделения компонентов пути. Для POSIX это '/', а для Windows — '\\'. Обратите внимание: знания этого символа недостаточно для разбора или объединения путей — используйте os.path.split() и os.path.join(), — однако иногда это может быть полезно. Также доступна через os.path.

os.altsep

Дополнительный символ, используемый операционной системой для разделения компонентов пути, или None, если существует только один символ-разделитель. В системах Windows это значение равно '/', где sep — обратная косая черта. Также доступна через os.path.

os.extsep

Символ, отделяющий имя файла от расширения; например, os.py содержит символ '.'. Также доступна через os.path.

os.pathsep

Символ, обычно используемый операционной системой для разделения компонентов пути поиска (как в PATH), например ':' для POSIX или ';' для Windows. Также доступна через os.path.

os.defpath

Путь поиска по умолчанию, используемый exec*p* и spawn*p*, если в окружении нет ключа 'PATH'. Также доступна через os.path.

os.linesep

Строка, используемая для разделения (или, точнее, завершения) строк на текущей платформе. Это может быть один символ, например '\n' для POSIX, или несколько символов, например '\r\n' для Windows. Не используйте os.linesep в качестве окончания строки при записи файлов, открытых в текстовом режиме (по умолчанию); на всех платформах используйте вместо этого один '\n'.

os.devnull

Путь к устройству null. Например: '/dev/null' для POSIX, 'nul' для Windows. Также доступна через os.path.

os.RTLD_LAZY

os.RTLD_NOW

os.RTLD_GLOBAL

os.RTLD_LOCAL

os.RTLD_NODELETE

os.RTLD_NOLOAD

os.RTLD_DEEPBIND

Флаги для функций setdlopenflags() и getdlopenflags(). Значения различных флагов см. на странице руководства Unix dlopen(3).

Добавлено в версии 3.3.

Случайные числа

os.getrandom(size, flags=0)

Получает до size случайных байтов. Функция может вернуть меньше байтов, чем запрошено.

Эти байты можно использовать для инициализации генераторов случайных чисел в пользовательском пространстве или в криптографических целях.

getrandom() использует энтропию, полученную от драйверов устройств и других источников случайного шума окружающей среды. Чтение чрезмерно больших объёмов данных без необходимости негативно повлияет на других пользователей устройств /dev/random и /dev/urandom.

Аргумент flags — это битовая маска, которая может содержать одно или несколько следующих значений, объединённых побитовым ИЛИ: os.GRND_RANDOM и GRND_NONBLOCK.

См. также страницу руководства Linux по getrandom().

Доступность: Linux >= 3.17.

Добавлено в версии 3.6.

os.urandom(size, /)

Возвращает строку байтов из size случайных байтов, пригодных для использования в криптографии.

Эта функция возвращает случайные байты из источника случайных данных, специфичного для операционной системы. Возвращённые данные должны быть достаточно непредсказуемыми для криптографических приложений, хотя их точное качество зависит от реализации операционной системы.

В Linux, если доступен системный вызов getrandom(), он используется в блокирующем режиме: функция ожидает инициализации пула энтропии urandom системы (ядро собирает 128 бит энтропии). Обоснование см. в PEP 524. В Linux для получения случайных байтов в неблокирующем режиме (с использованием флага GRND_NONBLOCK) или для ожидания инициализации пула энтропии urandom системы можно использовать функцию getrandom().

В Unix-подобных системах случайные байты считываются с устройства /dev/urandom. Если устройство /dev/urandom недоступно или не читается, возникает исключение NotImplementedError.

В Windows используется BCryptGenRandom().

См. также

Модуль secrets предоставляет функции более высокого уровня. Чтобы воспользоваться простым интерфейсом к генератору случайных чисел, предоставляемому вашей платформой, см. random.SystemRandom.

Изменено в версии 3.5: В Linux 3.17 и новее теперь используется системный вызов getrandom(), если он доступен. В OpenBSD 5.6 и новее теперь используется функция C getentropy(). Эти функции позволяют не использовать внутренний файловый дескриптор.

Изменено в версии 3.5.2: В Linux, если системный вызов getrandom() блокирует выполнение (пул энтропии urandom ещё не инициализирован), вместо него считываются данные из /dev/urandom.

Изменено в версии 3.6: В Linux теперь используется getrandom() в блокирующем режиме для повышения безопасности.

Изменено в версии 3.11: В Windows используется BCryptGenRandom() вместо устаревшего CryptGenRandom().

os.GRND_NONBLOCK

По умолчанию при чтении из /dev/random функция getrandom() блокирует выполнение, если случайные байты недоступны; при чтении из /dev/urandom выполнение блокируется, если пул энтропии ещё не инициализирован.

Если задан флаг GRND_NONBLOCK, функция getrandom() не блокирует выполнение в этих случаях, а сразу вызывает исключение BlockingIOError.

Добавлено в версии 3.6.

os.GRND_RANDOM

Если этот бит установлен, случайные байты берутся из пула /dev/random вместо пула /dev/urandom.

Добавлено в версии 3.6.