os — serviços básicos de “sistema operacional”

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

Funções gerais

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

Retorna uma tupla (possivelmente uma tupla nomeada) contendo informações sobre a máquina subjacente e/ou seu sistema operacional. A tupla tem cinco campos na seguinte ordem, sendo cada um deles 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 para o hardware subjacente (por exemplo, placa, CPU)

os.urandom(n: int) → bytes

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

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

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

  • Câmeras Alif Ensemble (AE3) usam o serviço de aleatoriedade de hardware do Secure Enclave.

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

  • Arduino Nano RP2040 Connect não possui TRNG de hardware; o PRNG do pico-sdk é semeado e continuamente remisturado com as fontes de entropia internas do RP2040.

Acesso ao sistema de arquivos

os.chdir(path: str) → None

Altera o diretório atual.

os.getcwd() → str

Obtém o diretório atual.

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

Esta função retorna um iterador que então produz tuplas correspondentes às entradas do diretório que está sendo listado. Sem argumento, ela lista o diretório atual; caso contrário, lista o diretório indicado por dir.

As tuplas têm a forma (name, type, inode[, size]):

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

  • type é um inteiro que especifica o tipo da entrada, com 0x4000 para diretórios e 0x8000 para arquivos comuns;

  • inode é um inteiro correspondente ao inode do arquivo, e pode ser 0 para sistemas de arquivos que não possuem tal noção.

  • size é um inteiro que pode ser incluído dependendo do tipo de sistema de arquivos. Para entradas de arquivo, size representa o tamanho do arquivo ou -1 se desconhecido. Seu significado é atualmente indefinido para entradas de diretório.

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

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

os.mkdir(path: str) → None

Cria um novo diretório.

os.remove(path: str) → None

Remove um arquivo.

Remove um arquivo. Este é um alias para remove().

os.rmdir(path: str) → None

Remove um diretório.

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

Renomeia um arquivo.

os.stat(path: str) → Tuple

Obtém o status de um arquivo ou diretório.

os.statvfs(path: str) → Tuple

Obtém o status de um sistema de arquivos.

Retorna uma tupla com as informações do sistema de arquivos na seguinte ordem:

  • f_bsize – Tamanho do bloco do sistema de arquivos

  • f_frsize – Tamanho do fragmento

  • f_blocks – Tamanho do sistema de arquivos em unidades de f_frsize

  • f_bfree – Número de blocos livres

  • f_bavail – Número de blocos livres para usuários sem privilégios

  • f_files – Número de inodes

  • f_ffree – Número de inodes livres

  • f_favail – Número de inodes livres para usuários sem privilégios

  • f_flag – Flags de montagem

  • f_namemax – Comprimento máximo do nome de arquivo

Parâmetros relacionados a inodes: f_files, f_ffree, f_favail e o parâmetro f_flag podem retornar 0, pois podem estar indisponíveis em uma implementação específica do port.

os.sync() → None

Sincroniza todos os sistemas de arquivos.

os.sep: str

O separador de componentes de caminho usado pelo sistema de arquivos, a string '/'.

Redirecionamento e duplicação do terminal

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

Duplica ou alterna o terminal do MicroPython (o REPL) para o objeto semelhante a stream fornecido. O argumento stream_object deve ser um objeto 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 retornar 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 é repassada à entrada do terminal.

O parâmetro index deve ser um inteiro não negativo e especifica qual slot de duplicação é configurado. Um determinado port pode implementar mais de um slot (o slot 0 sempre estará disponível) e, nesse caso, a entrada e a saída do terminal são duplicadas em todos os slots configurados.

Se None for passado como stream_object, a duplicação é cancelada no slot indicado por index.

A função retorna o objeto semelhante a stream anterior no slot fornecido.

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

Notifica o REPL do MicroPython de que há entrada disponível em um objeto semelhante a stream previamente registrado via os.dupterm().

Esta função deve ser chamada por implementações personalizadas de stream (por exemplo, UART, Bluetooth ou outros streams de REPL não USB) para informar ao REPL que a entrada está pronta para ser lida. O uso correto garante que caracteres especiais como Ctrl+C (usado para disparar KeyboardInterrupt) sejam processados prontamente pelo REPL, possibilitando o comportamento de interrupção esperado para o código do usuário.

O parâmetro obj_in é ignorado por os.dupterm_notify(), mas é necessário para permitir chamar dupterm_notify a partir de um manipulador 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 detectada ou processada até a próxima sondagem do REPL, potencialmente atrasando KeyboardInterrupts ou outros sinais de controle. Isso é especialmente importante para UART, Bluetooth e outras conexões de REPL não padronizadas, onde a notificação automática não é garantida.

Montagem do sistema de arquivos

As funções e classes a seguir foram movidas para o módulo vfs. Elas são fornecidas neste módulo apenas para compatibilidade retroativa 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 arquivos fsobj no local do VFS indicado pela string mount_point. fsobj pode ser um objeto VFS que possua um método mount() ou um dispositivo de bloco. Se for um dispositivo de bloco, o tipo de sistema de arquivos é detectado automaticamente (uma exceção é lançada se nenhum sistema de arquivos for reconhecido). mount_point pode ser '/' para montar fsobj na raiz, ou '/<name>' para montá-lo em um subdiretório sob a raiz.

Se readonly for True, o sistema de arquivos é montado somente leitura.

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

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

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

Sem argumentos para mount(), retorna uma lista de tuplas representando todos os pontos de montagem ativos.

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

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

Desmonta um sistema de arquivos. mount_point pode ser uma string nomeando o local de montagem, ou um objeto de sistema de arquivos previamente montado. Durante o processo de desmontagem, o método umount() é chamado no objeto de sistema de arquivos.

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

class os.VfsFat(block_dev: AbstractBlockDev)

Cria um objeto de sistema de arquivos que usa o formato de sistema de arquivos FAT. O armazenamento do sistema de arquivos FAT é fornecido por block_dev. Objetos criados por este construtor podem ser montados usando mount().

static mkfs(block_dev: AbstractBlockDev) → None

Constrói um sistema de arquivos FAT em block_dev.

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

Cria um objeto de sistema de arquivos que acessa o sistema de arquivos POSIX do host. Se root for especificado, ele deve ser um caminho no sistema de arquivos do host a ser usado como raiz do objeto VfsPosix. Caso contrário, é usado o diretório atual do sistema de arquivos do host.

Nota

VfsPosix está disponível apenas no port Unix; não está presente na OpenMV Cam.