os — servizi di base del «sistema operativo»

Il modulo os contiene funzioni per l’accesso e il montaggio del filesystem, la redirezione e duplicazione del terminale, e le funzioni uname e urandom.

Funzioni generali

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

Restituisce una tupla (eventualmente una named tuple) contenente informazioni sulla macchina sottostante e/o sul suo sistema operativo. La tupla ha cinque campi nel seguente ordine, ciascuno dei quali è una stringa:

  • sysname – Il nome del sistema sottostante

  • nodename – Il nome di rete (può essere uguale a sysname)

  • release – La versione del sistema sottostante

  • version – La versione di MicroPython e la data di build

  • machine – Un identificatore per l’hardware sottostante (ad es. board, CPU)

os.urandom(n: int) → bytes

Restituisce un oggetto bytes con n byte casuali. La sorgente è crittograficamente adeguata su ogni cam supportata, sebbene l’implementazione vari a seconda della port:

  • Le cam STM32 (M4, M7, H7, H7+, PT, N6) usano la periferica RNG hardware dell’STM32.

  • Le cam i.MX RT1062 (RT1060) usano il TRNG hardware del chip.

  • Le cam Alif Ensemble (AE3) usano il servizio random hardware del Secure Enclave.

  • L’Arduino Nano 33 BLE Sense usa la periferica RNG hardware dell’nRF52.

  • L’Arduino Nano RP2040 Connect non ha un TRNG hardware; il PRNG del pico-sdk viene inizializzato e continuamente rimescolato con le sorgenti di entropia on-chip dell’RP2040.

Accesso al filesystem

os.chdir(path: str) → None

Cambia la directory corrente.

os.getcwd() → str

Ottiene la directory corrente.

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

Questa funzione restituisce un iteratore che produce tuple corrispondenti alle voci della directory che sta elencando. Senza argomenti elenca la directory corrente, altrimenti elenca la directory specificata da dir.

Le tuple hanno la forma (name, type, inode[, size]):

  • name è una stringa (o bytes se dir è un oggetto bytes) ed è il nome della voce;

  • type è un intero che specifica il tipo della voce, con 0x4000 per le directory e 0x8000 per i file regolari;

  • inode è un intero corrispondente all’inode del file, e può essere 0 per i filesystem che non hanno tale nozione.

  • size è un intero che può essere incluso a seconda del tipo di filesystem. Per le voci di file, size rappresenta la dimensione del file, o -1 se sconosciuta. Il suo significato è attualmente indefinito per le voci di directory.

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

Senza argomenti, elenca la directory corrente. Altrimenti elenca la directory specificata.

os.mkdir(path: str) → None

Crea una nuova directory.

os.remove(path: str) → None

Rimuove un file.

Rimuove un file. Questo è un alias di remove().

os.rmdir(path: str) → None

Rimuove una directory.

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

Rinomina un file.

os.stat(path: str) → Tuple

Ottiene lo stato di un file o di una directory.

os.statvfs(path: str) → Tuple

Ottiene lo stato di un filesystem.

Restituisce una tupla con le informazioni del filesystem nel seguente ordine:

  • f_bsize – Dimensione del blocco del filesystem

  • f_frsize – Dimensione del frammento

  • f_blocks – Dimensione del fs in unità f_frsize

  • f_bfree – Numero di blocchi liberi

  • f_bavail – Numero di blocchi liberi per gli utenti non privilegiati

  • f_files – Numero di inode

  • f_ffree – Numero di inode liberi

  • f_favail – Numero di inode liberi per gli utenti non privilegiati

  • f_flag – Flag di mount

  • f_namemax – Lunghezza massima del nome del file

Parametri relativi agli inode: f_files, f_ffree, f_favail e il parametro f_flag possono restituire 0 in quanto possono non essere disponibili in un’implementazione specifica della port.

os.sync() → None

Sincronizza tutti i filesystem.

os.sep: str

Il separatore dei componenti di percorso usato dal filesystem, la stringa '/'.

Redirezione e duplicazione del terminale

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

Duplica o commuta il terminale MicroPython (il REPL) sull’oggetto di tipo stream specificato. L’argomento stream_object deve essere un oggetto stream nativo, oppure derivare da io.IOBase e implementare i metodi readinto() e write(). Lo stream dovrebbe essere in modalità non bloccante e readinto() dovrebbe restituire None se non vi sono dati disponibili per la lettura.

Dopo la chiamata a questa funzione tutto l’output del terminale viene ripetuto su questo stream, e qualsiasi input disponibile sullo stream viene passato all’input del terminale.

Il parametro index dovrebbe essere un intero non negativo e specifica quale slot di duplicazione viene impostato. Una determinata port può implementare più di uno slot (lo slot 0 sarà sempre disponibile) e in tal caso l’input e l’output del terminale vengono duplicati su tutti gli slot impostati.

Se viene passato None come stream_object, la duplicazione viene annullata sullo slot specificato da index.

La funzione restituisce il precedente oggetto di tipo stream nello slot specificato.

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

Notifica al REPL di MicroPython che è disponibile input su un oggetto di tipo stream precedentemente registrato tramite os.dupterm().

Questa funzione dovrebbe essere chiamata da implementazioni di stream personalizzate (ad es. UART, Bluetooth o altri stream REPL non USB) per informare il REPL che l’input è pronto per la lettura. Un uso corretto garantisce che caratteri speciali come Ctrl+C (usato per attivare KeyboardInterrupt) vengano elaborati prontamente dal REPL, abilitando il comportamento di interruzione atteso per il codice utente.

Il parametro obj_in viene ignorato da os.dupterm_notify(), ma è richiesto per consentire la chiamata di dupterm_notify da un handler di interrupt come UART.irq().

Esempio:

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

Nota

Se la funzione dupterm_notify() non viene chiamata, l’input dallo stream personalizzato potrebbe non essere rilevato o elaborato fino al successivo poll del REPL, ritardando potenzialmente i KeyboardInterrupt o altri segnali di controllo. Questo è particolarmente importante per UART, Bluetooth e altre connessioni REPL non standard, dove la notifica automatica non è garantita.

Montaggio del filesystem

Le seguenti funzioni e classi sono state spostate nel modulo vfs. Sono fornite in questo modulo solo per retrocompatibilità e verranno rimosse nella versione 2 di MicroPython.

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

Monta l’oggetto filesystem fsobj nella posizione del VFS specificata dalla stringa mount_point. fsobj può essere un oggetto VFS che ha un metodo mount(), oppure un block device. Se è un block device il tipo di filesystem viene rilevato automaticamente (viene sollevata un’eccezione se nessun filesystem viene riconosciuto). mount_point può essere '/' per montare fsobj nella root, oppure '/<name>' per montarlo in una sottodirectory sotto la root.

Se readonly è True allora il filesystem viene montato in sola lettura.

Durante il processo di montaggio viene chiamato il metodo mount() sull’oggetto filesystem.

Solleva OSError(EPERM) se mount_point è già montato.

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

Senza argomenti a mount(), restituisce una lista di tuple che rappresentano tutti i punti di montaggio attivi.

La lista restituita ha la forma [(fsobj, mount_point), …].

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

Smonta un filesystem. mount_point può essere una stringa che nomina la posizione di montaggio, oppure un oggetto filesystem precedentemente montato. Durante il processo di smontaggio viene chiamato il metodo umount() sull’oggetto filesystem.

Solleva OSError(EINVAL) se mount_point non viene trovato.

class os.VfsFat(block_dev: AbstractBlockDev)

Crea un oggetto filesystem che usa il formato di filesystem FAT. L’archiviazione del filesystem FAT è fornita da block_dev. Gli oggetti creati da questo costruttore possono essere montati usando mount().

static mkfs(block_dev: AbstractBlockDev) → None

Costruisce un filesystem FAT su block_dev.

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

Crea un oggetto filesystem che accede al filesystem POSIX dell’host. Se viene specificato root, esso dovrebbe essere un percorso nel filesystem dell’host da usare come root dell’oggetto VfsPosix. Altrimenti viene usata la directory corrente del filesystem dell’host.

Nota

VfsPosix è disponibile solo sulla port Unix; non è presente sull’OpenMV Cam.