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

Источник: Lib/os.py

Этот модуль предоставляет переносимый способ использования функциональности, зависящей от операционной системы. Если вы хотите просто прочитать или записать файл, смотрите модуль open(), если вы хотите манипулировать путями, смотрите модуль os.path, а если вы хотите прочитать все строки во всех файлах в командной строке, смотрите модуль fileinput. Для создания временных файлов и каталогов смотрите модуль tempfile, а для высокоуровневой работы с файлами и каталогами - модуль shutil.

Примечания о доступности этих функций:

Дизайн всех встроенных модулей Python, зависящих от операционной системы, таков, что до тех пор, пока доступна та же функциональность, она использует тот же интерфейс; например, функция os.stat(path) возвращает статистическую информацию о path в том же формате (который, как оказалось, берет начало в интерфейсе POSIX).
Расширения, характерные для конкретной операционной системы, также доступны через модуль os, но их использование, конечно, угрожает переносимости.
Все функции, принимающие имена путей или файлов, принимают как байтовые, так и строковые объекты и выдают в результате объект того же типа, если возвращается путь или имя файла.
На VxWorks не поддерживаются os.popen, os.fork, os.execv и os.spawn*p*.
На платформах WebAssembly и iOS многие части модуля os недоступны или ведут себя иначе. API, связанные с процессами (например, fork(), execve()) и ресурсами (например, nice()), недоступны. Другие, такие как getuid() и getpid(), являются эмуляцией или заглушками. В платформах WebAssembly также отсутствует поддержка сигналов (например, kill(), wait()).

Примечание

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

exception os.error¶: Псевдоним для встроенного исключения OSError.

os.name¶: Имя импортируемого модуля, зависящего от операционной системы. В настоящее время зарегистрированы следующие имена: 'posix', 'nt', 'java'.

См.также

sys.platform имеет более мелкую детализацию. os.uname() предоставляет информацию о версии, зависящую от системы.

Модуль platform обеспечивает детальную проверку идентичности системы.

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

В Python имена файлов, аргументы командной строки и переменные окружения представлены с помощью типа string. В некоторых системах перед передачей операционной системе необходимо декодировать эти строки в байты и обратно. Python использует filesystem encoding and error handler для выполнения этого преобразования (см. sys.getfilesystemencoding()).

Параметры filesystem encoding and error handler настраиваются при запуске Python функцией PyConfig_Read(): см. члены filesystem_encoding и filesystem_errors в PyConfig.

Изменено в версии 3.1: В некоторых системах преобразование с использованием кодировки файловой системы может быть неудачным. В этом случае Python использует surrogateescape encoding error handler, что означает, что недекодируемые байты заменяются символом Юникода U+DCxx при декодировании, а при кодировании они снова переводятся в исходный байт.

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

См. также locale encoding.

Режим Python UTF-8¶

Added in version 3.7: Более подробную информацию см. в разделе PEP 540.

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

Используйте UTF-8 в качестве filesystem encoding.
sys.getfilesystemencoding() возвращается 'utf-8'.
locale.getpreferredencoding() возвращает 'utf-8' (аргумент do_setlocale не имеет значения).
sys.stdin, sys.stdout и sys.stderr используют UTF-8 в качестве кодировки текста, а surrogateescape error handler включается для sys.stdin и sys.stdout (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. Однако по умолчанию они по-прежнему используют строгий обработчик ошибок, так что попытка открыть двоичный файл в текстовом режиме, скорее всего, вызовет исключение, а не выдаст бессмысленные данные.

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

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

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

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

См. также UTF-8 mode on Windows и filesystem encoding and error handler.

См.также

PEP 686: В Python 3.15 Режим Python UTF-8 будет использоваться по умолчанию.

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

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

os.ctermid()¶: Возвращает имя файла, соответствующего управляющему терминалу процесса.

Availability: Unix, не WASI.

os.environ¶

Объект mapping, в котором ключи и значения - строки, представляющие окружение процесса. Например, 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().

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

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

os.environb¶

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

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

Added in version 3.2.

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

os.chdir(path)
os.fchdir(fd)
os.getcwd(): Эти функции описаны в разделе Файлы и каталоги.

os.fsencode(filename)¶

Перекодируйте path-like имя файла в filesystem encoding and error handler; верните bytes без изменений.

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

Added in version 3.2.

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

os.fsdecode(filename)¶

Декодируйте path-like имя файла из filesystem encoding and error handler; верните str без изменений.

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

Added in version 3.2.

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

os.fspath(path)¶

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

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

Added in version 3.6.

class os.PathLike¶

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

Added in version 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().

Availability: Unix, Windows.

os.getenvb(key, default=None)¶

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

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

Availability: Unix.

Added in version 3.2.

os.get_exec_path(env=None)¶: Возвращает список каталогов, которые будут искаться в поисках именованного исполняемого файла, аналогичного оболочке, при запуске процесса. env, когда указано, должно быть словарем переменной окружения для поиска PATH. По умолчанию, когда env равно None, используется environ.

Added in version 3.2.

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

Availability: Unix, не WASI.

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

Availability: Unix, не WASI.

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

Availability: Unix.

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

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

Availability: Unix, не WASI.

Added in version 3.3.

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

Availability: Unix, не 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], чтобы получить имя текущего реального пользователя.

Availability: Unix, Windows, не WASI.

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

Availability: Unix, не WASI.

os.getpgrp()¶: Возвращает идентификатор текущей группы процессов.

Availability: Unix, не WASI.

os.getpid()¶

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

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

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

Availability: Unix, Windows, не WASI.

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

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

Availability: Unix, не WASI.

Added in version 3.3.

os.PRIO_PROCESS¶
os.PRIO_PGRP¶
os.PRIO_USER¶: Параметры для функций getpriority() и setpriority().

Availability: Unix, не WASI.

Added in version 3.3.

os.PRIO_DARWIN_THREAD¶
os.PRIO_DARWIN_PROCESS¶
os.PRIO_DARWIN_BG¶
os.PRIO_DARWIN_NONUI¶: Параметры для функций getpriority() и setpriority().

Availability: macOS

Added in version 3.12.

os.getresuid()¶: Возвращает кортеж (ruid, euid, suid), обозначающий реальный, эффективный и сохраненный идентификаторы пользователей текущего процесса.

Availability: Unix, не WASI.

Added in version 3.2.

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

Availability: Unix, не WASI.

Added in version 3.2.

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

Availability: Unix.

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

os.initgroups(username, gid, /)¶: Вызовите системную функцию initgroups() для инициализации списка группового доступа со всеми группами, членом которых является указанное имя пользователя, плюс указанный идентификатор группы.

Availability: Unix, не WASI.

Added in version 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().

Поднимает auditing event os.putenv с аргументами key, value.

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

os.setegid(egid, /)¶: Установите идентификатор эффективной группы текущего процесса.

Availability: Unix, не WASI.

os.seteuid(euid, /)¶: Установите эффективный идентификатор пользователя текущего процесса.

Availability: Unix, не WASI.

os.setgid(gid, /)¶: Установите идентификатор группы текущего процесса.

Availability: Unix, не WASI.

os.setgroups(groups, /)¶: Устанавливает список идентификаторов дополнительных групп, связанных с текущим процессом, в groups. groups должна быть последовательностью, и каждый элемент должен быть целым числом, идентифицирующим группу. Эта операция обычно доступна только суперпользователю.

Availability: Unix, не WASI.

Примечание

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

os.setns(fd, nstype=0)¶

Переассоциировать текущий поток с пространством имен Linux. Более подробную информацию см. на страницах setns(2) и namespaces(7).

Если fd ссылается на ссылку /proc/pid/ns/, setns() перепривязывает вызывающий поток к пространству имен, связанному с этой ссылкой, а nstype может быть установлен в одно из CLONE_NEW* constants, чтобы наложить ограничения на операцию (0 означает отсутствие ограничений).

Начиная с Linux 5.8, fd может ссылаться на дескриптор файла PID, полученный из pidfd_open(). В этом случае setns() переассоциирует вызывающий поток в одно или несколько тех же пространств имен, что и поток, на который ссылается fd. Это происходит с учетом любых ограничений, накладываемых nstype, который представляет собой битовую маску, объединяющую один или несколько CLONE_NEW* constants, например setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID). Членство вызывающей стороны в неопределенных пространствах имен остается неизменным.

fd может быть любым объектом с методом fileno() или необработанным дескриптором файла.

В этом примере поток перепривязывается к сетевому пространству имен процесса init:

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

Availability: Linux >= 3.0 с glibc >= 2.14.

Added in version 3.12.

См.также

Функция unshare().

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

Availability: Unix, не WASI.

os.setpgid(pid, pgrp, /)¶: Вызовите системный вызов setpgid(), чтобы установить идентификатор группы процессов процесса с идентификатором pid в группу процессов с идентификатором pgrp. Семантику см. в руководстве по Unix.

Availability: Unix, не WASI.

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

Availability: Unix, не WASI.

Added in version 3.3.

os.setregid(rgid, egid, /)¶: Установите идентификаторы реальной и эффективной групп текущего процесса.

Availability: Unix, не WASI.

os.setresgid(rgid, egid, sgid, /)¶: Установите идентификаторы реальной, эффективной и сохраненной групп текущего процесса.

Availability: Unix, не WASI.

Added in version 3.2.

os.setresuid(ruid, euid, suid, /)¶: Установите реальные, эффективные и сохраненные идентификаторы пользователей текущего процесса.

Availability: Unix, не WASI.

Added in version 3.2.

os.setreuid(ruid, euid, /)¶: Установите идентификаторы реального и эффективного пользователей текущего процесса.

Availability: Unix, не WASI.

os.getsid(pid, /)¶: Вызовите системный вызов getsid(). Семантику см. в руководстве по Unix.

Availability: Unix, не WASI.

os.setsid()¶: Вызовите системный вызов setsid(). Семантику см. в руководстве по Unix.

Availability: Unix, не WASI.

os.setuid(uid, /)¶: Установите идентификатор пользователя текущего процесса.

Availability: Unix, не WASI.

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

os.supports_bytes_environ¶: True, если родным типом ОС среды является байт (например, False в Windows).

Added in version 3.2.

os.umask(mask, /)¶

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

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

os.uname()¶

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

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

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

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

Для macOS, iOS и Android это возвращает имя и версию ядра (т. е. 'Darwin' для macOS и iOS; 'Linux' для Android). platform.uname() можно использовать для получения имени и версии операционной системы, ориентированной на пользователя, на iOS и Android.

Availability: Unix.

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

os.unsetenv(key, /)¶

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

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

Поднимает auditing event os.unsetenv с аргументом key.

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

os.unshare(flags)¶: Разъединяет части контекста выполнения процесса и перемещает их во вновь созданное пространство имен. Дополнительные сведения см. на странице unshare(2). Аргумент flags представляет собой битовую маску, объединяющую ноль или более из CLONE_* constants, которая указывает, какие части контекста выполнения должны быть отсоединены от существующих ассоциаций и перемещены в новое пространство имен. Если аргумент flags равен 0, никаких изменений в контекст выполнения вызывающего процесса не вносится.

Availability: Linux >= 2.6.16.

Added in version 3.12.

См.также

Функция setns().

Флаги для функции unshare(), если реализация поддерживает их. Их точное действие и доступность см. в руководстве по Linux unshare(2).

os.CLONE_FILES¶
os.CLONE_FS¶
os.CLONE_NEWCGROUP¶
os.CLONE_NEWIPC¶
os.CLONE_NEWNET¶
os.CLONE_NEWNS¶
os.CLONE_NEWPID¶
os.CLONE_NEWTIME¶
os.CLONE_NEWUSER¶
os.CLONE_NEWUTS¶
os.CLONE_SIGHAND¶
os.CLONE_SYSVSEM¶
os.CLONE_THREAD¶
os.CLONE_VM¶

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

Эти функции создают новые file objects (см. также open() для открытия дескрипторов файлов).

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

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

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

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

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

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.

В ядре Linux старше 5.3 файлы, на которые указывают src и dst, должны находиться в одной и той же файловой системе, иначе будет вызвана ошибка OSError, а для errno установлено значение errno.EXDEV.

Это копирование выполняется без дополнительных затрат на передачу данных из ядра в пользовательское пространство и затем обратно в ядро. Кроме того, некоторые файловые системы могут реализовывать дополнительные оптимизации, такие как использование рефлинков (т. е. двух или более инодов, имеющих общие указатели на одни и те же блоки диска с копированием при записи; поддерживаемые файловые системы включают btrfs и XFS) и копирование на стороне сервера (в случае NFS).

Функция копирует байты между двумя файловыми дескрипторами. Параметры текста, такие как кодировка и окончание строки, игнорируются.

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

Примечание

В Linux os.copy_file_range() не следует использовать для копирования диапазона псевдофайла из специальных файловых систем, таких как procfs и sysfs. Она всегда будет копировать ни одного байта и возвращать 0, как если бы файл был пуст, из-за известной проблемы ядра Linux.

Availability: Linux >= 4.5 с glibc >= 2.27.

Added in version 3.8.

os.device_encoding(fd)¶

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

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

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

os.dup(fd, /)¶

Возвращает дубликат файлового дескриптора fd. Новым дескриптором файла будет non-inheritable.

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

Availability: не WASI.

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

os.dup2(fd, fd2, inheritable=True)¶: Дублирует файловый дескриптор fd в fd2, при необходимости закрывая последний первым. Возвращает fd2. Новый дескриптор файла по умолчанию имеет значение inheritable или ненаследуемый, если значение inheritable равно False.

Availability: не WASI.

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

Изменено в версии 3.7: Возвращает fd2 в случае успеха. Ранее всегда возвращался None.

os.fchmod(fd, mode)¶

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

Поднимает auditing event os.chmod с аргументами path, mode, dir_fd.

Availability: Unix, Windows.

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

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

os.fchown(fd, uid, gid)¶

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

Поднимает auditing event os.chown с аргументами path, uid, gid, dir_fd.

Availability: Unix.

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

os.fdatasync(fd)¶: Принудительная запись файла с файловым дескриптором fd на диск. Не заставляет обновлять метаданные.

Availability: 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).

Availability: 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).

Availability: Unix.

os.fsync(fd)¶

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

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

Availability: Unix, Windows.

os.ftruncate(fd, length, /)¶

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

Поднимает auditing event os.truncate с аргументами fd, length.

Availability: Unix, Windows.

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

os.get_blocking(fd, /)¶

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

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

Availability: Unix, Windows.

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

В Windows эта функция ограничена трубами.

Added in version 3.5.

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

os.grantpt(fd, /)¶

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

Вызывает функцию стандартной библиотеки C grantpt().

Availability: Unix, не WASI.

Added in version 3.13.

os.isatty(fd, /)¶: Возвращает True, если файловый дескриптор fd открыт и подключен к устройству типа tty(-like), иначе False.

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

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

Поднимает auditing event os.lockf с аргументами fd, cmd, len.

Availability: Unix.

Added in version 3.3.

os.F_LOCK¶
os.F_TLOCK¶
os.F_ULOCK¶
os.F_TEST¶: Флаги, указывающие, какое действие будет выполнено lockf().

Availability: Unix.

Added in version 3.3.

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

Availability: Unix, не WASI.

Added in version 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() на file-like objects, для чего необходимо настроить индикатор положения файла.

SEEK_SET: Настройте положение файла относительно начала файла.
SEEK_CUR: Настройка позиции файла относительно текущей позиции файла.
SEEK_END: Настройте положение файла относительно конца файла.

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

os.SEEK_HOLE¶

os.SEEK_DATA¶

Параметры функции lseek() и метода seek() на file-like objects для поиска файловых данных и отверстий в редко распределенных файлах.

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

Примечание

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

Availability: Linux >= 3.1, macOS, Unix

Added in version 3.3.

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

Откройте файл path и установите различные флаги в соответствии с flags и, возможно, его режим в соответствии с mode. При вычислении mode текущее значение umask сначала маскируется. Возвращает дескриптор файла для только что открытого файла. Дескриптором нового файла является non-inheritable.

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

Эта функция может поддерживать paths relative to directory descriptors с параметром dir_fd.

Поднимает auditing event open с аргументами path, mode, flags.

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

Примечание

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

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

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

Изменено в версии 3.6: Принимает path-like object.

Следующие константы являются опциями для параметра flags функции open(). Их можно объединить с помощью оператора побитового ИЛИ |. Некоторые из них доступны не на всех платформах. Для получения информации об их наличии и использовании обратитесь к странице руководства open(2) на Unix или the 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 Kernel 3.11 или новее.

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

Availability: Unix, не WASI.

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

os.pipe()¶: Создать трубу. Возвращает пару файловых дескрипторов (r, w), пригодных для чтения и записи, соответственно. Новый дескриптор файла - это non-inheritable.

Availability: Unix, Windows.

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

os.pipe2(flags, /)¶: Создайте трубу с флагами, установленными атомарно. Флаги flags могут быть сконструированы путем объединения по ИЛИ одного или нескольких из этих значений: O_NONBLOCK, O_CLOEXEC. Возвращает пару файловых дескрипторов (r, w), пригодных для чтения и записи, соответственно.

Availability: Unix, не WASI.

Added in version 3.3.

os.posix_fallocate(fd, offset, len, /)¶: Убедится, что для файла, указанного fd, выделено достаточно места на диске, начиная с offset и далее на len байт.

Availability: Unix.

Added in version 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.

Availability: Unix.

Added in version 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¶: Флаги, которые могут быть использованы в советах в posix_fadvise(), указывающих на шаблон доступа, который, вероятно, будет использоваться.

Availability: Unix.

Added in version 3.3.

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

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

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

Availability: Unix.

Added in version 3.3.

os.posix_openpt(oflag, /)¶

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

Вызывает функцию стандартной библиотеки C posix_openpt(). Аргумент oflag используется для установки флагов состояния файлов и режимов доступа к ним, как указано на странице руководства posix_openpt() вашей системы.

Возвращаемый дескриптор файла имеет значение non-inheritable. Если в системе доступно значение O_CLOEXEC, оно добавляется к oflag.

Availability: Unix, не WASI.

Added in version 3.13.

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

Чтение из файлового дескриптора fd в позиции offset в мутабельные bytes-like objects буферы, оставляя смещение файла неизменным. Передавайте данные в каждый буфер, пока он не заполнится, а затем переходите к следующему буферу в последовательности для хранения оставшейся части данных.

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

RWF_HIPRI
RWF_NOWAIT

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

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

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

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

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

Added in version 3.7.

os.RWF_NOWAIT¶

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

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

Availability: Linux >= 4.14.

Added in version 3.7.

os.RWF_HIPRI¶

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

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

Availability: Linux >= 4.6.

Added in version 3.7.

os.ptsname(fd, /)¶

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

Вызывает реентерабельную функцию стандартной библиотеки C ptsname_r(), если она доступна; в противном случае вызывается функция стандартной библиотеки C ptsname(), потокобезопасность которой не гарантируется.

Availability: Unix, не WASI.

Added in version 3.13.

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

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

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

Availability: Unix.

Added in version 3.3.

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

Записать содержимое буферов в дескриптор файла fd по смещению offset, оставив смещение файла неизменным. Буферы должны быть последовательностью bytes-like objects. Буферы обрабатываются в порядке массива. Перед переходом ко второму буферу записывается все содержимое первого и так далее.

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

RWF_DSYNC
RWF_SYNC
RWF_APPEND

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

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

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

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

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

Added in version 3.7.

os.RWF_DSYNC¶: Предоставляет эквивалент O_DSYNC для каждой записи. os.open() флага. Действие этого флага распространяется только на диапазон данных, записанных системным вызовом.

Availability: Linux >= 4.7.

Added in version 3.7.

os.RWF_SYNC¶: Предоставляет эквивалент O_SYNC для каждой записи. os.open() флага. Действие этого флага распространяется только на диапазон данных, записанных системным вызовом.

Availability: Linux >= 4.7.

Added in version 3.7.

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

Availability: Linux >= 4.16.

Added in version 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. Возвращает количество отправленных байт. При достижении EOF возвращается 0.

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

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

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

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

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

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

Availability: Unix, не WASI.

Примечание

Более высокоуровневую обертку sendfile() смотрите в socket.socket.sendfile().

Added in version 3.3.

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

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

Availability: Unix, не WASI.

Added in version 3.3.

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

Availability: Unix, не WASI.

Added in version 3.11.

os.set_blocking(fd, blocking, /)¶

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

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

Availability: Unix, Windows.

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

В Windows эта функция ограничена трубами.

Added in version 3.5.

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

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 относится к трубе, то это означает, что данные не передавались, и блокировать их не имеет смысла, так как к пишущему концу трубы не подключены писатели.

Availability: Linux >= 2.6.17 с glibc >= 2.5

Added in version 3.10.

os.SPLICE_F_MOVE¶
os.SPLICE_F_NONBLOCK¶
os.SPLICE_F_MORE¶: Added in version 3.10.

os.readv(fd, buffers, /)¶

Чтение из файлового дескриптора fd в ряд изменяемых bytes-like objects буферов. Передавайте данные в каждый буфер, пока он не заполнится, а затем переходите к следующему буферу в последовательности для хранения оставшейся части данных.

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

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

Availability: Unix.

Added in version 3.3.

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

Availability: Unix, не WASI.

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

Availability: Unix, не WASI.

os.ttyname(fd, /)¶: Возвращает строку, определяющую терминальное устройство, связанное с файловым дескриптором fd. Если fd не ассоциирован с терминальным устройством, будет вызвано исключение.

Availability: Unix.

os.unlockpt(fd, /)¶

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

Вызывает функцию стандартной библиотеки C unlockpt().

Availability: Unix, не WASI.

Added in version 3.13.

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, /)¶

Запишите содержимое буферов в файловый дескриптор fd. Буферы должны быть последовательностью bytes-like objects. Буферы обрабатываются в порядке массива. Перед переходом ко второму буферу записывается все содержимое первого и так далее.

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

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

Availability: Unix.

Added in version 3.3.

Запрос размера терминала¶

Added in version 3.3.

os.get_terminal_size(fd=STDOUT_FILENO, /)¶

Возвращает размер окна терминала в виде (columns, lines), кортежа типа terminal_size.

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

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

shutil.get_terminal_size() - высокоуровневая функция, которая обычно должна использоваться, os.get_terminal_size - низкоуровневая реализация.

Availability: Unix, Windows.

class os.terminal_size¶

Подкласс кортежа, содержащего (columns, lines) размера окна терминала.

columns¶: Ширина окна терминала в символах.

lines¶: Высота окна терминала в символах.

Наследование дескрипторов файлов¶

Added in version 3.4.

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

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

В Windows ненаследуемые дескрипторы и дескрипторы файлов закрываются в дочерних процессах, за исключением стандартных потоков (дескрипторы файлов 0, 1 и 2: stdin, stdout и stderr), которые всегда наследуются. При использовании функций spawn* наследуются все наследуемые дескрипторы и все наследуемые дескрипторы файлов. При использовании модуля subprocess закрываются все файловые дескрипторы, кроме стандартных потоков, а наследуемые дескрипторы наследуются только в том случае, если параметр close_fds имеет значение False.

На платформах WebAssembly дескриптор файла не может быть изменен.

os.get_inheritable(fd, /)¶: Получает флаг «наследуемый» указанного дескриптора файла (булево значение).

os.set_inheritable(fd, inheritable, /)¶: Устанавливает флаг «наследуемый» для указанного файлового дескриптора.

os.get_handle_inheritable(handle, /)¶: Получает флаг «наследуемый» для указанного хэндла (булево значение).

Availability: Windows.

os.set_handle_inheritable(handle, inheritable, /)¶: Устанавливает флаг «наследуемый» для указанного хэндла.

Availability: Windows.

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

На некоторых платформах 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)¶

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

Эта функция может поддерживать указание paths relative to directory descriptors и not following symlinks.

Если 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: Принимает path-like object.

os.F_OK¶
os.R_OK¶
os.W_OK¶
os.X_OK¶: Значения, передаваемые в качестве параметра mode в access() для проверки существования, читаемости, записываемости и исполняемости пути, соответственно.

os.chdir(path)¶

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

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

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

Поднимает auditing event os.chdir с аргументом path.

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

Изменено в версии 3.6: Принимает path-like object.

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

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

Эта функция может поддерживать not following symlinks.

Поднимает auditing event os.chflags с аргументами path, flags.

Availability: Unix, не WASI.

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

Изменено в версии 3.6: Принимает path-like object.

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

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

Эта функция может поддерживать specifying a file descriptor, paths relative to directory descriptors и not following symlinks.

Примечание

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

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

Поднимает auditing event os.chmod с аргументами path, mode, dir_fd.

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

Изменено в версии 3.6: Принимает path-like object.

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

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

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

Эта функция может поддерживать specifying a file descriptor, paths relative to directory descriptors и not following symlinks.

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

Поднимает auditing event os.chown с аргументами path, uid, gid, dir_fd.

Availability: Unix.

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

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

Изменено в версии 3.6: Поддерживает path-like object.

os.chroot(path)¶: Измените корневой каталог текущего процесса на path.

Availability: Unix, не WASI.

Изменено в версии 3.6: Принимает path-like object.

os.fchdir(fd)¶

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

Поднимает auditing event os.chdir с аргументом path.

Availability: Unix.

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

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

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

os.lchflags(path, flags)¶

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

Поднимает auditing event os.chflags с аргументами path, flags.

Availability: Unix, не WASI.

Изменено в версии 3.6: Принимает path-like object.

os.lchmod(path, mode)¶

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

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

Поднимает auditing event os.chmod с аргументами path, mode, dir_fd.

Availability: Unix, Windows, не Linux, FreeBSD >= 1.3, NetBSD >= 1.3, не OpenBSD

Изменено в версии 3.6: Принимает path-like object.

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

os.lchown(path, uid, gid)¶

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

Поднимает auditing event os.chown с аргументами path, uid, gid, dir_fd.

Availability: Unix.

Изменено в версии 3.6: Принимает path-like object.

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

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

Эта функция может поддерживать указание src_dir_fd и/или dst_dir_fd для поставки paths relative to directory descriptors и not following symlinks.

Поднимает auditing event os.link с аргументами src, dst, src_dir_fd, dst_dir_fd.

Availability: Unix, Windows.

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

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

Изменено в версии 3.6: Принимает path-like object для src и dst.

os.listdir(path='.')¶

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

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

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

Поднимает auditing event os.listdir с аргументом path.

Примечание

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

См.также

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

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

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

Изменено в версии 3.6: Принимает path-like object.

os.listdrives()¶

Возвращает список, содержащий имена дисков в системе Windows.

Имя диска обычно выглядит как 'C:\\'. Не каждое имя диска будет связано с томом, и некоторые могут быть недоступны по разным причинам, включая разрешения, подключение к сети или отсутствие носителя. Эта функция не проверяет доступ.

Может поднять OSError, если произошла ошибка при сборе имен дисков.

Поднимает auditing event os.listdrives без аргументов.

Availability: Windows

Added in version 3.12.

os.listmounts(volume)¶

Возвращает список, содержащий точки монтирования для тома в системе Windows.

тома должны быть представлены в виде GUID-пути, подобно тем, которые возвращает os.listvolumes(). Тома могут быть смонтированы в нескольких местах или не смонтированы вообще. В последнем случае список будет пуст. Точки монтирования, не связанные с томом, не будут возвращены этой функцией.

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

Вызывает OSError, если том не распознан или произошла ошибка при сборе путей.

Поднимает auditing event os.listmounts с аргументом volume.

Availability: Windows

Added in version 3.12.

os.listvolumes()¶

Возвращает список, содержащий тома в системе.

Тома обычно представляются в виде GUID-пути, который выглядит как \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\. Доступ к файлам обычно можно получить через GUID-путь, если позволяют разрешения. Однако пользователи обычно не знакомы с ними, поэтому рекомендуется использовать эту функцию для получения точек монтирования с помощью os.listmounts().

Может поднять OSError, если произошла ошибка при сборе томов.

Поднимает auditing event os.listvolumes без аргументов.

Availability: Windows

Added in version 3.12.

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

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

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

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

Эта функция также может поддерживать paths relative to directory descriptors.

См.также

Функция stat().

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

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

Изменено в версии 3.6: Принимает path-like object.

Изменено в версии 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 игнорируются.

Эта функция также может поддерживать paths relative to directory descriptors.

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

Поднимает auditing event os.mkdir с аргументами path, mode, dir_fd.

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

Изменено в версии 3.6: Принимает path-like object.

Изменено в версии 3.13: Windows теперь обрабатывает режим 0o700.

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

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

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

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

Примечание

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

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

Поднимает auditing event 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: Принимает path-like object.

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

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

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

Эта функция также может поддерживать paths relative to directory descriptors.

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

Availability: Unix, не WASI.

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

Изменено в версии 3.6: Принимает path-like object.

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()), в противном случае оно игнорируется.

Эта функция также может поддерживать paths relative to directory descriptors.

Availability: Unix, не WASI.

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

Изменено в версии 3.6: Принимает path-like object.

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.

Эта функция может поддерживать specifying a file descriptor.

Availability: Unix.

Изменено в версии 3.6: Принимает path-like object.

os.pathconf_names¶: Словарь, отображающий имена, принимаемые через pathconf() и fpathconf(), на целочисленные значения, определенные для этих имен операционной системой хоста. Это можно использовать для определения набора имен, известных системе.

Availability: Unix.

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

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

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

Эта функция также может поддерживать paths relative to directory descriptors.

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

Availability: Unix, Windows.

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

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

Изменено в версии 3.6: Принимает path-like object на Unix.

Изменено в версии 3.8: Принимает path-like object и объект bytes в Windows.

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

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

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

Эта функция может поддерживать paths relative to directory descriptors.

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

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

Поднимает auditing event os.remove с аргументами path, dir_fd.

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

Изменено в версии 3.6: Принимает path-like object.

os.removedirs(name)¶

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

Поднимает auditing event os.remove с аргументами path, dir_fd.

Изменено в версии 3.6: Принимает path-like object.

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 будет молча заменен. Если dst - непустой каталог, будет выдано сообщение OSError. Если оба файла являются файлами, то dst будет заменен молча, если у пользователя есть права. Операция может завершиться неудачей в некоторых версиях Unix, если src и dst находятся в разных файловых системах. В случае успеха переименование будет атомарным (это требование POSIX).

Эта функция может поддерживать указание src_dir_fd и/или dst_dir_fd для поставки paths relative to directory descriptors.

Если вам нужна кроссплатформенная перезапись места назначения, используйте replace().

Поднимает auditing event os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

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

Изменено в версии 3.6: Принимает path-like object для src и dst.

os.renames(old, new)¶

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

Примечание

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

Поднимает auditing event os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

Изменено в версии 3.6: Принимает значение path-like object для старый и новый.

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 для поставки paths relative to directory descriptors.

Поднимает auditing event os.rename с аргументами src, dst, src_dir_fd, dst_dir_fd.

Added in version 3.3.

Изменено в версии 3.6: Принимает path-like object для src и dst.

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

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

Эта функция может поддерживать paths relative to directory descriptors.

Поднимает auditing event os.rmdir с аргументами path, dir_fd.

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

Изменено в версии 3.6: Принимает path-like object.

os.scandir(path='.')¶

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

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

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

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

Поднимает auditing event os.scandir с аргументом path.

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

scandir.close()¶

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

Он вызывается автоматически, когда итератор исчерпан или собран, или когда во время итерации произошла ошибка. Однако рекомендуется вызывать его явно или использовать оператор with.

Added in version 3.6.

В следующем примере показано простое использование scandir() для отображения всех файлов (за исключением каталогов) в заданном пути, которые не начинаются с '.'. Вызов 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.

Added in version 3.5.

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

Функция принимает значение path-like object.

Изменено в версии 3.7: Добавлена поддержка file descriptors на Unix.

class os.DirEntry¶

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

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

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

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

Чтобы быть непосредственно пригодным для использования в качестве path-like object, os.DirEntry реализует интерфейс PathLike.

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

name¶

Базовое имя файла записи, относительно аргумента scandir() пути.

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

path¶

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

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

inode()¶

Возвращает номер 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 перехватывается и не поднимается.

is_junction()¶

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

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

Added in version 3.12.

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(), is_junction() и stat().

Added in version 3.5.

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

Изменено в версии 3.12: Атрибут st_ctime в результатах статистики устарел в Windows. Время создания файла должным образом доступно как st_birthtime, а в будущем st_ctime может быть изменен, чтобы возвращать ноль или время изменения метаданных, если оно доступно.

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

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

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

Эта функция может поддерживать значения specifying a file descriptor и not following symlinks.

В Windows передача follow_symlinks=False отключает следование за всеми точками разбора с суррогатами имен, включая симлинки и перекрестки каталогов. Другие типы точек репарации, которые не похожи на ссылки или по которым операционная система не может следовать, будут открываться напрямую. При следовании по цепочке из нескольких ссылок может быть возвращена исходная ссылка, а не та, которая препятствовала полному обходу. Чтобы получить результат stat для конечного пути в этом случае, используйте функцию 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: Принимает path-like object.

Изменено в версии 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,
file index в Windows

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

st_nlink¶: Количество жестких ссылок.

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

st_gid¶: Групповой идентификатор владельца файла.

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

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

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

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

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

Изменено в версии 3.12: st_ctime устарел в Windows. Используйте st_birthtime для времени создания файла. В будущем st_ctime будет содержать время последнего изменения метаданных, как и для других платформ.

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

Added in version 3.3.

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

Added in version 3.3.

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

Added in version 3.3.

Изменено в версии 3.12: st_ctime_ns устарел в Windows. Используйте st_birthtime_ns для времени создания файла. В будущем st_ctime будет содержать время последнего изменения метаданных, как и для других платформ.

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

Изменено в версии 3.12: st_birthtime теперь доступен в Windows.

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

Added in version 3.12.

Примечание

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

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

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

st_blocks¶: Количество 512-байтных блоков, выделенных для файла. Это число может быть меньше, чем st_size/512, если в файле есть дыры.

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

st_rdev¶: Тип устройства, если это устройство inode.

st_flags¶: Флаги, определяемые пользователем для файла.

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

st_gen¶: Номер поколения файла.

В 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.

Added in version 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/derivatives добавлен член st_fstype.

Изменено в версии 3.8: Добавлен член st_reparse_tag в Windows.

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

Изменено в версии 3.12: В Windows значение st_ctime устарело. В конечном итоге он будет содержать время последнего изменения метаданных для согласованности с другими платформами, но пока он по-прежнему содержит время создания. Используйте st_birthtime для времени создания.

В Windows длина st_ino теперь может достигать 128 бит, в зависимости от файловой системы. Ранее он не превышал 64 бит, и более крупные идентификаторы файлов упаковывались произвольно.

В Windows значение st_rdev больше не возвращается. Ранее оно содержало то же значение, что и st_dev, что было неверно.

Добавлен член st_birthtime в Windows.

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).

Эта функция может поддерживать specifying a file descriptor.

Availability: 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: Принимает path-like object.

Изменено в версии 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.

Added in version 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 она не работает.

Added in version 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

Added in version 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, если вы можете указать follow_symlinks=False при вызове os.stat() на локальной платформе:

os.stat in os.supports_follow_symlinks

Added in version 3.3.

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

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

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

Эта функция может поддерживать paths relative to directory descriptors.

Примечание

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

OSError возникает при вызове функции непривилегированным пользователем.

Поднимает auditing event os.symlink с аргументами src, dst, dir_fd.

Availability: Unix, Windows.

Функция ограничена на WASI, смотрите Платформы WebAssembly для получения дополнительной информации.

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

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

Изменено в версии 3.6: Принимает path-like object для src и dst.

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

os.sync()¶: Принудительная запись всего на диск.

Availability: Unix.

Added in version 3.3.

os.truncate(path, length)¶

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

Эта функция может поддерживать specifying a file descriptor.

Поднимает auditing event os.truncate с аргументами path, length.

Availability: Unix, Windows.

Added in version 3.3.

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

Изменено в версии 3.6: Принимает path-like object.

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

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

Поднимает auditing event os.remove с аргументами path, dir_fd.

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

Изменено в версии 3.6: Принимает path-like object.

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

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

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

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

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

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

Эта функция может поддерживать specifying a file descriptor, paths relative to directory descriptors и not following symlinks.

Поднимает auditing event os.utime с аргументами path, times, ns, dir_fd.

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

Изменено в версии 3.6: Принимает path-like object.

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))

Поднимает auditing event os.walk с аргументами top, topdown, onerror, followlinks.

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

Изменено в версии 3.6: Принимает path-like object.

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.

Эта функция всегда поддерживает paths relative to directory descriptors и not following symlinks. Однако обратите внимание, что, в отличие от других функций, значение fwalk() по умолчанию для follow_symlinks равно 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)

Поднимает auditing event os.fwalk с аргументами top, topdown, onerror, follow_symlinks, dir_fd.

Availability: Unix.

Added in version 3.3.

Изменено в версии 3.6: Принимает path-like object.

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

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

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

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

Availability: Linux >= 3.17 с glibc >= 2.27.

Added in version 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().

Availability: Linux >= 3.17 с glibc >= 2.27

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

Added in version 3.8.

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

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

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

Флаги могут быть построены из 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)

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.10.

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

Availability: Linux >= 2.6.27

Added in version 3.10.

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

Availability: Linux >= 2.6.27

Added in version 3.10.

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

Availability: Linux >= 2.6.27

Added in version 3.10.

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

Availability: Linux >= 2.6.27

Added in version 3.10.

os.EFD_SEMAPHORE¶: Обеспечивает семафороподобную семантику для чтения из файлового дескриптора eventfd(). При чтении внутренний счетчик декрементируется на единицу.

Availability: Linux >= 2.6.30

Added in version 3.10.

Дескрипторы файлов таймера¶

Added in version 3.13.

Эти функции обеспечивают поддержку API timer file descriptor в Linux. Естественно, все они доступны только в Linux.

os.timerfd_create(clockid, /, *, flags=0)¶

Создает и возвращает дескриптор файла таймера (timerfd).

Дескриптор файла, возвращенный timerfd_create(), поддерживает:

Метод read() файлового дескриптора может быть вызван с размером буфера 8. Если таймер уже истек один или несколько раз, read() возвращает количество истечений с эндианальностью хоста, которая может быть преобразована в int с помощью int.from_bytes(x, byteorder=sys.byteorder).

select() и poll() можно использовать для ожидания, пока не истечет таймер и дескриптор файла не станет доступен для чтения.

clockid должен быть правильным clock ID, как определено в модуле time:

time.CLOCK_REALTIME
time.CLOCK_MONOTONIC
time.CLOCK_BOOTTIME (начиная с Linux 3.15 для timerfd_create)

Если clockid равен time.CLOCK_REALTIME, то используются настраиваемые общесистемные часы реального времени. Если системные часы изменены, необходимо обновить настройки таймера. Чтобы отменить таймер при изменении системных часов, смотрите TFD_TIMER_CANCEL_ON_SET.

Если clockid равен time.CLOCK_MONOTONIC, то используется монотонно увеличивающийся таймер, не подлежащий настройке. Даже если системные часы будут изменены, на настройку таймера это не повлияет.

Если clockid равен time.CLOCK_BOOTTIME, то это то же самое, что и time.CLOCK_MONOTONIC, только включает в себя все время, когда система приостановлена.

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

TFD_NONBLOCK
TFD_CLOEXEC

Если TFD_NONBLOCK не установлен как флаг, read() блокирует до истечения таймера. Если флаг установлен, read() не блокируется, но если с момента последнего вызова чтения не истек срок действия таймера, read() повышает OSError, а errno устанавливается в errno.EAGAIN.

TFD_CLOEXEC всегда устанавливается Python автоматически.

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

См.также

Человеческая страница timerfd_create(2).

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)¶

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

fd должен быть действительным дескриптором файла таймера.

Поведение таймера можно изменить, указав значение flags. Можно использовать любую из следующих переменных, объединенных с помощью побитового ИЛИ (оператор |):

TFD_TIMER_ABSTIME
TFD_TIMER_CANCEL_ON_SET

Таймер отключается установкой initial в ноль (0). Если initial равно или больше нуля, таймер включается. Если initial меньше нуля, возникает исключение OSError с errno, установленным в errno.EINVAL.

По умолчанию таймер сработает по истечении initial секунд. (Если initial равно нулю, таймер сработает немедленно).

Однако, если установлен флаг TFD_TIMER_ABSTIME, таймер сработает, когда часы таймера (заданные clockid в timerfd_create()) достигнут начальной секунды.

Интервал таймера задается параметром interval float. Если interval равен нулю, таймер срабатывает только один раз, при первом истечении срока действия. Если interval больше нуля, таймер срабатывает каждый раз, когда с момента предыдущего истечения прошло interval секунд. Если interval меньше нуля, он поднимает OSError, а errno устанавливается на errno.EINVAL.

Если флаг TFD_TIMER_CANCEL_ON_SET установлен вместе с TFD_TIMER_ABSTIME и часы для этого таймера равны time.CLOCK_REALTIME, то таймер помечается как отменяемый, если часы реального времени изменяются скачкообразно. Чтение дескриптора прерывается с ошибкой ECANCELED.

Linux управляет системными часами как UTC. Переход на летнее время осуществляется только за счет изменения смещения времени и не вызывает прерывистого изменения системных часов.

Непрерывная смена системных часов будет вызвана следующими событиями:

settimeofday
clock_settime
установите системную дату и время командой date.

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

См.также

timerfd_create(2), timerfd_settime(2), settimeofday(2), clock_settime(2) и date(1).

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)¶: Аналогична timerfd_settime(), но использует время в наносекундах. Эта функция работает с тем же интервальным таймером, что и timerfd_settime().

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.timerfd_gettime(fd, /)¶

Возвращает кортеж из двух элементов с плавающей точкой (next_expiration, interval).

next_expiration обозначает относительное время до следующего срабатывания таймера, независимо от того, установлен ли флаг TFD_TIMER_ABSTIME.

interval обозначает интервал таймера. Если значение равно нулю, таймер сработает только один раз, по истечении next_expiration секунд.

См.также

timerfd_gettime(2)

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.timerfd_gettime_ns(fd, /)¶: Аналогично timerfd_gettime(), но время возвращается в виде наносекунд.

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.TFD_NONBLOCK¶: Флаг для функции timerfd_create(), которая устанавливает флаг состояния O_NONBLOCK для нового дескриптора файла таймера. Если TFD_NONBLOCK не установлен в качестве флага, read() блокируется.

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.TFD_CLOEXEC¶: Флаг для функции timerfd_create(), Если в качестве флага установлен TFD_CLOEXEC, устанавливается флаг close-on-exec для нового файлового дескриптора.

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.TFD_TIMER_ABSTIME¶: Флаг для функций timerfd_settime() и timerfd_settime_ns(). Если этот флаг установлен, initial интерпретируется как абсолютное значение на часах таймера (в секундах UTC или наносекундах с эпохи Unix).

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

os.TFD_TIMER_CANCEL_ON_SET¶: Флаг для функций timerfd_settime() и timerfd_settime_ns() вместе с TFD_TIMER_ABSTIME. Таймер отменяется при скачкообразном изменении времени базовых часов.

Availability: Linux >= 2.6.27 с glibc >= 2.8

Added in version 3.13.

Расширенные атрибуты Linux¶

Added in version 3.3.

Все эти функции доступны только в Linux.

os.getxattr(path, attribute, *, follow_symlinks=True)¶

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

Эта функция может поддерживать значения specifying a file descriptor и not following symlinks.

Поднимает auditing event os.getxattr с аргументами path, attribute.

Изменено в версии 3.6: Принимает path-like object для пути и атрибута.

os.listxattr(path=None, *, follow_symlinks=True)¶

Возвращает список расширенных атрибутов файловой системы на path. Атрибуты в списке представлены в виде строк, декодированных с помощью кодировки файловой системы. Если path - это None, то listxattr() будет проверен текущий каталог.

Эта функция может поддерживать значения specifying a file descriptor и not following symlinks.

Поднимает auditing event os.listxattr с аргументом path.

Изменено в версии 3.6: Принимает path-like object.

os.removexattr(path, attribute, *, follow_symlinks=True)¶

Удаляет расширенный атрибут файловой системы attribute из path. Атрибут attribute должен быть байтом или строкой (напрямую или косвенно через интерфейс PathLike). Если это строка, то она кодируется с помощью filesystem encoding and error handler.

Эта функция может поддерживать значения specifying a file descriptor и not following symlinks.

Поднимает auditing event os.removexattr с аргументами path, attribute.

Изменено в версии 3.6: Принимает path-like object для пути и атрибута.

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)¶

Устанавливает расширенный атрибут файловой системы attribute на path в value. Атрибут должен быть байтом или строкой без встроенных NUL (прямо или косвенно через интерфейс PathLike). Если это str, то она кодируется с помощью filesystem encoding and error handler. флаги могут быть XATTR_REPLACE или XATTR_CREATE. Если задан XATTR_REPLACE и атрибут не существует, будет выдан сигнал ENODATA. Если задан XATTR_CREATE и атрибут уже существует, то атрибут не будет создан и будет выдано сообщение EEXISTS.

Эта функция может поддерживать значения specifying a file descriptor и not following symlinks.

Примечание

Ошибка в ядре Linux версий менее 2.6.39 приводила к тому, что аргумент flags игнорировался на некоторых файловых системах.

Поднимает auditing event os.setxattr с аргументами path, attribute, value, flags.

Изменено в версии 3.6: Принимает path-like object для пути и атрибута.

os.XATTR_SIZE_MAX¶: Максимальный размер значения расширенного атрибута. В настоящее время в Linux этот размер составляет 64 килобайта.

os.XATTR_CREATE¶: Это возможное значение аргумента flags в setxattr(). Оно указывает, что операция должна создать атрибут.

os.XATTR_REPLACE¶: Это возможное значение аргумента flags в setxattr(). Оно указывает на то, что операция должна заменить существующий атрибут.

Управление процессами¶

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

Различные функции 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 documentation.

Поднимает auditing event os.add_dll_directory с аргументом path.

Availability: Windows.

Added in version 3.8: Предыдущие версии CPython разрешали DLL, используя поведение по умолчанию для текущего процесса. Это приводило к несоответствиям, например, поиск PATH или текущей рабочей директории выполнялся лишь иногда, а функции ОС, такие как AddDllDirectory, не имели эффекта.

В 3.8 два основных способа загрузки библиотек DLL теперь явно переопределяют поведение всего процесса, чтобы обеспечить согласованность. Информацию об обновлении библиотек см. в porting notes.

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.

Текущий процесс заменяется немедленно. Открытые файловые объекты и дескрипторы не промываются, поэтому, если в этих открытых файлах могут быть буферизованные данные, их следует промыть с помощью sys.stdout.flush() или os.fsync() перед вызовом функции exec*.

Варианты «l» и «v» функций exec* различаются тем, как передаются аргументы командной строки. С вариантами «l», пожалуй, проще всего работать, если количество параметров фиксировано на момент написания кода; отдельные параметры просто становятся дополнительными параметрами функций execl*(). Варианты «v» хороши, когда количество параметров переменное, при этом аргументы передаются в виде списка или кортежа как параметр args. В любом случае аргументы дочернего процесса должны начинаться с имени выполняемой команды, но это не является обязательным.

Варианты, включающие букву «p» в конце (execlp(), execlpe(), execvp() и execvpe()), будут использовать переменную окружения PATH для нахождения программного файла. При замене окружения (в одном из вариантов exec*e, о котором речь пойдет в следующем параграфе) новое окружение используется в качестве источника переменной PATH. Другие варианты, execl(), execle(), execv() и execve(), не будут использовать переменную PATH для поиска исполняемого файла; path должен содержать соответствующий абсолютный или относительный путь. Относительные пути должны включать хотя бы одну косую черту, даже в Windows, так как простые имена не будут разрешены.

Для функций execle(), execlpe(), execve() и execvpe() (обратите внимание, что все они заканчиваются на «e») параметр env должен быть отображением, которое используется для определения переменных среды нового процесса (они используются вместо среды текущего процесса); функции execl(), execlp(), execv() и execvp() заставляют новый процесс наследовать среду текущего процесса.

Для execve() на некоторых платформах path также может быть указан как дескриптор открытого файла. Эта функциональность может не поддерживаться на вашей платформе; вы можете проверить, доступна ли она, используя os.supports_fd. Если она недоступна, ее использование вызовет ошибку NotImplementedError.

Поднимает auditing event os.exec с аргументами path, args, env.

Availability: Unix, Windows, не WASI, не iOS.

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

Изменено в версии 3.6: Принимает path-like object.

os._exit(n)¶: Выход из процесса со статусом n, без вызова обработчиков очистки, промывки буферов stdio и т.д.

Примечание

Стандартным способом выхода является sys.exit(n). _exit() обычно используется только в дочернем процессе после fork().

Следующие коды выхода определены и могут использоваться с _exit(), хотя они и не обязательны. Они обычно используются для системных программ, написанных на Python, таких как программа доставки внешних команд почтового сервера.

Примечание

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

os.EX_OK¶: Код выхода, означающий, что ошибки не произошло. На некоторых платформах может быть взят из определенного значения EXIT_SUCCESS. Обычно имеет нулевое значение.

Availability: Unix, Windows.

os.EX_USAGE¶: Код выхода, означающий, что команда была использована неверно, например, когда было задано неправильное количество аргументов.

Availability: Unix, не WASI.

os.EX_DATAERR¶: Код выхода, означающий, что входные данные были неверными.

Availability: Unix, не WASI.

os.EX_NOINPUT¶: Код выхода, означающий, что входной файл не существует или не может быть прочитан.

Availability: Unix, не WASI.

os.EX_NOUSER¶: Код выхода, означающий, что указанный пользователь не существует.

Availability: Unix, не WASI.

os.EX_NOHOST¶: Код выхода, означающий, что указанный хост не существует.

Availability: Unix, не WASI.

os.EX_UNAVAILABLE¶: Код выхода, означающий, что необходимая услуга недоступна.

Availability: Unix, не WASI.

os.EX_SOFTWARE¶: Код выхода, означающий, что была обнаружена внутренняя ошибка программного обеспечения.

Availability: Unix, не WASI.

os.EX_OSERR¶: Код выхода, означающий, что была обнаружена ошибка операционной системы, например, невозможность форка или создания трубы.

Availability: Unix, не WASI.

os.EX_OSFILE¶: Код выхода, означающий, что какой-то системный файл не существует, его не удалось открыть или произошла какая-то другая ошибка.

Availability: Unix, не WASI.

os.EX_CANTCREAT¶: Код выхода, означающий, что указанный пользователем выходной файл создать не удалось.

Availability: Unix, не WASI.

os.EX_IOERR¶: Код выхода, означающий, что при выполнении ввода-вывода некоторого файла произошла ошибка.

Availability: Unix, не WASI.

os.EX_TEMPFAIL¶: Код выхода, означающий, что произошел временный сбой. Это указывает на то, что на самом деле может и не быть ошибкой, например, сетевое соединение не удалось установить во время операции, которую можно повторить.

Availability: Unix, не WASI.

os.EX_PROTOCOL¶: Код выхода, означающий, что обмен протоколами был незаконным, недействительным или непонятным.

Availability: Unix, не WASI.

os.EX_NOPERM¶: Код выхода, означающий, что для выполнения операции не хватило прав (но не предназначенный для проблем с файловой системой).

Availability: Unix, не WASI.

os.EX_CONFIG¶: Код выхода, означающий, что произошла какая-то ошибка конфигурации.

Availability: Unix, не WASI.

os.EX_NOTFOUND¶: Код выхода, означающий что-то вроде «запись не найдена».

Availability: Unix, не WASI.

os.fork()¶

Форк дочернего процесса. Возвращает 0 в дочернем процессе и идентификатор дочернего процесса в родительском. При возникновении ошибки возвращается OSError.

Обратите внимание, что для некоторых платформ, включая FreeBSD <= 6.3 и Cygwin, известны проблемы с использованием fork() из потока.

Поднимает auditing event os.fork без аргументов.

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

Если вы используете TLS-сокеты в приложении, вызывающем fork(), обратитесь к предупреждению в документации ssl.

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

В macOS использование этой функции небезопасно в сочетании с использованием системных API более высокого уровня, включая использование urllib.request.

Изменено в версии 3.8: Вызов fork() в субинтерпретаторе больше не поддерживается (RuntimeError поднимается).

Изменено в версии 3.12: Если Python сможет обнаружить, что ваш процесс имеет несколько потоков, os.fork() теперь будет вызывать DeprecationWarning.

Мы решили вынести это на экран в качестве предупреждения, когда это можно обнаружить, чтобы лучше проинформировать разработчиков о проблеме проектирования, которую платформа POSIX специально отмечает как не поддерживаемую. Даже в коде, который кажется работающим, никогда не было безопасно смешивать потоки с os.fork() на POSIX-платформах. Сама среда выполнения CPython всегда делала вызовы API, которые небезопасно использовать в дочернем процессе, если в родительском существовали потоки (например, malloc и free).

Пользователи macOS, а также пользователи реализаций libc или malloc, отличных от тех, что обычно встречаются в glibc на сегодняшний день, относятся к числу тех, кто с большей вероятностью столкнется с тупиковыми ситуациями при выполнении такого кода.

Технические подробности о том, почему мы сообщаем разработчикам об этой давней проблеме совместимости платформ, см. в разделе this discussion on fork being incompatible with threads.

Availability: POSIX, не WASI, не iOS.

os.forkpty()¶

Форк дочернего процесса, используя новый псевдотерминал в качестве управляющего терминала дочернего процесса. Возвращает пару (pid, fd), где pid - это 0 в дочернем процессе, id нового дочернего процесса в родительском, а fd - это дескриптор файла главного конца псевдотерминала. Для более переносимого подхода используйте модуль pty. При возникновении ошибки вызывается OSError.

Поднимает auditing event os.forkpty без аргументов.

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

В macOS использование этой функции небезопасно в сочетании с использованием системных API более высокого уровня, включая использование urllib.request.

Изменено в версии 3.8: Вызов forkpty() в субинтерпретаторе больше не поддерживается (RuntimeError поднимается).

Изменено в версии 3.12: Если Python обнаруживает, что ваш процесс имеет несколько потоков, то теперь это вызывает ошибку DeprecationWarning. См. более подробное объяснение os.fork().

Availability: Unix, не WASI, не iOS.

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().

Поднимает auditing event os.kill с аргументами pid, sig.

Availability: Unix, Windows, не WASI, не iOS.

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

os.killpg(pgid, sig, /)¶

Отправьте сигнал sig группе процессов pgid.

Поднимает auditing event os.killpg с аргументами pgid, sig.

Availability: Unix, не WASI, не iOS.

os.nice(increment, /)¶: Добавьте инкремент к «приятности» процесса. Верните новую «приятность».

Availability: Unix, не WASI.

os.pidfd_open(pid, flags=0)¶

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

Дополнительные сведения см. на странице pidfd_open(2).

Availability: Linux >= 5.3

Added in version 3.9.

os.PIDFD_NONBLOCK¶: Этот флаг указывает на то, что дескриптор файла будет неблокируемым. Если процесс, на который ссылается файловый дескриптор, еще не завершился, то попытка ожидания на файловом дескрипторе с использованием waitid(2) немедленно вернет ошибку EAGAIN, а не блокировку.

Availability: Linux >= 5.10

Added in version 3.12.

os.plock(op, /)¶: Заблокировать сегменты программы в памяти. Значение op (определено в <sys/lock.h>) определяет, какие сегменты будут заблокированы.

Availability: Unix, не WASI, не iOS.

os.popen(cmd, mode='r', buffering=-1)¶

Открыть трубу к команде cmd или от нее. Возвращаемое значение - открытый файловый объект, подключенный к трубе, который может быть прочитан или записан в зависимости от того, имеет ли mode значение 'r' (по умолчанию) или 'w'. Аргумент буферизация имеет то же значение, что и соответствующий аргумент встроенной функции open(). Возвращаемый файловый объект читает или записывает текстовые строки, а не байты.

Метод close возвращает None, если подпроцесс завершился успешно, или код возврата подпроцесса, если произошла ошибка. В POSIX-системах, если код возврата положительный, он представляет собой значение возврата процесса, сдвинутое влево на один байт. Если код возврата отрицательный, процесс был завершен сигналом, заданным отрицательным значением кода возврата. (Например, значение возврата может быть - signal.SIGKILL, если подпроцесс был убит.) В системах Windows значение возврата содержит подписанный целочисленный код возврата дочернего процесса.

В Unix waitstatus_to_exitcode() можно использовать для преобразования результата метода close (статус выхода) в код выхода, если он не является None. В Windows результат метода close является непосредственно кодом выхода (или None).

Это реализовано с помощью subprocess.Popen; о более мощных способах управления и взаимодействия с подпроцессами читайте в документации к этому классу.

Availability: не WASI, не iOS.

Примечание

Значение Python UTF-8 Mode влияет на кодировки, используемые для 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)¶

Обертывает posix_spawn() API библиотеки C для использования из Python.

Большинство пользователей должны использовать subprocess.run() вместо posix_spawn().

Только позиционные аргументы path, args и env аналогичны execve(). Для env допускается значение None, в этом случае используется окружение текущего процесса.

Параметр 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).

os.POSIX_SPAWN_CLOSEFROM¶

(os.POSIX_SPAWN_CLOSEFROM, fd)

Выполняет os.closerange(fd, INF).

Эти кортежи соответствуют библиотеке Си posix_spawn_file_actions_addopen(), posix_spawn_file_actions_addclose(), posix_spawn_file_actions_adddup2() и posix_spawn_file_actions_addclosefrom_np(). API-вызовам, используемым для подготовки к самому вызову 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 устанавливает маску сигнала на указанный набор сигналов. Если параметр не используется, то дочерняя функция наследует сигнальную маску родительской. Этот аргумент соответствует флагу POSIX_SPAWN_SETSIGMASK библиотеки C.

Аргумент sigdef сбрасывает диспозицию всех сигналов в указанном наборе. Этот аргумент соответствует флагу POSIX_SPAWN_SETSIGDEF библиотеки C.

Аргумент scheduler должен быть кортежем, содержащим (необязательную) политику планировщика и экземпляр sched_param с параметрами планировщика. Значение None вместо политики планировщика означает, что она не предоставляется. Этот аргумент представляет собой комбинацию флагов библиотеки C POSIX_SPAWN_SETSCHEDPARAM и POSIX_SPAWN_SETSCHEDULER.

Поднимает auditing event os.posix_spawn с аргументами path, argv, env.

Added in version 3.8.

Изменено в версии 3.13: Параметр env принимает значение None. os.POSIX_SPAWN_CLOSEFROM доступен на платформах, где существует posix_spawn_file_actions_addclosefrom_np().

Availability: Unix, не WASI, не iOS.

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)¶

Обертывает posix_spawnp() API библиотеки C для использования из Python.

Аналогично posix_spawn(), за исключением того, что система ищет исполняемый файл в списке каталогов, указанных переменной окружения PATH (так же, как и для execvp(3)).

Поднимает auditing event os.posix_spawn с аргументами path, argv, env.

Added in version 3.8.

Availability: POSIX, не WASI, не iOS.

См. документацию 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(), выполняемые сторонним Си-кодом, не могут вызывать эти функции, если только они не вызывают PyOS_BeforeFork(), PyOS_AfterFork_Parent() и PyOS_AfterFork_Child() явно.

Не существует способа отменить регистрацию функции.

Availability: Unix, не WASI, не iOS.

Added in version 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.

Варианты «l» и «v» функций spawn* различаются тем, как передаются аргументы командной строки. С вариантами «l», пожалуй, проще всего работать, если количество параметров фиксировано на момент написания кода; отдельные параметры просто становятся дополнительными параметрами функций spawnl*(). Варианты «v» хороши, когда количество параметров переменное, при этом аргументы передаются в виде списка или кортежа как параметр args. В любом случае аргументы дочернего процесса должны начинаться с имени выполняемой команды.

Варианты, включающие вторую букву «p» в конце (spawnlp(), spawnlpe(), spawnvp() и spawnvpe()), будут использовать переменную окружения PATH для нахождения программного файла. При замене окружения (в одном из вариантов 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)

Поднимает auditing event os.spawn с аргументами mode, path, args, env.

Availability: Unix, Windows, не WASI, не iOS.

Модули spawnlp(), spawnlpe(), spawnvp() и spawnvpe() недоступны в Windows. spawnle() и spawnve() не являются потокобезопасными в Windows; мы советуем вам использовать вместо них модуль subprocess.

Изменено в версии 3.6: Принимает path-like object.

os.P_NOWAIT¶
os.P_NOWAITO¶: Возможные значения параметра mode для семейства функций spawn*. Если задано одно из этих значений, функции spawn* вернутся, как только будет создан новый процесс, с идентификатором процесса в качестве возвращаемого значения.

Availability: Unix, Windows.

os.P_WAIT¶: Возможное значение параметра mode для семейства функций spawn*. Если указать mode, функции spawn* не вернутся, пока новый процесс не будет запущен до конца, и вернут код выхода процесса, если запуск был успешным, или -signal, если сигнал завершил процесс.

Availability: Unix, Windows.

os.P_DETACH¶
os.P_OVERLAY¶: Возможные значения параметра mode для семейства функций spawn*. Они менее переносимы, чем перечисленные выше. P_DETACH аналогична P_NOWAIT, но новый процесс отделяется от консоли вызывающего процесса. Если используется P_OVERLAY, текущий процесс будет заменен; функция spawn* не возвращается.

Availability: Windows.

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])¶

Запуск файла с помощью связанного с ним приложения.

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

Когда указывается другая операция, это должен быть «командный глагол», определяющий, что нужно сделать с файлом. Обычно Microsoft документирует следующие глаголы: 'open', 'print' и 'edit' (используются для файлов), а также 'explore' и 'find' (используются для каталогов).

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

Рабочая директория по умолчанию наследуется, но может быть переопределена аргументом cwd. Это должен быть абсолютный путь. Относительный путь будет разрешен относительно этого аргумента.

Используйте show_cmd, чтобы отменить стиль окна по умолчанию. Будет ли это иметь какой-либо эффект, зависит от запускаемого приложения. Значения - целые числа, поддерживаемые функцией Win32 ShellExecute().

startfile() возвращается, как только запускается связанное с ним приложение. Нет возможности подождать, пока приложение закроется, и нет способа получить статус выхода приложения. Параметр path является относительным к текущему каталогу или cwd. Если вы хотите использовать абсолютный путь, убедитесь, что первый символ не является косой чертой ('/'). Используйте функцию pathlib или os.path.normpath(), чтобы убедиться, что пути правильно закодированы для Win32.

Чтобы уменьшить нагрузку при запуске интерпретатора, функция Win32 ShellExecute() не разрешается до первого вызова этой функции. Если функция не может быть разрешена, будет вызвана функция NotImplementedError.

Поднимает auditing event os.startfile с аргументами path, operation.

Поднимает auditing event os.startfile/2 с аргументами path, operation, arguments, cwd, show_cmd.

Availability: Windows.

Изменено в версии 3.10: Добавлены аргументы arguments, cwd и show_cmd, а также событие аудита os.startfile/2.

os.system(command)¶

Выполнить команду (строку) в подоболочке. Это реализовано вызовом стандартной функции Си system() и имеет те же ограничения. Изменения в sys.stdin и т. д. не отражаются в окружении выполняемой команды. Если команда генерирует какой-либо вывод, он будет отправлен в стандартный поток вывода интерпретатора. Стандарт C не определяет значение возвращаемого значения функции C, поэтому возвращаемое значение функции Python зависит от системы.

В Unix возвращаемым значением является статус завершения процесса, закодированный в формате, указанном для wait().

В Windows возвращаемое значение - это значение, возвращаемое системной оболочкой после выполнения команды. Оболочка задается переменной окружения Windows COMSPEC: обычно это cmd.exe, которая возвращает статус завершения выполнения команды; в системах, использующих неродную оболочку, обратитесь к документации по оболочке.

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

В Unix waitstatus_to_exitcode() можно использовать для преобразования результата (статуса выхода) в код выхода. В Windows результатом является непосредственно код выхода.

Поднимает auditing event os.system с аргументом command.

Availability: Unix, Windows, не WASI, не iOS.

os.times()¶

Возвращает текущее время глобального процесса. Возвращаемое значение - объект с пятью атрибутами:

user - время пользователя
system - системное время
children_user - пользовательское время всех дочерних процессов
children_system - системное время всех дочерних процессов
elapsed - прошедшее реальное время с фиксированного момента в прошлом

Для обратной совместимости этот объект также ведет себя как кортеж из пяти элементов, содержащий user, system, children_user, children_system и elapsed в таком порядке.

См. страницу руководства times(2) в Unix и страницу руководства times(3) в Unix или the GetProcessTimes MSDN в Windows. В Windows известны только user и system; остальные атрибуты равны нулю.

Availability: Unix, Windows.

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

os.wait()¶

Дождитесь завершения дочернего процесса и верните кортеж, содержащий его pid и признак статуса завершения: 16-битное число, младший байт которого - номер сигнала, убившего процесс, а старший байт - статус завершения (если номер сигнала равен нулю); старший бит младшего байта установлен, если был создан файл ядра.

Если нет детей, которых можно было бы дождаться, поднимается значение ChildProcessError.

waitstatus_to_exitcode() можно использовать для преобразования статуса выхода в код выхода.

Availability: Unix, не WASI, не iOS.

См.также

Другие функции wait*(), описанные ниже, могут использоваться для ожидания завершения определенного дочернего процесса и имеют больше возможностей. waitpid() - единственная функция, которая также доступна в Windows.

os.waitid(idtype, id, options, /)¶

Ожидание завершения дочернего процесса.

idtype может быть P_PID, P_PGID, P_ALL или (в Linux) P_PIDFD. От этого зависит интерпретация id; см. их индивидуальные описания.

options - это комбинация флагов в формате OR. Хотя бы один из 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.

Availability: Unix, не WASI, не iOS.

Added in version 3.3.

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

os.waitpid(pid, options, /)¶

Детали этой функции отличаются в Unix и Windows.

На Unix: Дождитесь завершения дочернего процесса, заданного идентификатором процесса pid, и верните кортеж, содержащий его идентификатор процесса и признак состояния завершения (в кодировке wait()). Семантика вызова зависит от значения целого числа options, которое для нормальной работы должно быть 0.

Если pid больше 0, waitpid() запрашивает информацию о состоянии конкретного процесса. Если pid равен 0, запрос касается статуса любого дочернего процесса в группе процессов текущего процесса. Если pid равен -1, запрос относится к любому дочернему процессу текущего процесса. Если pid меньше -1, статус запрашивается для любого процесса в группе процессов -pid (абсолютное значение pid).

options - это комбинация флагов по принципу ИЛИ. Если она содержит WNOHANG и нет подходящих детей в запрашиваемом состоянии, возвращается (0, 0). В противном случае, если нет подходящих детей, которых можно было бы дождаться, возвращается ChildProcessError. Другие варианты, которые могут быть использованы, это WUNTRACED и WCONTINUED.

В Windows: Дождитесь завершения процесса, заданного хэндлом процесса pid, и верните кортеж, содержащий pid и его статус завершения, сдвинутый влево на 8 бит (сдвиг облегчает кроссплатформенное использование функции). Значение pid, меньшее или равное 0, не имеет специального значения в Windows и вызывает исключение. Значение целочисленных options не имеет значения. pid может ссылаться на любой процесс, чей id известен, не обязательно на дочерний процесс. Функции spawn*, вызываемые с помощью P_NOWAIT, возвращают соответствующие дескрипторы процессов.

waitstatus_to_exitcode() можно использовать для преобразования статуса выхода в код выхода.

Availability: Unix, Windows, не WASI, не iOS.

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

os.wait3(options)¶

Аналогично waitpid(), за исключением того, что аргумент идентификатора процесса не задается, и возвращается трехэлементный кортеж, содержащий идентификатор дочернего процесса, индикацию статуса завершения и информацию об использовании ресурсов. Подробнее об информации об использовании ресурсов см. в resource.getrusage(). Аргумент options такой же, как и в waitpid() и wait4().

waitstatus_to_exitcode() можно использовать для преобразования статуса выхода в код выхода.

Availability: Unix, не WASI, не iOS.

os.wait4(pid, options)¶

Аналогично waitpid(), за исключением того, что возвращается трехэлементный кортеж, содержащий идентификатор дочернего процесса, признак состояния завершения и информацию об использовании ресурсов. Подробнее об информации об использовании ресурсов см. в resource.getrusage(). Аргументы для wait4() те же, что и для waitpid().

waitstatus_to_exitcode() можно использовать для преобразования статуса выхода в код выхода.

Availability: Unix, не WASI, не iOS.

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()).

Availability: Unix, не WASI, не iOS.

Примечание

P_PIDFD доступен только в Linux >= 5.4.

Added in version 3.3.

Added in version 3.9: Константа P_PIDFD.

os.WCONTINUED¶: Этот флаг options для waitpid(), wait3(), wait4() и waitid() заставляет дочерние процессы сообщать, если они были продолжены после остановки управления заданиями с момента последнего сообщения.

Availability: Unix, не WASI, не iOS.

os.WEXITED¶

Этот флаг options для waitid() заставляет сообщать о дочерних процессах, которые завершились.

Другие функции wait* всегда сообщают о завершившихся дочерних элементах, поэтому эта опция для них недоступна.

Availability: Unix, не WASI, не iOS.

Added in version 3.3.

os.WSTOPPED¶

Этот флаг options для waitid() заставляет сообщать о дочерних процессах, которые были остановлены подачей сигнала.

Эта опция недоступна для других функций wait*.

Availability: Unix, не WASI, не iOS.

Added in version 3.3.

os.WUNTRACED¶

Этот флаг options для waitpid(), wait3() и wait4() заставляет дочерние процессы также получать отчет, если они были остановлены, но их текущее состояние не было сообщено с момента остановки.

Эта опция недоступна для waitid().

Availability: Unix, не WASI, не iOS.

os.WNOHANG¶: Этот флаг options заставляет waitpid(), wait3(), wait4() и waitid() возвращаться сразу, если статус дочернего процесса не доступен немедленно.

Availability: Unix, не WASI, не iOS.

os.WNOWAIT¶

Этот флаг options заставляет waitid() оставить ребенка в состоянии ожидания, так что последующий вызов wait*() может быть использован для повторного получения информации о состоянии ребенка.

Эта опция недоступна для других функций wait*.

Availability: Unix, не WASI, не iOS.

os.CLD_EXITED¶
os.CLD_KILLED¶
os.CLD_DUMPED¶
os.CLD_TRAPPED¶
os.CLD_STOPPED¶
os.CLD_CONTINUED¶: Это возможные значения для si_code в результате, возвращаемом waitid().

Availability: Unix, не WASI, не iOS.

Added in version 3.3.

Изменено в версии 3.9: Добавлены значения CLD_KILLED и CLD_STOPPED.

os.waitstatus_to_exitcode(status)¶

Преобразуйте статус ожидания в код выхода.

На Unix:

Если процесс завершился нормально (если WIFEXITED(status) равен true), верните статус завершения процесса (return WEXITSTATUS(status)): результат больше или равен 0.
Если процесс был завершен сигналом (если WIFSIGNALED(status) равен true), верните -signum, где signum - номер сигнала, вызвавшего завершение процесса (верните -WTERMSIG(status)): результат меньше 0.
В противном случае поднимите ValueError.

В Windows возвращается status, сдвинутый вправо на 8 бит.

В Unix, если процесс отслеживается или если waitpid() был вызван с опцией WUNTRACED, вызывающая сторона должна сначала проверить, истинен ли WIFSTOPPED(status). Эта функция не должна вызываться, если WIFSTOPPED(status) истинна.

См.также

Функции WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED(), WSTOPSIG().

Availability: Unix, Windows, не WASI, не iOS.

Added in version 3.9.

Следующие функции принимают в качестве параметра код состояния процесса, возвращаемый функциями system(), wait() или waitpid(). Они могут использоваться для определения состояния процесса.

os.WCOREDUMP(status, /)¶

Возвращает True, если для процесса был создан дамп ядра, в противном случае возвращает False.

Эту функцию следует использовать только в том случае, если WIFSIGNALED() истинно.

Availability: Unix, не WASI, не iOS.

os.WIFCONTINUED(status)¶

Возвращает True, если остановленный дочерний процесс был возобновлен посылкой SIGCONT (если процесс был продолжен после остановки управления заданием), в противном случае возвращает False.

См. опцию WCONTINUED.

Availability: Unix, не WASI, не iOS.

os.WIFSTOPPED(status)¶

Возвращает True, если процесс был остановлен подачей сигнала, в противном случае возвращает False.

WIFSTOPPED() возвращает True только в том случае, если вызов waitpid() был выполнен с помощью опции WUNTRACED или если процесс отслеживается (см. ptrace(2)).

Availability: Unix, не WASI, не iOS.

os.WIFSIGNALED(status)¶: Возвращает True, если процесс был завершен по сигналу, в противном случае возвращает False.

Availability: Unix, не WASI, не iOS.

os.WIFEXITED(status)¶: Верните True, если процесс завершился нормально, то есть вызовом exit() или _exit(), или возвратом из main(); в противном случае верните False.

Availability: Unix, не WASI, не iOS.

os.WEXITSTATUS(status)¶

Возвращает статус завершения процесса.

Эту функцию следует использовать только в том случае, если WIFEXITED() истинно.

Availability: Unix, не WASI, не iOS.

os.WSTOPSIG(status)¶

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

Эту функцию следует использовать только в том случае, если WIFSTOPPED() истинно.

Availability: Unix, не WASI, не iOS.

os.WTERMSIG(status)¶

Возвращает номер сигнала, вызвавшего завершение процесса.

Эту функцию следует использовать только в том случае, если WIFSIGNALED() истинно.

Availability: Unix, не WASI, не iOS.

Интерфейс к планировщику¶

Эти функции управляют тем, как операционная система распределяет процессорное время процесса. Они доступны только на некоторых платформах Unix. Для получения более подробной информации обратитесь к руководству по Unix.

Added in version 3.3.

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

os.SCHED_OTHER¶: Политика планирования по умолчанию.

os.SCHED_BATCH¶: Политика составления расписания для процессов, требовательных к процессору, которая старается сохранить интерактивность на остальной части компьютера.

os.SCHED_IDLE¶: Политика составления расписания для фоновых задач с низким приоритетом.

os.SCHED_SPORADIC¶: Политика составления расписания для спорадических серверных программ.

os.SCHED_FIFO¶: Политика составления расписания «первый пришел - первый ушел».

os.SCHED_RR¶: Политика планирования по круговой системе.

os.SCHED_RESET_ON_FORK¶: Этот флаг может быть ИЛИ с любой другой политикой планирования. Когда процесс с установленным флагом переходит в форк, политика планирования и приоритет его дочернего процесса сбрасываются до значения по умолчанию.

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 равен нулю, верните набор процессоров, на которые ограничен вызывающий поток текущего процесса.

См. также функцию process_cpu_count().

Разная информация о системе¶

os.confstr(name, /)¶

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

Если значение конфигурации, указанное name, не определено, возвращается None.

Если name является строкой и неизвестно, выдается сообщение ValueError. Если конкретное значение name не поддерживается хост-системой, даже если оно включено в confstr_names, выдается сообщение OSError с номером ошибки errno.EINVAL.

Availability: Unix.

os.confstr_names¶: Словарь, отображающий имена, принимаемые confstr(), на целочисленные значения, определенные для этих имен операционной системой хоста. Это можно использовать для определения набора имен, известных системе.

Availability: Unix.

os.cpu_count()¶

Возвращает количество логических процессоров в системе. Возвращает None, если не определено.

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

Added in version 3.4.

Изменено в версии 3.13: Если задан -X cpu_count или установлен PYTHON_CPU_COUNT, cpu_count() возвращает переопределенное значение n.

os.getloadavg()¶: Возвращает количество процессов в очереди выполнения системы, усредненное за последние 1, 5 и 15 минут, или выдает OSError, если среднее значение нагрузки недостижимо.

Availability: Unix.

os.process_cpu_count()¶

Получает количество логических процессоров, используемых вызывающим потоком текущего процесса. Возвращает None, если не определено. Оно может быть меньше cpu_count() в зависимости от сродства процессора.

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

Если задан -X cpu_count или установлен PYTHON_CPU_COUNT, process_cpu_count() возвращает переопределенное значение n.

См. также функции sched_getaffinity().

Added in version 3.13.

os.sysconf(name, /)¶: Возвращает целочисленные значения конфигурации системы. Если значение конфигурации, указанное name, не определено, возвращается -1. Комментарии относительно параметра name для confstr() применимы и здесь; словарь, содержащий информацию об известных именах, указан в sysconf_names.

Availability: Unix.

os.sysconf_names¶: Словарь, отображающий имена, принимаемые sysconf(), на целочисленные значения, определенные для этих имен операционной системой хоста. Это можно использовать для определения набора имен, известных системе.

Availability: 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¶: Путь к файлу нулевого устройства. Например: '/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).

Added in version 3.3.

Случайные числа¶

os.getrandom(size, flags=0)¶

Получите до size случайных байтов. Функция может вернуть меньше байт, чем запрошено.

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

getrandom() полагается на энтропию, собранную из драйверов устройств и других источников шума окружающей среды. Излишнее считывание большого количества данных негативно скажется на других пользователях устройств /dev/random и /dev/urandom.

Аргумент flags представляет собой битовую маску, которая может содержать ноль или более из следующих значений, объединенных вместе: os.GRND_RANDOM и GRND_NONBLOCK.

См. также Linux getrandom() manual page.

Availability: Linux >= 3.17.

Added in version 3.6.

os.urandom(size, /)¶

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

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

В Linux, если системный вызов getrandom() доступен, он используется в блокирующем режиме: блокируется до тех пор, пока не будет инициализирован системный пул энтропии urandom (128 бит энтропии собираются ядром). Обоснование см. в PEP 524. В Linux функцию getrandom() можно использовать для получения случайных байтов в неблокирующем режиме (используя флаг GRND_NONBLOCK) или для опроса до тех пор, пока не будет инициализирован системный пул случайной энтропии.

В 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 вместо устаревшего CryptGenRandom() используется BCryptGenRandom().

os.GRND_NONBLOCK¶

По умолчанию при чтении из /dev/random getrandom() блокируется, если нет случайных байтов, а при чтении из /dev/urandom блокируется, если пул энтропии еще не инициализирован.

Если флаг GRND_NONBLOCK установлен, то getrandom() не блокируется в этих случаях, а вместо этого сразу поднимает BlockingIOError.

Added in version 3.6.

os.GRND_RANDOM¶: Если этот бит установлен, то случайные байты берутся из пула /dev/random, а не из пула /dev/urandom.

Added in version 3.6.

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

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

Режим Python UTF-8¶

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

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

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

Запрос размера терминала¶

Наследование дескрипторов файлов¶

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

Дескрипторы файлов таймера¶

Расширенные атрибуты Linux¶

Управление процессами¶

Интерфейс к планировщику¶

Разная информация о системе¶

Случайные числа¶

Оглавление

Предыдущий раздел

Следующий раздел

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

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

Режим Python UTF-8¶

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

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

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

Запрос размера терминала¶

Наследование дескрипторов файлов¶

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

Дескрипторы файлов таймера¶

Расширенные атрибуты Linux¶

Управление процессами¶

Интерфейс к планировщику¶

Разная информация о системе¶

Случайные числа¶

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