os — базові служби «операційної системи»

Модуль os містить функції для доступу до файлової системи та монтування, перенаправлення та дублювання терміналу, а також функції uname та urandom.

Загальні функції

os.uname() → Tuple[str, str, str, str, str]

Повертає кортеж (можливо, іменований) із відомостями про апаратне забезпечення та/або його операційну систему. Кортеж містить п’ять полів у наступному порядку, кожне з яких є рядком:

  • sysname – назва базової системи

  • nodename – мережева назва (може збігатися з sysname)

  • release – версія базової системи

  • version – версія MicroPython та дата збірки

  • machine – ідентифікатор апаратного забезпечення (наприклад, плати, CPU)

os.urandom(n: int) → bytes

Повертає байтовий об’єкт із n випадковими байтами. Джерело є криптографічно придатним на всіх підтримуваних камерах, хоча реалізація залежить від порту:

  • Камери STM32 (M4, M7, H7, H7+, PT, N6) використовують апаратний периферійний пристрій RNG STM32.

  • Камери i.MX RT1062 (RT1060) використовують апаратний TRNG чіпа.

  • Камери Alif Ensemble (AE3) використовують апаратну службу випадкових чисел Secure Enclave.

  • Arduino Nano 33 BLE Sense використовує апаратний периферійний пристрій RNG nRF52.

  • Arduino Nano RP2040 Connect не має апаратного TRNG; PRNG з pico-sdk ініціалізується та постійно перемішується з джерелами ентропії RP2040 на кристалі.

Доступ до файлової системи

os.chdir(path: str) → None

Змінює поточний каталог.

os.getcwd() → str

Отримує поточний каталог.

os.ilistdir(dir: str | None = None) → Iterator[Tuple]

Ця функція повертає ітератор, який видає кортежі, що відповідають записам у переглядуваному каталозі. Без аргументів виводить поточний каталог, інакше — каталог, заданий параметром dir.

Кортежі мають вигляд (name, type, inode[, size]):

  • name — рядок (або байти, якщо dir є байтовим об’єктом) із назвою запису;

  • type — ціле число, що визначає тип запису: 0x4000 для каталогів і 0x8000 для звичайних файлів;

  • inode — ціле число, що відповідає inode файлу; може дорівнювати 0 для файлових систем, де це поняття відсутнє.

  • size — ціле число, наявність якого залежить від типу файлової системи. Для файлових записів size означає розмір файлу або -1, якщо він невідомий. Для записів каталогів значення наразі не визначено.

os.listdir(dir: str | None = None) → List[str]

Без аргументів виводить поточний каталог. Інакше — заданий каталог.

os.mkdir(path: str) → None

Створює новий каталог.

os.remove(path: str) → None

Видаляє файл.

Видаляє файл. Є псевдонімом для remove().

os.rmdir(path: str) → None

Видаляє каталог.

os.rename(old_path: str, new_path: str) → None

Перейменовує файл.

os.stat(path: str) → Tuple

Отримує інформацію про файл або каталог.

os.statvfs(path: str) → Tuple

Отримує інформацію про файлову систему.

Повертає кортеж з інформацією про файлову систему в наступному порядку:

  • f_bsize – розмір блоку файлової системи

  • f_frsize – розмір фрагмента

  • f_blocks – розмір файлової системи в одиницях f_frsize

  • f_bfree – кількість вільних блоків

  • f_bavail – кількість вільних блоків для непривілейованих користувачів

  • f_files – кількість inode

  • f_ffree – кількість вільних inode

  • f_favail – кількість вільних inode для непривілейованих користувачів

  • f_flag – прапорці монтування

  • f_namemax – максимальна довжина імені файлу

Параметри, пов’язані з inode: f_files, f_ffree, f_favail і параметр f_flag можуть повертати 0, оскільки вони можуть бути недоступні в реалізації для конкретного порту.

os.sync() → None

Синхронізує всі файлові системи.

os.sep: str

Роздільник компонентів шляху, що використовується файловою системою, — рядок '/'.

Перенаправлення та дублювання терміналу

os.dupterm(stream_object: Any, index: int = 0, /) → Any

Дублює або перемикає термінал MicroPython (REPL) на заданий об’єкт типу stream. Аргумент stream_object має бути рідним потоковим об’єктом або успадковуватися від io.IOBase та реалізовувати методи readinto() і write(). Потік має бути в неблокуючому режимі, а readinto() повинен повертати None, якщо даних для читання немає.

Після виклику цієї функції весь вивід терміналу дублюється на цьому потоці, а будь-який ввід, доступний у потоці, передається на вхід терміналу.

Параметр index має бути невід’ємним цілим числом і вказує, який слот дублювання встановлюється. Порт може реалізовувати більше одного слота (слот 0 завжди доступний); у цьому випадку ввід та вивід терміналу дублюються на всіх встановлених слотах.

Якщо як stream_object передається None, дублювання скасовується для слота, заданого параметром index.

Функція повертає попередній потоковий об’єкт у заданому слоті.

os.dupterm_notify(obj_in: Any, /) → None

Повідомляє MicroPython REPL про наявність вводу в потоковому об’єкті, раніше зареєстрованому через os.dupterm().

Ця функція має викликатися власними реалізаціями потоків (наприклад, UART, Bluetooth або інших не-USB REPL потоків), щоб повідомити REPL про готовність вводу до читання. Правильне використання гарантує своєчасну обробку спеціальних символів, таких як Ctrl+C (для генерації KeyboardInterrupt), що забезпечує очікувану поведінку переривання для коду користувача.

Параметр obj_in ігнорується функцією os.dupterm_notify(), але необхідний для можливості виклику dupterm_notify з обробника переривання, наприклад UART.irq().

Приклад:

from machine import UART
import os
uart = UART(0)
os.dupterm(uart, 0)
uart.irq(os.dupterm_notify, machine.UART.IRQ_RX)

Примітка

Якщо функція dupterm_notify() не викликається, ввід із власного потоку може не виявлятися та не оброблятися до наступного опитування REPL, що може затримати KeyboardInterrupt або інші керуючі сигнали. Це особливо важливо для UART, Bluetooth та інших нестандартних REPL-з’єднань, де автоматичне сповіщення не гарантується.

Монтування файлових систем

Наступні функції та класи перенесено до модуля vfs. Вони надаються в цьому модулі лише для зворотної сумісності та будуть видалені у версії 2 MicroPython.

os.mount(fsobj: Any, mount_point: str, *, readonly: bool = False) → None

Монтує об’єкт файлової системи fsobj у розташуванні VFS, заданому рядком mount_point. fsobj може бути об’єктом VFS із методом mount() або блоковим пристроєм. Якщо це блоковий пристрій, тип файлової системи визначається автоматично (якщо файлову систему не вдається розпізнати, генерується виключення). mount_point може бути '/' для монтування fsobj у корені або '/<name>' для монтування в підкаталозі кореня.

Якщо readonly має значення True, файлова система монтується лише для читання.

Під час монтування на об’єкті файлової системи викликається метод mount().

Генерує OSError(EPERM), якщо mount_point вже змонтовано.

os.mount() → List[Tuple[Any, str]]

При виклику mount() без аргументів повертає список кортежів, що представляють усі активні точки монтування.

Повернений список має вигляд [(fsobj, mount_point), …].

os.umount(mount_point: str | Any) → None

Демонтує файлову систему. mount_point може бути рядком із назвою точки монтування або раніше змонтованим об’єктом файлової системи. Під час демонтування на об’єкті файлової системи викликається метод umount().

Генерує OSError(EINVAL), якщо mount_point не знайдено.

class os.VfsFat(block_dev: AbstractBlockDev)

Створює об’єкт файлової системи у форматі FAT. Сховище для файлової системи FAT забезпечується block_dev. Об’єкти, створені цим конструктором, можна монтувати за допомогою mount().

static mkfs(block_dev: AbstractBlockDev) → None

Форматує файлову систему FAT на block_dev.

class os.VfsPosix(root: str | None = None)

Створює об’єкт файлової системи, що забезпечує доступ до файлової системи POSIX хоста. Якщо root вказано, це має бути шлях у файловій системі хоста, який використовуватиметься як корінь об’єкта VfsPosix. Інакше використовується поточний каталог файлової системи хоста.

Примітка

VfsPosix доступний лише на порті Unix; на OpenMV Cam він відсутній.