os — serviços básicos do «sistema operativo»

O módulo os contém funções para acesso ao sistema de ficheiros e montagem, redirecionamento e duplicação do terminal, e as funções uname e urandom.

Funções gerais

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

Devolve um tuplo (possivelmente um tuplo nomeado) com informação sobre a máquina subjacente e/ou o seu sistema operativo. O tuplo tem cinco campos pela seguinte ordem, cada um sendo uma string:

  • sysname – O nome do sistema subjacente

  • nodename – O nome de rede (pode ser igual a sysname)

  • release – A versão do sistema subjacente

  • version – A versão do MicroPython e a data de compilação

  • machine – Um identificador do hardware subjacente (por exemplo, placa, CPU)

os.urandom(n: int) → bytes

Devolve um objeto de bytes com n bytes aleatórios. A fonte é criptograficamente adequada em todas as câmaras suportadas, embora a implementação varie por porta:

  • Câmaras STM32 (M4, M7, H7, H7+, PT, N6) utilizam o periférico RNG de hardware do STM32.

  • Câmaras i.MX RT1062 (RT1060) utilizam o TRNG de hardware do chip.

  • Câmaras Alif Ensemble (AE3) utilizam o serviço de números aleatórios de hardware do Secure Enclave.

  • Arduino Nano 33 BLE Sense utiliza o periférico RNG de hardware do nRF52.

  • Arduino Nano RP2040 Connect não tem TRNG de hardware; o PRNG do pico-sdk é inicializado e continuamente re-misturado com as fontes de entropia internas do RP2040.

Acesso ao sistema de ficheiros

os.chdir(path: str) → None

Muda o diretório atual.

os.getcwd() → str

Obtém o diretório atual.

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

Esta função devolve um iterador que produz tuplos correspondentes às entradas do diretório que está a listar. Sem argumento, lista o diretório atual; caso contrário, lista o diretório indicado em dir.

Os tuplos têm a forma (name, type, inode[, size]):

  • name é uma string (ou bytes se dir for um objeto de bytes) e é o nome da entrada;

  • type é um inteiro que especifica o tipo da entrada, sendo 0x4000 para diretórios e 0x8000 para ficheiros regulares;

  • inode é um inteiro correspondente ao inode do ficheiro, podendo ser 0 para sistemas de ficheiros que não possuem esse conceito.

  • size é um inteiro que pode ser incluído dependendo do tipo de sistema de ficheiros. Para entradas de ficheiros, size representa o tamanho do ficheiro ou -1 se desconhecido. O seu significado está atualmente indefinido para entradas de diretórios.

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

Sem argumento, lista o diretório atual. Caso contrário, lista o diretório indicado.

os.mkdir(path: str) → None

Cria um novo diretório.

os.remove(path: str) → None

Remove um ficheiro.

Remove um ficheiro. É um alias para remove().

os.rmdir(path: str) → None

Remove um diretório.

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

Renomeia um ficheiro.

os.stat(path: str) → Tuple

Obtém o estado de um ficheiro ou diretório.

os.statvfs(path: str) → Tuple

Obtém o estado de um sistema de ficheiros.

Devolve um tuplo com as informações do sistema de ficheiros pela seguinte ordem:

  • f_bsize – Tamanho do bloco do sistema de ficheiros

  • f_frsize – Tamanho do fragmento

  • f_blocks – Tamanho do sistema de ficheiros em unidades f_frsize

  • f_bfree – Número de blocos livres

  • f_bavail – Número de blocos livres para utilizadores sem privilégios

  • f_files – Número de inodes

  • f_ffree – Número de inodes livres

  • f_favail – Número de inodes livres para utilizadores sem privilégios

  • f_flag – Flags de montagem

  • f_namemax – Comprimento máximo do nome de ficheiro

Os parâmetros relacionados com inodes: f_files, f_ffree, f_favail e o parâmetro f_flag podem devolver 0 pois podem não estar disponíveis numa implementação específica de porta.

os.sync() → None

Sincroniza todos os sistemas de ficheiros.

os.sep: str

O separador de componentes de caminho utilizado pelo sistema de ficheiros, a string '/'.

Redirecionamento e duplicação do terminal

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

Duplica ou comuta o terminal MicroPython (o REPL) para o objeto do tipo stream indicado. O argumento stream_object deve ser um objeto de stream nativo, ou derivar de io.IOBase e implementar os métodos readinto() e write(). O stream deve estar em modo não bloqueante e readinto() deve devolver None se não houver dados disponíveis para leitura.

Após chamar esta função, toda a saída do terminal é repetida neste stream, e qualquer entrada disponível no stream é passada para a entrada do terminal.

O parâmetro index deve ser um inteiro não negativo e especifica qual a ranhura de duplicação a definir. Uma determinada porta pode implementar mais de uma ranhura (a ranhura 0 estará sempre disponível) e, nesse caso, a entrada e saída do terminal são duplicadas em todas as ranhuras definidas.

Se None for passado como stream_object, a duplicação é cancelada na ranhura indicada por index.

A função devolve o objeto do tipo stream anterior na ranhura indicada.

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

Notifica o REPL do MicroPython que existe entrada disponível num objeto do tipo stream previamente registado via os.dupterm().

Esta função deve ser chamada por implementações de stream personalizadas (por exemplo, UART, Bluetooth ou outros streams REPL não-USB) para informar o REPL de que a entrada está pronta para ser lida. A utilização correta garante que caracteres especiais como Ctrl+C (utilizado para acionar KeyboardInterrupt) sejam processados prontamente pelo REPL, permitindo o comportamento de interrupção esperado para o código do utilizador.

O parâmetro obj_in é ignorado por os.dupterm_notify(), mas é necessário para permitir chamar dupterm_notify a partir de um handler de interrupção como UART.irq().

Exemplo:

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

Nota

Se a função dupterm_notify() não for chamada, a entrada do stream personalizado pode não ser detetada ou processada até ao próximo polling do REPL, podendo atrasar KeyboardInterrupts ou outros sinais de controlo. Isto é especialmente importante para UART, Bluetooth e outras ligações REPL não-padrão, onde a notificação automática não é garantida.

Montagem do sistema de ficheiros

As seguintes funções e classes foram movidas para o módulo vfs. São fornecidas neste módulo apenas por razões de compatibilidade com versões anteriores e serão removidas na versão 2 do MicroPython.

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

Monta o objeto de sistema de ficheiros fsobj na localização do VFS indicada pela string mount_point. fsobj pode ser um objeto VFS com um método mount(), ou um dispositivo de blocos. Se for um dispositivo de blocos, o tipo de sistema de ficheiros é detetado automaticamente (é lançada uma exceção se não for reconhecido nenhum sistema de ficheiros). mount_point pode ser '/' para montar fsobj na raiz, ou '/<name>' para montá-lo num subdiretório abaixo da raiz.

Se readonly for True, o sistema de ficheiros é montado em modo de apenas leitura.

Durante o processo de montagem, o método mount() é chamado no objeto do sistema de ficheiros.

Lança OSError(EPERM) se mount_point já estiver montado.

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

Sem argumentos para mount(), devolve uma lista de tuplos que representam todos os pontos de montagem ativos.

A lista devolvida tem a forma [(fsobj, mount_point), …].

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

Desmonta um sistema de ficheiros. mount_point pode ser uma string com o nome da localização de montagem, ou um objeto de sistema de ficheiros previamente montado. Durante o processo de desmontagem, o método umount() é chamado no objeto do sistema de ficheiros.

Lança OSError(EINVAL) se mount_point não for encontrado.

class os.VfsFat(block_dev: AbstractBlockDev)

Cria um objeto de sistema de ficheiros que utiliza o formato FAT. O armazenamento do sistema de ficheiros FAT é fornecido por block_dev. Os objetos criados por este construtor podem ser montados com mount().

static mkfs(block_dev: AbstractBlockDev) → None

Constrói um sistema de ficheiros FAT em block_dev.

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

Cria um objeto de sistema de ficheiros que acede ao sistema de ficheiros POSIX do anfitrião. Se root for especificado, deve ser um caminho no sistema de ficheiros do anfitrião a utilizar como raiz do objeto VfsPosix. Caso contrário, é utilizado o diretório atual do sistema de ficheiros do anfitrião.

Nota

VfsPosix só está disponível na porta Unix; não está presente na OpenMV Cam.