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

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

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

Параметры filesystem encoding and error handler настраиваются при запуске Python с помощью функции PyConfig_Read(): смотрите filesystem_encoding и filesystem_errors, входящие в состав PyConfig.

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

Смотрите также locale encoding.

Режим Python UTF-8¶

Режим Python UTF-8 игнорирует 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 включен, если языковой стандарт LC_CTYPE равен C или POSIX при запуске Python (смотрите функцию PyConfig_Read()).

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

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

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

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

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

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

os.ctermid()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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.

Добавлено в версии 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() - это обратная функция.

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

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

os.fsdecode(filename)¶

Расшифруйте path-like имя файла из filesystem encoding and error handler; верните str без изменений.

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

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

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

os.fspath(path)¶

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

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

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

class os.PathLike¶

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

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

abstractmethod __fspath__()¶

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

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

os.getenv(key, default=None)¶

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

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

Availability: Unix, Windows.

os.getenvb(key, default=None)¶

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

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

Availability: Unix.

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

os.get_exec_path(env=None)¶

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

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

os.getegid()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.geteuid()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.getgid()¶

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

Availability: Unix.

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

os.getgrouplist(user, group, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.getgroups()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

Примечание

В Mac OS поведение 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, не Emscripten, не БЫЛ я.

os.getpgid(pid)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.getpgrp()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.getpid()¶

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

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

os.getppid()¶

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

Availability: Unix, Windows, не Emscripten, не БЫЛ я.

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

os.getpriority(which, who)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.PRIO_PROCESS¶

os.PRIO_PGRP¶

os.PRIO_USER¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.getresuid()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.getresgid()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.getuid()¶

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

Availability: Unix.

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

os.initgroups(username, gid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.putenv(key, value, /)¶

Присвойте переменной среды с именем key значение string 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, не Emscripten, не БЫЛ I.

os.seteuid(euid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.setgid(gid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.setgroups(groups, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

Примечание

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

os.setpgrp()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.setpgid(pid, pgrp, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.setpriority(which, who, priority)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.setregid(rgid, egid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

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

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.setreuid(ruid, euid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.getsid(pid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.setsid()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.setuid(uid, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

os.strerror(code, /)¶

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

os.supports_bytes_environ¶

True если тип собственной операционной системы для среды - bytes (например, False в Windows).

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

os.umask(mask, /)¶

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

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

os.uname()¶

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

• sysname - название операционной системы

• nodename - имя компьютера в сети (определяется реализацией)

• release - версия операционной системы

• version - версия операционной системы

• machine - идентификатор оборудования

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

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

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.

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

Эти функции создают новые 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)¶

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

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

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

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

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

os.device_encoding(fd)¶

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

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

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

os.dup(fd, /)¶

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

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

Availability: это был не я.

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

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

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

Availability: это был не я.

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

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

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

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.

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

os.fdatasync(fd)¶

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

Availability: Unix.

Примечание

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

os.fpathconf(fd, 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)¶

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

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

Availability: Unix, Windows.

os.ftruncate(fd, length, /)¶

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

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

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

os.isatty(fd, /)¶

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

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

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

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

Availability: Unix.

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

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

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

Availability: Unix.

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

os.login_tty(fd, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

Добавлено в версии 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

Добавлено в версии 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(). Их можно комбинировать с помощью побитового оператора OR |. Некоторые из них доступны не на всех платформах. Для получения описаний их доступности и использования обратитесь к странице руководства 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¶

Вышеуказанные константы доступны только в Mac OS.

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

os.O_ASYNC¶

os.O_DIRECT¶

os.O_DIRECTORY¶

os.O_NOFOLLOW¶

os.O_NOATIME¶

os.O_PATH¶

os.O_TMPFILE¶

os.O_SHLOCK¶

os.O_EXLOCK¶

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

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

os.openpty()¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.pipe()¶

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

Availability: Unix, Windows.

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

os.pipe2(flags, /)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

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

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

Availability: Unix, а не Emscripten.

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

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

Объявляет о намерении получить доступ к данным по определенному шаблону, что позволяет ядру выполнить оптимизацию. Совет применим к области файла, указанной в fd, начиная с offset и заканчивая len байтами. совет - это один из POSIX_FADV_NORMAL, POSIX_FADV_SEQUENTIAL, POSIX_FADV_RANDOM, POSIX_FADV_NOREUSE, POSIX_FADV_WILLNEED или POSIX_FADV_DONTNEED.

Availability: Unix.

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

os.POSIX_FADV_NORMAL¶

os.POSIX_FADV_SEQUENTIAL¶

os.POSIX_FADV_RANDOM¶

os.POSIX_FADV_NOREUSE¶

os.POSIX_FADV_WILLNEED¶

os.POSIX_FADV_DONTNEED¶

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

Availability: Unix.

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

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

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

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

Availability: Unix.

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

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.

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

os.RWF_NOWAIT¶

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

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

Availability: Linux >= 4.14.

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

os.RWF_HIPRI¶

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

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

Availability: Linux >= 4.6.

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

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

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

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

Availability: Unix.

Добавлено в версии 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.

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

os.RWF_DSYNC¶

Укажите эквивалент флага O_DSYNC os.open() для каждой записи. Этот эффект флага применяется только к диапазону данных, записанному системным вызовом.

Availability: Linux >= 4.7.

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

os.RWF_SYNC¶

Укажите эквивалент флага O_SYNC os.open() для каждой записи. Этот эффект флага применяется только к диапазону данных, записанному системным вызовом.

Availability: Linux >= 4.7.

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

os.RWF_APPEND¶

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

Availability: Linux >= 4.16.

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

os.read(fd, n, /)¶

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

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

Примечание

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

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

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

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

Скопируйте количество байт из файлового дескриптора 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, не Emscripten, не БЫЛ I.

Примечание

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

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

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

os.SF_NODISKIO¶

os.SF_MNOWAIT¶

os.SF_SYNC¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.SF_NOCACHE¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.set_blocking(fd, blocking, /)¶

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

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

Availability: Unix.

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

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

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

Перенесите количество байт из файлового дескриптора 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

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

os.SPLICE_F_MOVE¶

os.SPLICE_F_NONBLOCK¶

os.SPLICE_F_MORE¶

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

os.readv(fd, buffers, /)¶

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

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

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

Availability: Unix.

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

os.tcgetpgrp(fd, /)¶

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

Availability: Unix, как и я.

os.tcsetpgrp(fd, pg, /)¶

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

Availability: Unix, как и я.

os.ttyname(fd, /)¶

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

Availability: Unix.

os.write(fd, str, /)¶

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

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

Примечание

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

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

os.writev(fd, buffers, /)¶

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

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

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

Availability: Unix.

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

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

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

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

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

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

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

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

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

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

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

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

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

If effective_ids is 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() для проверки существования, читаемости, записи и исполняемости path, соответственно.

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. флаги могут принимать комбинацию (побитовое ИЛИ) из следующих значений (как определено в модуле stat):

• stat.UF_NODUMP

• stat.UF_IMMUTABLE

• stat.UF_APPEND

• stat.UF_OPAQUE

• stat.UF_NOUNLINK

• stat.UF_COMPRESSED

• stat.UF_HIDDEN

• stat.SF_ARCHIVED

• stat.SF_IMMUTABLE

• stat.SF_APPEND

• stat.SF_NOUNLINK

• stat.SF_SNAPSHOT

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

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

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

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

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

• stat.S_ISUID

• stat.S_ISGID

• stat.S_ENFMT

• stat.S_ISVTX

• stat.S_IREAD

• stat.S_IWRITE

• stat.S_IEXEC

• stat.S_IRWXU

• stat.S_IRUSR

• stat.S_IWUSR

• stat.S_IXUSR

• stat.S_IRWXG

• stat.S_IRGRP

• stat.S_IWGRP

• stat.S_IXGRP

• stat.S_IRWXO

• stat.S_IROTH

• stat.S_IWOTH

• stat.S_IXOTH

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

Примечание

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

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

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

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

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

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.

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

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

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

os.chroot(path)¶

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

Availability: Unix, не Emscripten, не БЫЛ I.

Изменено в версии 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 числовые флаги, например, chflags(), но не переходите по символьным ссылкам. Начиная с версии Python 3.3, это эквивалентно os.chflags(path, flags, follow_symlinks=False).

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

Availability: Unix, не Emscripten, не БЫЛ I.

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

os.lchmod(path, mode)¶

Измените режим 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, не Linux, FreeBSD >= 1.3, NetBSD >= 1.3, не OpenBSD

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

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, а не Emscripten.

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

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

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

os.listdir(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.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 цифры восьмеричного представления режима *), их значение зависит от платформы. На некоторых платформах они игнорируются, и для их установки следует явно вызвать 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.11.10: 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.

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

Availability: Unix, не Emscripten, не БЫЛ I.

Изменено в версии 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, не Emscripten, не БЫЛ I.

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

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

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

Эта функция также может поддерживать 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 и летнего времени.

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.

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

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

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

Добавлено в версии 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.

Добавлено в версии 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() path.

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

path¶

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

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

inode()¶

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

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

При первом, некэшированном вызове, системный вызов требуется в Windows, но не в Unix.

is_dir(*, follow_symlinks=True)¶

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

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

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

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

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

is_file(*, follow_symlinks=True)¶

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

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

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

is_symlink()¶

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

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

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

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

stat(*, follow_symlinks=True)¶

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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

См.также

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

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

Изменено в версии 3.6: Принимает значение 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¶

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

• время последнего изменения метаданных в Unix,

• время создания в Windows, выраженное в секундах.

st_atime_ns¶

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

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

st_mtime_ns¶

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

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

st_ctime_ns¶

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

• время последнего изменения метаданных в Unix,

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

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

Примечание

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

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

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

st_blocks¶

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

st_blksize¶

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

st_rdev¶

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

st_flags¶

Пользовательские флаги для файла.

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

st_gen¶

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

st_birthtime¶

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

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

st_fstype¶

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

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

st_rsize¶

Реальный размер файла.

st_creator¶

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

st_type¶

Тип файла.

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

st_file_attributes¶

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

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

st_reparse_tag¶

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

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

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

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

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

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

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

os.statvfs(path)¶

Выполните системный вызов a 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 (разрешает принудительную блокировку FS), 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.

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

os.supports_effective_ids¶

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

Значение этого выражения равно True, если os.access() поддерживает effective_ids=True на локальной платформе:

os.access in os.supports_effective_ids

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

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

os.supports_fd¶

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

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

os.chdir in os.supports_fd

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

os.supports_follow_symlinks¶

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

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

os.stat in os.supports_follow_symlinks

Добавлено в версии 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.

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

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

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

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

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

os.sync()¶

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

Availability: Unix.

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

os.truncate(path, length)¶

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

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

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

Availability: Unix, Windows.

Добавлено в версии 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. Они определяют время, установленное в path, и используются следующим образом:

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

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

• Если значение times равно None, а значение ns не указано, это эквивалентно указанию ns=(atime_ns, mtime_ns), где оба значения являются текущим временем.

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

Обратите внимание, что точное время, указанное вами здесь, может не быть возвращено при последующем вызове stat(), в зависимости от разрешения, с которым ваша операционная система регистрирует время доступа и изменения; см. stat(). Лучший способ сохранить точное время - использовать поля st_atime_ns и st_mtime_ns из объекта os.stat() result с параметром 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.